Java擴充套件Nginx之五：五大handler(系列最核心)
2023-07-15 09:00:36
歡迎存取我的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) | [email protected]: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的主要能力已經熟悉，接下來的章節會繼續深入挖掘，歡迎繼續關注欣宸原創