lua共享字典是nginx内核级共享内存的lua封装，须在http块中预定义，支持原子操作如incr/set/get_set，内存需合理规划，仅限单机worker间共享且数据不持久。
在 OpenResty 的非阻塞架构中，Lua 共享字典（lua_shared_dict）是实现跨 worker 进程高速缓存与同步的原生方案。它不依赖外部服务、无网络开销、毫秒级读写，本质是 Nginx 内核级共享内存的 Lua 封装。
必须在 http 块中正确定义字典
共享字典不是“运行时创建”的对象，而是由 Nginx 启动时预分配的共享内存区域：
-
只能放在 http {} 块内，不能出现在 server、location 或 include 文件的嵌套块中，否则启动报错：
[emerg] "lua_shared_dict" directive is not allowed here - 命名仅支持字母、数字、下划线，且大小写敏感（
cache_v1和Cache_V1是两个独立字典） - 每个名字只能声明一次；多个配置文件中重复定义会触发 duplicate directive 错误
- 示例配置：
http {
lua_shared_dict user_cache 20m;
lua_shared_dict api_counter 5m;
}
用原子操作保障并发安全
Nginx worker 进程并发执行 Lua 脚本，共享字典虽内存隔离，但 Lua 层逻辑仍需避免竞态。get + set 组合不是原子的，必须改用内置原子方法：
- 计数类场景优先用
dict:incr(key, step)：首次访问自动初始化为 0，再加 step；返回新值和错误信息 - 设置带过期时间的值统一用
dict:set(key, val, exptime)，单位为秒（如3600表示 1 小时） - 读取后需条件更新时，可用
dict:get_set(key, new_val, exptime)，它返回旧值并原子替换 - 避免以下写法：
val = dict:get(k); if not val then dict:set(k, v, 60) end—— 两个请求可能同时判空并写入，导致数据覆盖或重复初始化
合理规划内存与 key 设计
共享内存是固定大小的 slab 区域，设计不当会导致 LRU 频繁驱逐或内存浪费：
- 单个 key 名称最长 255 字节，建议对长标识（如含 User-Agent 的 IP）先做哈希：
md5(ngx.var.remote_addr .. ngx.var.http_user_agent) - 预估总 key 数 ×（平均 key 长度 + value 长度 + 约 64 字节元信息），再上浮 25% 作为缓冲
- 过小（如 1m 存数千 key）会频繁淘汰有效数据；过大（如 100m 仅用 10%）则挤占系统资源
- 过期机制是惰性的：访问时才检查 TTL；可主动调用
dict:flush_expired(n)批量清理最多 n 个过期项
明确适用边界，不越界使用
共享字典快而轻，但不是万能存储：
- 数据随 Nginx reload 或重启**完全清空**，不可用于需要持久化的状态（如订单流水）
- 只在**单机所有 worker 进程间共享**，不跨机器；集群级同步需配合 Redis 或 etcd
- value 类型仅支持 string、number、boolean、nil，不支持 table、function、userdata 或循环引用结构
- 适合高频读写、低延迟要求的场景：限流计数、热点缓存、黑名单校验、API 调用统计等
