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

欢迎访问我的GitHub

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

本篇概览

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

1. Initialization Handler for nginx worker（初始化）
2. Content Ring Handler for Location（location对应的业务处理）
3. Nginx Rewrite Handler（地址重定向）
4. Nginx Access Handler（鉴权）
5. 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级别的，有以下几个特性：

1. 每个worker都是独立的进程，启动的时候都会调用一次Initialization Handler
2. 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的用意：

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

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

1. 依旧是NginxJavaRingHandler接口的实现，invoke方法被执行的时机是request被销毁前
2. 有专用的配置属性log_handler_property
3. 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" };
    }
    */
}

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

1. 以上代码来自官方demo，我这里做了点小的改动(主要是文件路径改为外部参数传入)
2. 整体功能是取出请求和响应的一些参数，打印在日志文件中
3. logUserAgent参数控制了user agent是否打印，这个比较实用，可以通过配置来做一些开关控制
4. 这个demo不要用于生产环境，从代码可以看出，每一次请求都做了一次io操作，这是存在性能隐患的，官方的demo只是展示log handler的作用而已，看看就好
5. 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的主要能力已经熟悉，接下来的章节会继续深入挖掘，欢迎继续关注欣宸原创

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

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