多级缓存实战（二）：Redis 与 Nginx 本地缓存

本文在 OpenResty 调用 Tomcat 的基础上加入 Redis 和 Nginx shared dict，形成“本地缓存 → Redis → Tomcat → MySQL”的完整查询链。

1. 最终查询链#

flowchart LR U["用户请求"] --> L1{"OpenResty\n本地缓存命中？"} L1 -- "是" --> R["返回 JSON"] L1 -- "否" --> L2{"Redis 命中？"} L2 -- "是" --> W1["回填本地缓存"] --> R L2 -- "否" --> T{"Tomcat 进程缓存命中？"} T -- "是" --> W2["返回并回填本地缓存"] --> R T -- "否" --> DB[("MySQL")] DB --> C["回填 Caffeine"] --> W2

各层定位：

层级	技术	共享范围	速度	主要作用
L1	Nginx shared dict	单个 OpenResty 实例的所有 worker	极快	扛热点请求
L2	Redis	多个应用和 OpenResty 实例	快	跨实例共享缓存
L3	Caffeine	单个 JVM	极快	保护 Java 服务
数据源	MySQL	全局	相对慢	权威数据

“本地”不等于“单个 worker”：lua_shared_dict 在同一 Nginx 实例的 worker 间共享，但不同机器、不同 OpenResty 实例之间不共享。

2. 缓存预热#

2.1 为什么需要预热#

新 Redis 刚启动时没有数据。如果大批请求同时到达，所有请求都会穿透到 Tomcat 和数据库，形成冷启动压力。预热是在流量到来前把预期热点数据写入 Redis。

在 Spring 容器启动完成后读取全部商品与库存：

1
@Component
2
public class RedisHandler implements InitializingBean {
3

4
    private final StringRedisTemplate redisTemplate;
5
    private final IItemService itemService;
6
    private final IItemStockService stockService;
7

8
    public RedisHandler(
9
            StringRedisTemplate redisTemplate,
10
            IItemService itemService,
11
            IItemStockService stockService) {
12
        this.redisTemplate = redisTemplate;
13
        this.itemService = itemService;
14
        this.stockService = stockService;
15
    }
16

17
    @Override
18
    public void afterPropertiesSet() {
19
        List<Item> items = itemService.list();
20
        List<ItemStock> stocks = stockService.list();
21

22
        for (Item item : items) {
23
            redisTemplate.opsForValue().set(
24
                    "item:id:" + item.getId(),
25
                    JSON.toJSONString(item)
26
            );
27
        }
28

29
        for (ItemStock stock : stocks) {
30
            redisTemplate.opsForValue().set(
31
                    "item:stock:id:" + stock.getId(),
32
                    JSON.toJSONString(stock)
33
            );
34
        }
35
    }
36
}

这是适合学习的小数据量写法。生产环境要额外考虑：

不应让每个应用副本启动时都全表扫描。
只预热热点数据，并分批读取、批量写入。
预热失败不能悄悄忽略，应有重试、告警和降级策略。
预热过程应幂等。
大数据量场景可由独立任务执行，不阻塞应用就绪。
课程代码写入 Redis 时没有 TTL，必须配合同步、淘汰和容量治理。

2.2 Redis 键设计#

数据	Key	Value
商品	`item:id:{id}`	商品 JSON
库存	`item:stock:id:{id}`	库存 JSON

示例：

1
item:id:10001
2
item:stock:id:10001

建议：

key 使用明确的业务命名空间。
不要把展示名称等可变字段作为 key。
value 结构变化时考虑版本，例如 item:v2:id:10001。
分布式缓存的 key 规则必须由生产者和消费者共同约定。

3. Java 连接 Redis#

课程依赖：

1
<dependency>
2
    <groupId>org.springframework.boot</groupId>
3
    <artifactId>spring-boot-starter-data-redis</artifactId>
4
</dependency>

配置：

1
spring:
2
  redis:
3
    host: 192.168.150.101
4
    port: 6379

课程通过 Docker 启动 Redis：

1
docker run --name redis \
2
  -p 6379:6379 \
3
  -d redis redis-server --appendonly yes

生产环境至少还要配置认证、持久化、内存上限、淘汰策略、主从或集群，以及网络访问控制。

4. OpenResty 查询 Redis#

OpenResty 常用 lua-resty-redis。最重要的并发规则是：Redis 对象必须在请求函数内部创建，不能放在 Lua 模块顶层共享。

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

1
local redis = require("resty.redis")
2

3
local _M = {}
4

5
function _M.read_redis(host, port, key)
6
    -- 每次请求创建自己的 redis 对象
7
    local red, new_err = redis:new()
8
    if not red then
9
        return nil, "create redis client failed: " .. tostring(new_err)
10
    end
11

12
    -- 连接、发送、读取超时，单位毫秒
13
    red:set_timeouts(1000, 1000, 1000)
14

15
    local ok, connect_err = red:connect(host, port)
16
    if not ok then
17
        return nil, "connect redis failed: " .. tostring(connect_err)
18
    end
19

20
    local value, get_err = red:get(key)
21
    if not value then
22
        red:close()
23
        return nil, "redis get failed: " .. tostring(get_err)
24
    end
25

26
    -- 命令执行完后把连接放回当前 worker 的连接池
27
    local keepalive_ok, keepalive_err = red:set_keepalive(10000, 100)
28
    if not keepalive_ok then
29
        ngx.log(ngx.WARN, "redis keepalive failed: ", keepalive_err)
30
    end
31

32
    -- Redis key 不存在时返回 ngx.null，而不是 Lua nil
33
    if value == ngx.null then
34
        return nil, nil
35
    end
36

37
    return value, nil
38
end
39

40
return _M

4.1 为什么不能把 `red` 放在模块顶层#

下面的写法有并发安全风险：

1
local redis = require("resty.redis")
2
local red = redis:new()
3

4
function read_redis(...)
5
    -- 多个请求可能共享同一个对象
6
end

OpenResty worker 会在请求间复用已加载模块。模块级 red 可能被并发请求共同使用，造成响应串线或 “socket busy” 一类问题。

4.2 连接池要点#

set_keepalive(10000, 100)：空闲超时 10 秒，池大小上限 100。
连接池是每个 Nginx worker 独立的。
调用 set_keepalive 后，当前 Redis 对象的连接已交回池中，不应继续用它执行命令。
业务代码需要为连接、发送和读取分别设置合理超时。
Redis 命令失败时不要把错误结果写入本地缓存。

5. 查询 Tomcat 的通用函数#

把上一章的 HTTP 函数放进同一个模块：

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

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

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

15
    if resp.truncated then
16
        return nil, "subrequest body was truncated"
17
    end
18

19
    return resp.body, nil
20
end

6. Nginx 本地缓存#

6.1 配置共享内存#

在 http 块中声明：

1
http {
2
    lua_shared_dict item_cache 150m;
3

4
    # 其余配置……
5
}

在 Lua 中取得字典：

1
local item_cache = ngx.shared.item_cache

读写：

1
local value = item_cache:get(key)
2

3
local ok, err = item_cache:set(key, value, 1800)
4
if not ok then
5
    ngx.log(ngx.WARN, "local cache set failed: ", err)
6
end

set 的第三个参数是过期时间，单位为秒。

6.2 容量与淘汰#

shared dict 的容量固定。如果空间不足，写入可能失败或触发淘汰。必须检查 set 返回值，并监控：

当前容量和空闲空间。
写入失败次数。
命中率。
淘汰量。
单条 value 大小。

不要把无限增长、无 TTL 的数据写进 shared dict。

7. 封装三级读取逻辑#

把以下函数继续放入 common.lua：

1
function _M.read_data(key, expire, path, params)
2
    local item_cache = ngx.shared.item_cache
3

4
    -- L1：OpenResty 本地缓存
5
    local local_value = item_cache:get(key)
6
    if local_value then
7
        return local_value, "local", nil
8
    end
9

10
    -- L2：Redis
11
    local redis_value, redis_err =
12
        _M.read_redis("192.168.150.101", 6379, key)
13

14
    if redis_value then
15
        local ok, set_err = item_cache:set(key, redis_value, expire)
16
        if not ok then
17
            ngx.log(ngx.WARN, "local cache set failed: ", set_err)
18
        end
19
        return redis_value, "redis", nil
20
    end
21

22
    if redis_err then
23
        ngx.log(ngx.WARN, "redis unavailable, fallback to http: ", redis_err)
24
    end
25

26
    -- L3：Tomcat，Tomcat 内部还有 Caffeine 和 MySQL
27
    local http_value, http_err = _M.read_http(path, params)
28
    if not http_value then
29
        return nil, nil, http_err
30
    end
31

32
    local ok, set_err = item_cache:set(key, http_value, expire)
33
    if not ok then
34
        ngx.log(ngx.WARN, "local cache set failed: ", set_err)
35
    end
36

37
    return http_value, "tomcat", nil
38
end

关键点：

函数使用 local 或模块字段 _M.read_data，不创建全局函数。
Redis 未命中和 Redis 故障都可降级到 Tomcat，但日志和指标必须区分。
只有取得有效响应后才写入本地缓存。
item_cache:set(key, nil, expire) 是错误用法；缓存前必须判断值存在。
课程链路在 Tomcat 回源后只回填 Nginx 本地缓存，不由 Lua 回填 Redis。Redis 主要依赖预热和 Canal 同步来维护。

8. 完整的 `common.lua`#

1
local redis = require("resty.redis")
2

3
local _M = {}
4

5
function _M.read_redis(host, port, key)
6
    local red, new_err = redis:new()
7
    if not red then
8
        return nil, "create redis client failed: " .. tostring(new_err)
9
    end
10

11
    red:set_timeouts(1000, 1000, 1000)
12

13
    local ok, connect_err = red:connect(host, port)
14
    if not ok then
15
        return nil, "connect redis failed: " .. tostring(connect_err)
16
    end
17

18
    local value, get_err = red:get(key)
19
    if not value then
20
        red:close()
21
        return nil, "redis get failed: " .. tostring(get_err)
22
    end
23

24
    local keepalive_ok, keepalive_err = red:set_keepalive(10000, 100)
25
    if not keepalive_ok then
26
        ngx.log(ngx.WARN, "redis keepalive failed: ", keepalive_err)
27
    end
28

29
    if value == ngx.null then
30
        return nil, nil
31
    end
32

33
    return value, nil
34
end
35

36
function _M.read_http(path, params)
37
    local resp = ngx.location.capture(path, {
38
        method = ngx.HTTP_GET,
39
        args = params
40
    })
41

42
    if not resp then
43
        return nil, "subrequest failed: no response"
44
    end
45

46
    if resp.status < 200 or resp.status >= 300 then
47
        return nil, "subrequest status: " .. tostring(resp.status)
48
    end
49

50
    if resp.truncated then
51
        return nil, "subrequest body was truncated"
52
    end
53

54
    return resp.body, nil
55
end
56

57
function _M.read_data(key, expire, path, params)
58
    local item_cache = ngx.shared.item_cache
59

60
    local value = item_cache:get(key)
61
    if value then
62
        return value, "local", nil
63
    end
64

65
    local redis_err
66
    value, redis_err = _M.read_redis("192.168.150.101", 6379, key)
67
    if value then
68
        local ok, set_err = item_cache:set(key, value, expire)
69
        if not ok then
70
            ngx.log(ngx.WARN, "local cache set failed: ", set_err)
71
        end
72
        return value, "redis", nil
73
    end
74

75
    if redis_err then
76
        ngx.log(ngx.WARN, "redis fallback: ", redis_err)
77
    end
78

79
    local http_err
80
    value, http_err = _M.read_http(path, params)
81
    if not value then
82
        return nil, nil, http_err
83
    end
84

85
    local ok, set_err = item_cache:set(key, value, expire)
86
    if not ok then
87
        ngx.log(ngx.WARN, "local cache set failed: ", set_err)
88
    end
89

90
    return value, "tomcat", nil
91
end
92

93
return _M

9. 完整的 `item.lua`#

商品缓存 30 分钟，库存缓存 1 分钟：

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_key = "item:id:" .. id
12
local stock_key = "item:stock:id:" .. id
13

14
local item_json, item_source, item_err =
15
    common.read_data(item_key, 1800, "/item", { id = id })
16

17
if not item_json then
18
    ngx.log(ngx.ERR, "read item failed: ", item_err or "unknown")
19
    ngx.status = ngx.HTTP_BAD_GATEWAY
20
    ngx.say(cjson.encode({ message = "商品服务暂时不可用" }))
21
    return
22
end
23

24
local stock_json, stock_source, stock_err =
25
    common.read_data(stock_key, 60, "/item/stock", { id = id })
26

27
if not stock_json then
28
    ngx.log(ngx.ERR, "read stock failed: ", stock_err or "unknown")
29
    ngx.status = ngx.HTTP_BAD_GATEWAY
30
    ngx.say(cjson.encode({ message = "库存服务暂时不可用" }))
31
    return
32
end
33

34
local item, item_decode_err = cjson.decode(item_json)
35
local stock, stock_decode_err = cjson.decode(stock_json)
36

37
if not item or not stock then
38
    ngx.log(
39
        ngx.ERR,
40
        "decode cache value failed, item=", item_decode_err or "",
41
        ", stock=", stock_decode_err or ""
42
    )
43
    ngx.status = ngx.HTTP_BAD_GATEWAY
44
    ngx.say(cjson.encode({ message = "缓存数据格式错误" }))
45
    return
46
end
47

48
item.stock = stock.stock
49
item.sold = stock.sold
50

51
local result, encode_err = cjson.encode(item)
52
if not result then
53
    ngx.log(ngx.ERR, "encode result failed: ", encode_err)
54
    ngx.status = ngx.HTTP_INTERNAL_SERVER_ERROR
55
    ngx.say('{"message":"响应生成失败"}')
56
    return
57
end
58

59
-- 便于学习环境观察命中层级；生产环境可改为内部日志或指标
60
ngx.header["X-Item-Cache"] = item_source
61
ngx.header["X-Stock-Cache"] = stock_source
62
ngx.say(result)

10. 为什么商品和库存 TTL 不同#

课程设置：

数据	本地缓存 TTL	原因
商品信息	1800 秒	名称、图片等相对稳定
库存	60 秒	变化更频繁，对时效性更敏感

TTL 是一致性与性能的折中，不是固定答案。应根据：

数据更新频率。
用户能容忍的陈旧时间。
回源成本。
主动失效机制是否可靠。
热点程度。

来确定。实际可加入小幅随机抖动，避免大量 key 同一时刻过期。

11. 各种故障下会发生什么#

场景	行为	风险
本地缓存命中	直接返回	可能短暂读到旧值
本地未命中、Redis 命中	回填本地后返回	正常
Redis key 不存在	回源 Tomcat	热点空 key 可能穿透
Redis 超时	降级到 Tomcat	大面积故障时可能压垮应用
Tomcat 失败	返回 502	应结合重试边界和熔断
MySQL 慢	Caffeine 未命中时受影响	可能逐层放大
shared dict 满	本地写入失败但仍可返回	命中率下降

“能降级”不代表可以无限回源。Redis 故障时需要限流、熔断、请求合并和容量预案。

12. 三类经典缓存问题#

12.1 缓存穿透#

请求的数据在 Redis 和数据库中都不存在。

可选措施：

参数和 ID 合法性校验。
对不存在的数据短时间缓存空值。
布隆过滤器。
限制异常请求来源。

缓存空值时应使用特殊标记，不要把 Lua nil 当作 value：

1
__NULL__

并设置较短 TTL。

12.2 缓存击穿#

单个热点 key 过期，大量请求同时回源。

可选措施：

请求合并或互斥锁。
热点 key 逻辑过期。
主动刷新。
允许短时间返回旧值。

OpenResty 可借助锁库实现请求合并，但锁必须有超时，持锁范围只包含回源和回填。

12.3 缓存雪崩#

大量 key 同时失效或 Redis 整体不可用。

可选措施：

TTL 加随机值。
Redis 高可用和容量治理。
分批预热。
限流、熔断、降级。
多级缓存保留合理的过期差异。

13. 观测指标#

不要只看总接口耗时，应分别记录：

L1、Redis、Tomcat 命中次数和命中率。
Redis 连接失败、超时、命令错误。
Tomcat 子请求状态码和耗时。
shared dict 写入失败和容量。
各 key 类型的 value 大小。
回源 MySQL 的 QPS。
缓存数据年龄和同步延迟。

学习环境可以临时用响应头观察命中层，生产环境更适合用日志、指标系统和追踪系统。

14. 验证方法#

第一次请求：

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

预期：

1
X-Item-Cache: redis
2
X-Stock-Cache: redis

再次请求：

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

预期：

1
X-Item-Cache: local
2
X-Stock-Cache: local

检查 Redis：

1
redis-cli GET item:id:10001
2
redis-cli GET item:stock:id:10001

验证回源时，应只删除明确的测试 key：

1
redis-cli DEL item:id:10001 item:stock:id:10001

随后 reload OpenResty 或等待本地缓存过期，再发起请求。不要在共享环境中使用 FLUSHALL。

15. 与下一章的关系#

到这里读取速度已经提升，但数据更新后会出现多个副本：

1
MySQL
2
Redis
3
OpenResty shared dict
4
每个 JVM 的 Caffeine

如果只更新 MySQL，其余缓存仍可能返回旧值。因此下一章要解决缓存同步，以及仍未完全覆盖的 OpenResty 本地缓存失效问题。

音乐

I'm Aron

音乐

1. 最终查询链#

2. 缓存预热#

2.1 为什么需要预热#

2.2 Redis 键设计#

3. Java 连接 Redis#

4. OpenResty 查询 Redis#

4.1 为什么不能把 `red` 放在模块顶层#

4.2 连接池要点#

5. 查询 Tomcat 的通用函数#

6. Nginx 本地缓存#

6.1 配置共享内存#

6.2 容量与淘汰#

7. 封装三级读取逻辑#

8. 完整的 `common.lua`#

9. 完整的 `item.lua`#

10. 为什么商品和库存 TTL 不同#

11. 各种故障下会发生什么#

12. 三类经典缓存问题#

12.1 缓存穿透#

12.2 缓存击穿#

12.3 缓存雪崩#

13. 观测指标#

14. 验证方法#

15. 与下一章的关系#

评论区

音乐

文章目录

音乐

I'm Aron

音乐

多级缓存实战（二）：Redis 与 Nginx 本地缓存

1. 最终查询链#

2. 缓存预热#

2.1 为什么需要预热#

2.2 Redis 键设计#

3. Java 连接 Redis#

4. OpenResty 查询 Redis#

4.1 为什么不能把 red 放在模块顶层#

4.2 连接池要点#

5. 查询 Tomcat 的通用函数#

6. Nginx 本地缓存#

6.1 配置共享内存#

6.2 容量与淘汰#

7. 封装三级读取逻辑#

8. 完整的 common.lua#

9. 完整的 item.lua#

10. 为什么商品和库存 TTL 不同#

11. 各种故障下会发生什么#

12. 三类经典缓存问题#

12.1 缓存穿透#

12.2 缓存击穿#

12.3 缓存雪崩#

13. 观测指标#

14. 验证方法#

15. 与下一章的关系#

评论区

音乐

文章目录

4.1 为什么不能把 `red` 放在模块顶层#

8. 完整的 `common.lua`#

9. 完整的 `item.lua`#