多级缓存实战（一）：OpenResty、Lua 与 Tomcat 集群

1. 本阶段要解决什么问题#

前面的进程缓存由 Java 应用直接维护。为了进一步减少请求进入 Java 进程的次数，可以把缓存和请求编排前移到 Nginx：

flowchart LR U["浏览器 / 前端"] --> N1["入口 Nginx :80"] N1 --> OR["OpenResty :8081"] OR --> T1["Tomcat :8081"] OR --> T2["Tomcat :8082"] T1 --> DB[("MySQL")] T2 --> DB

本阶段先不接 Redis，只完成以下链路：

前端访问 /api/item/{id}。
OpenResty 用 Lua 解析商品 ID。
Lua 分别请求 Tomcat 的商品接口和库存接口。
将两个 JSON 结果拼成前端需要的响应。
相同 URI 尽量落到相同 Tomcat 节点，提高该节点进程缓存的命中率。

2. OpenResty 是什么#

OpenResty 是基于 Nginx 和 LuaJIT 的 Web 平台。它把 Lua 执行阶段嵌入 Nginx 的事件模型，因此可以在 Nginx 内完成鉴权、限流、缓存查询、请求聚合和路由等逻辑。

需要明确两点：

Lua 代码运行在 Nginx worker 中，不应执行阻塞式 I/O。
同一个 worker 内，请求可能复用已加载的 Lua 模块；应避免使用可变全局变量保存请求状态。

3. 安装与目录#

采用 CentOS 7 和 YUM 仓库安装，实际部署时应使用与你的操作系统和 OpenResty 版本匹配的官方安装方式。

课程中的核心命令如下：

1
yum install -y yum-utils
2
yum-config-manager --add-repo https://openresty.org/package/centos/openresty.repo
3
yum install -y openresty
4
yum install -y openresty-opm

常见目录：

1
/usr/local/openresty/
2
├── nginx/
3
│   ├── conf/nginx.conf
4
│   ├── html/
5
│   └── logs/
6
└── lualib/

验证安装：

1
openresty -V
2
resty -V

配置修改后的安全检查顺序：

1
openresty -t
2
openresty -s reload

如果系统中的可执行文件叫 nginx，则使用：

1
nginx -t
2
nginx -s reload

不要跳过 -t。配置语法错误时直接 reload，可能导致新 worker 无法启动。

4. 配置 Lua 模块搜索路径#

在 nginx.conf 的 http 块中配置：

1
http {
2
    lua_package_path "/usr/local/openresty/lualib/?.lua;;";
3
    lua_package_cpath "/usr/local/openresty/lualib/?.so;;";
4

5
    # 其余配置……
6
}

说明：

lua_package_path：查找 Lua 源码模块。
lua_package_cpath：查找 Lua C 扩展模块。
?.lua 中的 ? 会被模块名替换。
末尾 ;; 表示保留 Lua 原有的默认搜索路径。

课程文档曾出现 /usr/loca/openresty/...，正确路径是 /usr/local/openresty/...。

5. 第一个 OpenResty 接口#

在 server 中配置：

1
server {
2
    listen 8081;
3
    server_name _;
4

5
    location /api/item {
6
        default_type application/json;
7
        content_by_lua_file lua/item.lua;
8
    }
9
}

创建 lua/item.lua：

1
ngx.say('{"id":10001,"name":"示例商品"}')

访问：

1
curl -i http://localhost:8081/api/item

content_by_lua_file 表示响应内容由 Lua 文件生成。ngx.say 会输出内容并追加换行；若不希望追加换行，可使用 ngx.print。

6. 接收请求参数#

6.1 路径参数#

将 location 改为正则匹配：

1
location ~ ^/api/item/(\d+)$ {
2
    default_type application/json;
3
    content_by_lua_file lua/item.lua;
4
}

Lua 中读取第一个捕获组：

1
local id = ngx.var[1]
2
ngx.say("商品 ID：", id)

ngx.var[1] 得到的是字符串。如果要参与数值运算，应显式转换：

1
local id = tonumber(ngx.var[1])
2
if not id then
3
    ngx.status = ngx.HTTP_BAD_REQUEST
4
    ngx.say('{"message":"非法商品 ID"}')
5
    return
6
end

6.2 常见参数 API#

参数位置	Lua API	说明
正则路径捕获	`ngx.var[1]`	对应 location 正则中的第一个括号
请求头	`ngx.req.get_headers()`	返回 table
GET 查询参数	`ngx.req.get_uri_args()`	例如 `?page=1`
POST 表单	`ngx.req.read_body()` + `ngx.req.get_post_args()`	先读取请求体
原始请求体	`ngx.req.read_body()` + `ngx.req.get_body_data()`	可用于 JSON

示例：

1
local headers = ngx.req.get_headers()
2
local args = ngx.req.get_uri_args()
3

4
ngx.log(ngx.INFO, "user-agent=", headers["user-agent"] or "")
5
ngx.log(ngx.INFO, "page=", args.page or "1")

读取 JSON 请求体：

1
local cjson = require("cjson.safe")
2

3
ngx.req.read_body()
4
local body = ngx.req.get_body_data()
5
local data, err = cjson.decode(body or "")
6

7
if not data then
8
    ngx.status = ngx.HTTP_BAD_REQUEST
9
    ngx.say(cjson.encode({ message = "JSON 格式错误", detail = err }))
10
    return
11
end

cjson.safe 在解析失败时返回 nil, err，比直接抛异常更适合接口代码。

7. OpenResty 发起内部子请求#

7.1 为什么使用内部 location#

OpenResty 可以通过 ngx.location.capture 发起 Nginx 内部子请求：

1
location /item {
2
    proxy_pass http://item-service;
3
}

Lua：

1
local resp = ngx.location.capture("/item", {
2
    method = ngx.HTTP_GET,
3
    args = { id = 10001 }
4
})

响应对象常用字段：

字段	含义
`resp.status`	HTTP 状态码
`resp.header`	响应头
`resp.body`	响应体字符串
`resp.truncated`	响应体是否被截断

内部子请求不是浏览器重定向，客户端看不到这个过程。

7.2 封装通用 HTTP 函数#

创建 /usr/local/openresty/lualib/common.lua：

1
local _M = {}
2

3
function _M.read_http(path, params)
4
    local resp = ngx.location.capture(path, {
5
        method = ngx.HTTP_GET,
6
        args = params
7
    })
8

9
    if not resp then
10
        return nil, "subrequest failed: no response"
11
    end
12

13
    if resp.status < 200 or resp.status >= 300 then
14
        return nil, "subrequest status: " .. tostring(resp.status)
15
    end
16

17
    if resp.truncated then
18
        return nil, "subrequest body was truncated"
19
    end
20

21
    return resp.body, nil
22
end
23

24
return _M

调用：

1
local common = require("common")
2
local body, err = common.read_http("/item", { id = 10001 })

8. 配置 Tomcat 集群#

假设两个 Java 实例分别监听 8081 和 8082：

1
upstream item-service {
2
    hash $request_uri consistent;
3

4
    server 192.168.150.101:8081;
5
    server 192.168.150.101:8082;
6
}
7

8
server {
9
    listen 8081;
10

11
    location /item {
12
        proxy_pass http://item-service;
13
    }
14

15
    location /item/stock {
16
        proxy_pass http://item-service;
17
    }
18
}

使用：

1
hash $request_uri;

它可以让相同 URI 通常落到相同节点，有助于命中该 JVM 的 Caffeine 进程缓存。这里补充 consistent，因为节点增减时，一致性哈希通常只重新映射少部分 key，而普通哈希可能让大量 key 改变节点。

8.1 为什么用 `$request_uri`#

若商品接口为：

1
/item/10001
2
/item/stock/10001

两个 URI 不同，可能被分配到不同节点。如果 Java 接口使用查询参数并通过统一路径代理：

1
/item?id=10001
2
/item/stock?id=10001

仍然是两个不同 URI。对于当前案例，只要各接口自己的同类请求保持稳定即可；商品和库存不要求落到同一节点，因为它们有各自的缓存。

如果业务确实要求“同一商品的不同接口落在同一节点”，应从 URI 中提取商品 ID，使用统一的哈希 key，而不是机械地使用完整 $request_uri。

9. JSON 编解码#

9.1 编码#

1
local cjson = require("cjson.safe")
2

3
local json, err = cjson.encode({
4
    id = 10001,
5
    name = "手机",
6
    stock = 100
7
})
8

9
if not json then
10
    ngx.log(ngx.ERR, "encode failed: ", err)
11
end

9.2 解码#

1
local data, err = cjson.decode('{"id":10001,"stock":100}')
2
if not data then
3
    ngx.log(ngx.ERR, "decode failed: ", err)
4
    return
5
end
6

7
ngx.say(data.id)

JSON 对象会转成 Lua table；JSON 数组也会转成 table。不要依赖 Lua table 的键遍历顺序。

10. 完整的商品聚合接口#

10.1 Nginx 配置#

1
upstream item-service {
2
    hash $request_uri consistent;
3
    server 192.168.150.101:8081;
4
    server 192.168.150.101:8082;
5
}
6

7
server {
8
    listen 8081;
9
    server_name _;
10

11
    location ~ ^/api/item/(\d+)$ {
12
        default_type application/json;
13
        content_by_lua_file lua/item.lua;
14
    }
15

16
    location /item {
17
        internal;
18
        proxy_pass http://item-service;
19
    }
20

21
    location /item/stock {
22
        internal;
23
        proxy_pass http://item-service;
24
    }
25
}

internal 表示 location 只允许 Nginx 内部请求，外部直接访问会返回 404，避免绕过 API 层。

10.2 `item.lua`#

1
local cjson = require("cjson.safe")
2
local common = require("common")
3

4
local id = tonumber(ngx.var[1])
5
if not id then
6
    ngx.status = ngx.HTTP_BAD_REQUEST
7
    ngx.say(cjson.encode({ message = "非法商品 ID" }))
8
    return
9
end
10

11
local item_json, item_err = common.read_http("/item", { id = id })
12
if not item_json then
13
    ngx.log(ngx.ERR, "read item failed: ", item_err)
14
    ngx.status = ngx.HTTP_BAD_GATEWAY
15
    ngx.say(cjson.encode({ message = "商品服务暂时不可用" }))
16
    return
17
end
18

19
local stock_json, stock_err = common.read_http("/item/stock", { id = id })
20
if not stock_json then
21
    ngx.log(ngx.ERR, "read stock failed: ", stock_err)
22
    ngx.status = ngx.HTTP_BAD_GATEWAY
23
    ngx.say(cjson.encode({ message = "库存服务暂时不可用" }))
24
    return
25
end
26

27
local item, decode_item_err = cjson.decode(item_json)
28
local stock, decode_stock_err = cjson.decode(stock_json)
29

30
if not item or not stock then
31
    ngx.log(
32
        ngx.ERR,
33
        "decode failed, item_err=", decode_item_err or "",
34
        ", stock_err=", decode_stock_err or ""
35
    )
36
    ngx.status = ngx.HTTP_BAD_GATEWAY
37
    ngx.say(cjson.encode({ message = "上游响应格式错误" }))
38
    return
39
end
40

41
item.stock = stock.stock
42
item.sold = stock.sold
43

44
local result, encode_err = cjson.encode(item)
45
if not result then
46
    ngx.log(ngx.ERR, "encode result failed: ", encode_err)
47
    ngx.status = ngx.HTTP_INTERNAL_SERVER_ERROR
48
    ngx.say('{"message":"响应生成失败"}')
49
    return
50
end
51

52
ngx.say(result)

11. 并行请求的补充#

上面的两个 ngx.location.capture 是顺序执行。商品和库存互不依赖时，可使用 ngx.location.capture_multi 并行发起：

1
local responses = {
2
    { "/item", { args = { id = id } } },
3
    { "/item/stock", { args = { id = id } } }
4
}
5

6
local item_resp, stock_resp = ngx.location.capture_multi(responses)

这能减少聚合接口的总等待时间，但代码必须分别检查两个响应的状态、截断标记和 JSON 格式。入门阶段先掌握通用错误处理，再引入并行化。

12. 从浏览器到 Tomcat 的完整请求路径#

前端页面请求：

1
axios.get("/api/item/" + id)

外层 Nginx：

1
upstream nginx-cluster {
2
    server 192.168.150.101:8081;
3
}
4

5
server {
6
    listen 80;
7

8
    location /api {
9
        proxy_pass http://nginx-cluster;
10
    }
11

12
    location / {
13
        root html;
14
        index index.html;
15
    }
16
}

完整链路：

1
浏览器
2
  → 入口 Nginx:80
3
  → OpenResty:8081 的 /api/item/{id}
4
  → Lua 内部请求 /item 与 /item/stock
5
  → Tomcat 集群
6
  → Caffeine / MySQL
7
  → Lua 聚合 JSON
8
  → 浏览器

13. 验证步骤#

13.1 先验证 Java 接口#

1
curl -i "http://192.168.150.101:8081/item?id=10001"
2
curl -i "http://192.168.150.101:8081/item/stock?id=10001"

13.2 再验证 OpenResty 内部链路#

1
curl -i "http://192.168.150.101:8081/api/item/10001"

13.3 最后验证入口 Nginx#

1
curl -i "http://192.168.150.101/api/item/10001"

13.4 查看日志#

1
tail -f /usr/local/openresty/nginx/logs/error.log
2
tail -f /usr/local/openresty/nginx/logs/access.log

生产环境不要长期保留大量 ngx.ERR 以下的调试日志，否则会增加 I/O 和磁盘压力。

14. 常见故障#

现象	优先检查
OpenResty 启动失败	`openresty -t`、配置块位置、分号
`module 'common' not found`	`lua_package_path`、文件路径和文件名
访问 `/api/item/1` 返回 404	location 正则、入口 Nginx 的代理路径
子请求 404	内部 location 是否存在、URI 是否一致
子请求 502	Tomcat 地址、端口、服务健康状态
JSON 解码失败	上游是否返回 HTML 错误页、空字符串或非 JSON
请求总落到同一节点	upstream 节点是否都可用、哈希 key 是否缺乏离散度
修改 Lua 后未生效	是否 reload、编辑的是否为当前实例配置目录

15. 本章需要记住的边界#

ngx.location.capture 是 Nginx 内部子请求，不等同于普通阻塞式 HTTP 客户端。
每个外部输入都要校验；每个上游响应都要检查状态和格式。
请求级变量必须是 local，不要用 Lua 全局变量承载请求状态。
哈希负载均衡只是提高进程缓存亲和性，不保证某个节点永远不变。
到这里仍然会访问 Tomcat。下一章加入 Redis 和 Nginx shared dict 后，才形成真正的多级缓存查询链。

音乐

I'm Aron

音乐

1. 本阶段要解决什么问题#

2. OpenResty 是什么#

3. 安装与目录#

4. 配置 Lua 模块搜索路径#

5. 第一个 OpenResty 接口#

6. 接收请求参数#

6.1 路径参数#

6.2 常见参数 API#

7. OpenResty 发起内部子请求#

7.1 为什么使用内部 location#

7.2 封装通用 HTTP 函数#

8. 配置 Tomcat 集群#

8.1 为什么用 `$request_uri`#

9. JSON 编解码#

9.1 编码#

9.2 解码#

10. 完整的商品聚合接口#

10.1 Nginx 配置#

10.2 `item.lua`#

11. 并行请求的补充#

12. 从浏览器到 Tomcat 的完整请求路径#

13. 验证步骤#

13.1 先验证 Java 接口#

13.2 再验证 OpenResty 内部链路#

13.3 最后验证入口 Nginx#

13.4 查看日志#

14. 常见故障#

15. 本章需要记住的边界#

评论区

音乐

文章目录

音乐

I'm Aron

音乐

多级缓存实战（一）：OpenResty、Lua 与 Tomcat 集群

1. 本阶段要解决什么问题#

2. OpenResty 是什么#

3. 安装与目录#

4. 配置 Lua 模块搜索路径#

5. 第一个 OpenResty 接口#

6. 接收请求参数#

6.1 路径参数#

6.2 常见参数 API#

7. OpenResty 发起内部子请求#

7.1 为什么使用内部 location#

7.2 封装通用 HTTP 函数#

8. 配置 Tomcat 集群#

8.1 为什么用 $request_uri#

9. JSON 编解码#

9.1 编码#

9.2 解码#

10. 完整的商品聚合接口#

10.1 Nginx 配置#

10.2 item.lua#

11. 并行请求的补充#

12. 从浏览器到 Tomcat 的完整请求路径#

13. 验证步骤#

13.1 先验证 Java 接口#

13.2 再验证 OpenResty 内部链路#

13.3 最后验证入口 Nginx#

13.4 查看日志#

14. 常见故障#

15. 本章需要记住的边界#

评论区

音乐

文章目录

8.1 为什么用 `$request_uri`#

10.2 `item.lua`#