Apache APISIX 中变量解析机制深度解析：$status 变量的特殊行为

变量解析机制概述

在 Apache APISIX 这个高性能 API 网关中，变量解析是插件开发中的基础操作。系统提供了两种主要的变量访问方式：通过 ctx.var 访问上下文缓存变量，以及通过 ngx.var 直接访问 Nginx 原生变量。这两种方式在性能和行为特性上有着显著差异。

问题现象分析

在 header_filter 阶段（即上游服务响应后），当开发者尝试通过 core.utils.resolve_var("$status", ctx.var) 解析 HTTP 状态码时，会遇到一个特殊现象：如果 $status 变量之前已经被 proxy-rewrite 等插件解析过，那么后续通过 ctx.var 获取的值会固定为 0，而非预期的实际状态码（如 200）。

底层原理剖析

ctx.var 的工作机制

ctx.var 是 APISIX 维护的一个变量缓存系统，它在请求处理的早期阶段（如 rewrite/access 阶段）就会初始化。这种设计带来了两个重要特性：

1. 性能优化：避免了重复解析常用变量，提高了处理效率
2. 数据冻结：一旦缓存建立，后续变量值的变化不会自动更新

对于 $status 这种在请求处理后期才会确定的变量，由于缓存建立时上游尚未响应，ctx.var 中保存的初始值就是 0。

ngx.var 的实时特性

相比之下，ngx.var 直接对接 Nginx 的变量系统，具有以下特点：

1. 实时访问：总是返回当前最新的变量值
2. 性能开销：每次访问都需要进行变量解析
3. 阶段敏感性：在不同处理阶段返回的值可能不同

在 header_filter 阶段，通过 ngx.var.status 可以正确获取到上游返回的实际 HTTP 状态码。

最佳实践建议

基于对两种变量访问方式的深入理解，我们推荐以下开发实践：

1. 早期阶段变量访问：在 rewrite/access 等早期阶段，优先使用 ctx.var 获取已缓存的变量，提高性能
2. 后期阶段关键变量：在 header_filter/log 等后期阶段，对于 $status 等会变化的变量，使用 ngx.var 确保准确性
3. 变量更新策略：如果需要在插件中修改并传递变量值，应当同时更新 ctx.var 和 ngx.var 保持一致性

典型场景解决方案

对于需要在多个插件间共享 $status 等变量的场景，可以采用以下模式：

local function get_status(ctx)
    -- 先尝试从缓存获取
    local status = ctx.var.status
    if not status or status == 0 then
        -- 缓存无效时回退到实时获取
        status = ngx.var.status
        -- 更新缓存供后续使用
        ctx.var.status = status
    end
    return status
end

这种混合访问策略既保持了性能优势，又确保了数据准确性。

总结

理解 APISIX 中变量解析的双机制对于开发可靠高效的插件至关重要。ctx.var 提供了性能优化，而 ngx.var 确保了数据准确性。开发者应当根据处理阶段和变量特性选择合适的访问方式，在必要时实现混合访问策略，以达到最佳效果。