Java扩展Nginx之五：五大handler(系列最核心)

欢迎访问我的GitHub

这里分类和汇总了欣宸的全部原创(含配套源码)：https://github.com/zq2599/blog_demos

本篇概览

本文是《Java扩展Nginx》系列的第五篇，如题，本篇是整个系列的最核心内容，咱们写的代码主要都集中在nginx-clojure定义的五种handler中，不同handler分别发挥着各自的作用，它们是：

Initialization Handler for nginx worker（初始化）
Content Ring Handler for Location（location对应的业务处理）
Nginx Rewrite Handler（地址重定向）
Nginx Access Handler（鉴权）
Nginx Log Handler（日志输出）

接下来，一起在实战中学习它们

源码下载

《Java扩展Nginx》的完整源码可在GitHub下载到，地址和链接信息如下表所示(https://github.com/zq2599/blog_demos)：

名称	链接	备注
项目主页	https://github.com/zq2599/blog_demos	该项目在GitHub上的主页
git仓库地址(https)	https://github.com/zq2599/blog_demos.git	该项目源码的仓库地址，https协议
git仓库地址(ssh)	git@github.com:zq2599/blog_demos.git	该项目源码的仓库地址，ssh协议

这个git项目中有多个文件夹，本篇的源码在nginx-clojure-tutorials文件夹下的handler-demo子工程中，如下图红框所示：
本篇涉及到nginx.conf的修改，完整的参考在此：https://raw.githubusercontent.com/zq2599/blog_demos/master/nginx-clojure-tutorials/files/nginx.conf

maven工程

新建名为handler-demo的maven工程，今天实战的代码都在这里面
我这里为了统一管理代码和依赖库，整个《Java扩展Nginx》系列的源码都放在父工程nginx-clojure-tutorials下面，本篇的handler-demo也是nginx-clojure-tutorials的一个子工程
接下来，编码实战每种handler

Initialization Handler for nginx worker（初始化）

Initialization Handler，顾名思义，是用于执行初始化逻辑的handler，它在nginx配置中是http级别的，有以下几个特性：

每个worker都是独立的进程，启动的时候都会调用一次Initialization Handler
Initialization Handler也是NginxJavaRingHandler接口的实现类，其invoke方法会被调用，所以初始化逻辑代码应该写在invoke方法中

接下来写代码试试，新增MyInitHandler.java，代码如下：

package com.bolingcavalry.handlerdemo;

import nginx.clojure.NginxClojureRT;
import nginx.clojure.java.NginxJavaRingHandler;
import java.io.IOException;
import java.util.Map;

public class MyInitHandler implements NginxJavaRingHandler {
    @Override
    public Object[] invoke(Map<String, Object> map) throws IOException {
        // 可以根据实际需求执行初始化操作，这里作为演示，只打印日志
        NginxClojureRT.log.info("MyInitHandler.invoke executed");
        return null;
    }
}

用命令mvn clean package -U，生成名为handler-demo-1.0-SNAPSHOT.jar的文件，将其放入nginx的jars目录下
再在nginx.conf的http配置中增加以下两行配置：

jvm_handler_type 'java';
jvm_init_handler_name 'com.bolingcavalry.handlerdemo.MyInitHandler';

重启nginx，打开logs/error.log文件，发现里面新增一行日志，这就是初始化日志：

2022-02-05 23:02:37[info][73954][main]MyInitHandler.invoke executed

如果之前部署的location还在，可以用postman发请求试试，应该可以正常响应，表示nginx的worker已经正常工作：

Content Ring Handler for Location（location对应的业务处理）

content handler是最常用的handler，这是个location配置，定义了nginx收到某个请求后应该如何处理，前面的文章中已经用到了
现在咱们再写一个content handler，与之前不同的是新增了配置项content_handler_property，该配置项可以添加自定义配置，整个location如下所示：

location /contentdemo {
	# 第一个自定义属性
    content_handler_property foo.name 'foo.value';
   # 第二个自定义属性
   content_handler_property bar.name 'bar.value';
   # 逻辑处理类
   content_handler_name 'com.bolingcavalry.handlerdemo.MyContentHandler';
}

从上面的配置可见，通过content_handler_property增加了两个配置项，名字分别是foo.name和bar.name
再来看MyContentHandler类的源码，重点是实现了Configurable接口，然后在config方法被调用的时候，入参map中保存的就是content_handler_property配置的key和value了，在invoke方法中可以直接使用：

package com.bolingcavalry.handlerdemo;

import nginx.clojure.Configurable;
import nginx.clojure.java.ArrayMap;
import nginx.clojure.java.NginxJavaRingHandler;
import java.io.IOException;
import java.time.LocalDateTime;
import java.util.Map;
import static nginx.clojure.MiniConstants.CONTENT_TYPE;
import static nginx.clojure.MiniConstants.NGX_HTTP_OK;

public class MyContentHandler implements NginxJavaRingHandler, Configurable {

    private Map<String, String> config;

    /**
     * location中配置的content_handler_property属性会通过此方法传给当前类
     * @param map
     */
    @Override
    public void config(Map<String, String> map) {
        this.config = map;
    }

    @Override
    public Object[] invoke(Map<String, Object> map) throws IOException {

        String body = "From MyContentHandler, "
                    + LocalDateTime.now()
                    + ", foo : "
                    + config.get("foo.name")
                    + ", bar : "
                    + config.get("bar.name");

        return new Object[] {
                NGX_HTTP_OK, //http status 200
                ArrayMap.create(CONTENT_TYPE, "text/plain"), //headers map
                body
        };
    }
}

编译、配置、重启nginx，再用postman访问/contentdemo，响应如下，可见符合预期，content_handler_property配置的值可以在invoke方法中使用：

Nginx Rewrite Handler（地址重定向）

rewrite handler顾名思义，就是咱们常在nginx上配置的rewrite功能，在nginx-clojure中又略有不同，为了方便记忆，这里将整个rewrite分为三段处理：
- 下面就是一个完整的rewrite handler，这些内容都是写在http配置内的：

# 1. 定义变量，用于保存路径
set $myhost "";
       
location /myproxy {
	rewrite_handler_type 'java';
	# 2. java代码中为变量赋值
    rewrite_handler_name 'com.bolingcavalry.handlerdemo.MyRewriteProxyPassHandler';
     # 3. 用变量的值作为地址进行跳转
     proxy_pass $myhost;
}

对应的MyRewriteProxyPassHandler.java如下：

package com.bolingcavalry.handlerdemo;

import nginx.clojure.NginxClojureRT;
import nginx.clojure.java.NginxJavaRequest;
import nginx.clojure.java.NginxJavaRingHandler;
import java.util.Map;
import static nginx.clojure.java.Constants.PHASE_DONE;

public class MyRewriteProxyPassHandler implements NginxJavaRingHandler {
    @Override
    public Object[] invoke(Map<String, Object> req) {
        // 根据业务情况定制计算出的path
        String myhost = computeMyHost(req);
        // 用setVariable方法设置myhost变量的值，这个myhost在这个location中被定义，跳转的时候就用这个值作为path
        ((NginxJavaRequest)req).setVariable("myhost", myhost);
        // 返回PHASE_DONE之后，nginx-clojure框架就会执行proxy_pass逻辑，
        // 如果返回的不是PHONE_DONE，nginx-clojure框架就把这个handler当做content handler处理
        return PHASE_DONE;
    }

    /**
     * 这里写入业务逻辑，根据实际情况确定返回的path
     * @param req
     * @return
     */
    private String computeMyHost(Map<String, Object> req) {
        // 确认是http还是https
        String scheme = (String)req.get("scheme");
        // 确认端口号
        String serverPort = (String)req.get("server-port");

        // /contentdemo是nginx.conf中配置的一个location，您可以根据自己的业务情况来决定返回值
        String myhost = scheme + "://127.0.0.1:" + serverPort + "/contentdemo";

        NginxClojureRT.log.info("pass address [" + myhost + "]");

        return myhost;
    }
}

编译构建运行起来，用postman访问/myproxy，效果如下图，从返回结果可见请求被成功转发到/contentdemo：
此刻，相信聪明的您应该想到了：既然rewrite handler的逻辑代码可以自己用java写，那意味着可以按照自己的业务需求随意定制，那岂不是自己可以在nginx上写一个负载均衡的功能出来了？没错，从下图可见官方也是这么说的：
- 如果您的环境中有注册中心，例如eureka或者nacos，您还可以取得后台服务列表，这样，不光是负载均衡，各种转发调度逻辑都可以在nginx上开发出来了
还有一点要注意的，下图是刚才写的MyRewriteProxyPassHandler.java的源码，注意红框位置，是invoke方法的返回值，如果返回的不是PHASE_DONE，nginx-clojure框架就不再执行后面poss_proxy操作，而是把此handler当做普通的content handler来处理了：

Nginx Access Handler（鉴权）

access handler的定位，是用于执行鉴权相关的逻辑
其实看过了前面的rewrite handler，聪明的您应该会想到：rewrite handler既可以重定向，也可以直接返回code和body，那岂不是直接用来做鉴权？鉴权不通过就在rewrite handler上返回401 （Unauthorized）或者403 （Forbidden）
从技术实现的角度来看，您说得没错，access handler来自nginx-clojure对功能和职责的划分，官方建议将鉴权的工作都交给access handler来做：
正常情况下，一次请求被前面几种handler执行的顺序如下：
写一个access handler的配置和代码验证试试，为了省事儿，就在前面rewrite handler的基础上改动吧
首先是配置，如下所示，在刚才的rewrite handler的配置中，增加了access_handler_type和access_handler_name，这就意味着该location的请求，先由MyRewriteProxyPassHandler处理，再交给BasicAuthHandler处理，如果鉴权通过，才会交给proxy_pass处理：

# 1. 定义变量，用于保存路径
set $myhost "";
       
location /myproxy {
	# 指定access handler的类型是java
    access_handler_type 'java';
    # 指定access handler的执行类类
    access_handler_name 'com.bolingcavalry.handlerdemo.BasicAuthHandler';

    rewrite_handler_type 'java';
    # 2. java代码中为变量赋值
    rewrite_handler_name 'com.bolingcavalry.handlerdemo.MyRewriteProxyPassHandler';
    # 3. 用变量的值作为地址进行跳转
    proxy_pass $myhost;
}

BasicAuthHandler.java的内容如下，已添加详细注释，就不多赘述了：

package com.bolingcavalry.handlerdemo;

import nginx.clojure.java.ArrayMap;
import nginx.clojure.java.NginxJavaRingHandler;
import javax.xml.bind.DatatypeConverter;
import java.util.Map;
import static nginx.clojure.MiniConstants.DEFAULT_ENCODING;
import static nginx.clojure.MiniConstants.HEADERS;
import static nginx.clojure.java.Constants.PHASE_DONE;

public  class BasicAuthHandler implements NginxJavaRingHandler {

    @Override
    public Object[] invoke(Map<String, Object> request) {
        // 从header中获取authorization字段
        String auth = (String) ((Map)request.get(HEADERS)).get("authorization");

        // 如果header中没有authorization，就返回401错误，并带上body
        if (auth == null) {
            return new Object[] { 401, ArrayMap.create("www-authenticate", "Basic realm=\"Secure Area\""),
                    "<HTML><BODY><H1>401 Unauthorized.</H1></BODY></HTML>" };
        }

        // authorization应该是 : Basic xfeep:hello!，所以这里先将"Basic "去掉，然后再用":"分割
        String[] up = auth.substring("Basic ".length()).split(":");

        // 只是为了演示，所以账号和密码的检查逻辑在代码中是写死的，
        // 如果账号等于"xfeep"，并且密码等于"hello!"，就返回PHASE_DONE，这样nginx-clojure就会继续执行后面的content handler
        if (up[0].equals("xfeep") && up[1].equals("hello!")) {
            return PHASE_DONE;
        }

        // 如果账号密码校验不过，就返回401，body内容是提示账号密码不过
        return new Object[] { 401, ArrayMap.create("www-authenticate", "Basic realm=\"Secure Area\""),
                "<HTML><BODY><H1>401 Unauthorized BAD USER & PASSWORD.</H1></BODY></HTML>" };
    }
}

编译构建部署之后，咱们来试试效果，用postman再次请求/myproxy，因为header中没有authorization字段，所以返回401错误：
然后在header中增加一个属性，如下图红框，名字authorization，值Basic xfeep:hello!，再发一次请求，蓝框中显示返回码正常，并且返回内容也是重定向后的location生成的：
然后故意用错误的密码试试，如下图，鉴权未通过，并且返回body准确描述了具体的错误信息：

Nginx Log Handler（日志输出）

最后一个handler是作为辅助作用的日志输出，尽管在其他handler中，我们可以直接调用NginxClojureRT.log方法将日志输出到error.log文件中，但还是可以猜出官方定义Log Handler的用意：

明确划分各个handler的职责
让日志与业务功能解耦合，让Log Handler做纯粹的日志输出工作
日志模块偏向于组件化，各个location可以按照需求选择用或者不用，而且还可以设计成多个location复用

另外Log Handler也有属于自己的特性：

依旧是NginxJavaRingHandler接口的实现，invoke方法被执行的时机是request被销毁前
有专用的配置属性log_handler_property
invoke方法的返回值无意义，会被nginx-clojure忽略

接下来通过实例学习log handler，找到前面的content handler的demo，给它加上日志输出试试，将配置文件修改如下，可见增加了log_handler_name用于指定日志输出的执行类，另外还有两个log_handler_property配置项作为自定义属性传入：

       location /contentdemo {
         # 第一个自定义属性
         content_handler_property foo.name 'foo.value';
         # 第二个自定义属性
         content_handler_property bar.name 'bar.value';
         content_handler_name 'com.bolingcavalry.handlerdemo.MyContentHandler';

         # log handler类型是java
         log_handler_type java;
         # log handler的执行类
         log_handler_name 'com.bolingcavalry.handlerdemo.MyLogHandler';
         # 自定义属性，在MyLogHandler中作为是否打印User Agent的开关
         log_handler_property log.user.agent on;
         # 自定义属性，在MyLogHandler中作为日志目录
         log_handler_property log.file.path logs/contentdemo.log;
       }

对应的MyLogHandler.java，有几处要注意的地方稍后会提到：

package com.bolingcavalry.handlerdemo;

import nginx.clojure.Configurable;
import nginx.clojure.NginxClojureRT;
import nginx.clojure.java.NginxJavaRequest;
import nginx.clojure.java.NginxJavaRingHandler;
import java.io.File;
import java.io.FileOutputStream;
import java.io.IOException;
import java.util.Map;

public class MyLogHandler implements NginxJavaRingHandler, Configurable {

    /**
     * 是否将User Agent打印在日志中
     */
    private boolean logUserAgent;

    /**
     * 日志文件路径
     */
    private String filePath;

    @Override
    public Object[] invoke(Map<String, Object> request) throws IOException {
        File file = new File(filePath);
        NginxJavaRequest r = (NginxJavaRequest) request;
        try (FileOutputStream out = new FileOutputStream(file, true)) {
            String msg = String.format("%s - %s [%s] \"%s\" %s \"%s\" %s %s\n",
                    r.getVariable("remote_addr"),
                    r.getVariable("remote_user", "x"),
                    r.getVariable("time_local"),
                    r.getVariable("request"),
                    r.getVariable("status"),
                    r.getVariable("body_bytes_sent"),
                    r.getVariable("http_referer", "x"),
                    logUserAgent ? r.getVariable("http_user_agent") : "-");
            out.write(msg.getBytes("utf8"));
        }
        return null;
    }

    @Override
    public void config(Map<String, String> properties) {
        logUserAgent = "on".equalsIgnoreCase(properties.get("log.user.agent"));
        filePath = properties.get("log.file.path");
        NginxClojureRT.log.info("MyLogHandler, logUserAgent [" + logUserAgent + "], filePath [" + filePath + "]");
    }

    // 下面这段代码来自官方demo，实测发现这段代码在打印日志的逻辑中并未发挥作用，
    // 不论是否删除，日志输出的内容都是相同的
    /*
    @Override
    public String[] variablesNeedPrefetch() {
        return new String[] { "remote_addr", "remote_user", "time_local", "request", "status", "body_bytes_sent",
                "http_referer", "http_user_agent" };
    }
    */
}

上述代码中，有下面几处地方要注意：

以上代码来自官方demo，我这里做了点小的改动(主要是文件路径改为外部参数传入)
整体功能是取出请求和响应的一些参数，打印在日志文件中
logUserAgent参数控制了user agent是否打印，这个比较实用，可以通过配置来做一些开关控制
这个demo不要用于生产环境，从代码可以看出，每一次请求都做了一次io操作，这是存在性能隐患的，官方的demo只是展示log handler的作用而已，看看就好
variablesNeedPrefetch方法的代码被我注释掉了，因为实际尝试发现不论这段代码是否存在，都不回影响日志的输出，去看源码也没弄明白...（水平有限，望理解），于是就注释掉了，毕竟只要日志输出正常就行

编译构建部署运行，先看logs/error.log，如下，可见MyLogHandler成功的接收到了配置项的值：

2022-02-08 08:59:22[info][69035][main]MyLogHandler, logUserAgent [true], filePath [logs/contentdemo.log]

再用postman请求/contentdemo试试，如下图，首先确保响应和之前一致，证明log handler不影响主业务：
去logs目录下查看，发现新增了contentdemo.log文件，内容如下，postman自带的header参数已经被成功获取并打印在日志中了：

127.0.0.1 - x [08/Feb/2022:09:45:36 +0800] "GET /contentdemo HTTP/1.1" 200 "80" x PostmanRuntime/7.29.0

至此，五大handler咱们已经全部实战体验过了，对nginx-clojure的主要能力已经熟悉，接下来的章节会继续深入挖掘，欢迎继续关注欣宸原创

欢迎关注博客园：程序员欣宸

学习路上，你不孤单，欣宸原创一路相伴...

posted @ 2023-07-15 07:57 程序员欣宸 Views(581) Comments(0) Edit 收藏举报

刷新页面返回顶部

zq2599

Java扩展Nginx之五：五大handler(系列最核心)

欢迎访问我的GitHub

本篇概览

源码下载

maven工程

Initialization Handler for nginx worker（初始化）

Content Ring Handler for Location（location对应的业务处理）

Nginx Rewrite Handler（地址重定向）

Nginx Access Handler（鉴权）

Nginx Log Handler（日志输出）

欢迎关注博客园：程序员欣宸

公告