如何正确使用 `resty.core` 优化 Lua 模块加载与性能？

Question

常见技术问题： 在 OpenResty 项目中，开发者常直接 `require "resty.core"` 并期望自动启用 JIT 优化与模块缓存机制，却未意识到 `resty.core` 的启用有严格前提——必须在 `init_by_lua*` 阶段（而非 `set_by_lua*` 或 `content_by_lua*`）中显式调用 `require("resty.core")`，且需确保 `lua_code_cache on;`（生产环境默认开启，但开发调试时易误关）。若遗漏 init 阶段加载，或在子请求/延迟加载路径中重复 `require`，不仅无法触发核心优化（如 `ngx.var` 的零拷贝访问、`string.find` 的内联加速），反而因冗余模块查找和 table 创建引入额外开销。更隐蔽的问题是：当 `resty.core` 启用后，部分老版本 `resty.*` 模块（如 `resty.lrucache`）若未适配 core 补丁，可能行为异常。如何验证是否生效？应检查 `ngx.config.ngx_lua_version >= 10025` 且 `resty.core` 返回非 nil 值，并通过 `lua-resty-core` 文档确认所用 API 是否已“core-ified”。

Answer 1

```html

一、现象层：开发者常见误用模式（What）

在 OpenResty 项目中，大量工程师（尤其从 Nginx + Lua 快速上手者）习惯性地在 content_by_lua_block 或 set_by_lua_block 中直接写：

local core = require "resty.core"

误以为此举即可“一键启用 JIT 加速”和“自动模块缓存”。实则该调用发生在每个请求生命周期内，导致：
• 每次请求重复执行模块查找与 table 构造；
• ngx.var 仍走传统字符串拷贝路径，无法享受零拷贝访问；
• string.find/string.match 未触发 LuaJIT 内联优化；
• resty.lrucache 等老模块因未适配 core 补丁，出现 key 哈希不一致或过期失效异常。

二、机制层：resty.core 的加载契约（Why）

resty.core 并非普通 Lua 模块，而是一套运行时注入式补丁框架，其生效依赖两个不可妥协的前提：

1. 阶段约束：必须在 init_by_lua*（含 init_by_lua_block 和 init_by_lua_file）中首次 require，因其需在 worker 进程初始化时劫持 Lua C API 函数指针（如 lua_gettable、lua_rawget），重绑定至优化版实现；
2. 缓存开关依赖：lua_code_cache on; 必须启用——否则每次请求重建 Lua VM，所有 JIT 编译代码与 core 补丁均被丢弃。

若违反任一前提，require "resty.core" 将静默降级为 noop（返回 nil），且无日志告警，形成“伪启用”陷阱。

三、验证层：三步精准诊断法（How to Check）

检查项	正确值	检测方式
ngx.config.ngx_lua_version	≥ 10025（即 lua-nginx-module ≥ 0.10.25）	ngx.say(ngx.config.ngx_lua_version) in init_by_lua*
require "resty.core" 返回值	非 nil（通常为 true 或模块表）	local ok = pcall(require, "resty.core"); ngx.log(ngx.INFO, "core loaded: ", tostring(ok))

四、实践层：安全启用与兼容性避坑指南

✅ 正确写法（nginx.conf）：

http {
    lua_code_cache on;  # 生产/开发环境均需显式开启！
    init_by_lua_block {
        local ok, err = pcall(require, "resty.core")
        if not ok then
            ngx.log(ngx.ERR, "failed to load resty.core: ", err)
            error(err)
        end
        ngx.log(ngx.INFO, "resty.core loaded successfully")
    }

    server {
        location /api {
            content_by_lua_block {
                -- 此处可放心使用 ngx.var.xxx 零拷贝、string.find 内联等特性
                local host = ngx.var.host  -- 直接 C 指针访问，无 GC 开销
                local _, _, port = string.find(host, ":(%d+)") -- JIT 内联加速
                ngx.say("port=", port or "80")
            }
        }
    }
}

五、演进层：OpenResty 核心模块的“Core-ified”演进图谱

graph LR
A[OpenResty v1.13.6.2] -->|引入 resty.core| B[基础 API 补丁]
B --> C[ngx.var / ngx.ctx / ngx.header]
B --> D[string.* / table.* / math.* 内联]
C --> E[resty.lrucache v0.13+ 适配 core]
D --> F[resty.limit.count v0.08+ 支持 core 补丁]
E --> G[⚠️ 老版本 resty.lrucache v0.09 会因 hash 计算逻辑冲突导致缓存穿透]

六、监控层：生产环境长效可观测方案

建议在 init_worker_by_lua_block 中注入指标采集：

init_worker_by_lua_block {
    local core = require "resty.core"
    local version = ngx.config.ngx_lua_version
    if core and version >= 10025 then
        -- 上报 Prometheus：openresty_core_enabled{version="10025"} 1
        ngx.timer.at(0, function() 
            ngx.log(ngx.NOTICE, "Core OK: ver=", version, " | JIT=", jit.status())
        end)
    else
        ngx.log(ngx.WARN, "Core NOT active: ver=", version, " core=", tostring(core))
    end
}

结合 lua-resty-core 官方文档的 Status Table，定期扫描业务中使用的 API 是否已标记为 ✅ “core-ified”。

```