ngx.ctx

https://github.com/openresty/lua-nginx-module#ngxctx

要点

生命周期和请求一致

每个请求的ngx.ctx是相互独立的,包括ngx.location.capture的子请求

内部跳转(Internal redirection)如ngx.exec会销毁ngx.ctx,重建新的.

ngx.ctx的属性查找代价相对昂贵,所以尽量使用显式的函数参数.

原文

context: init_worker_by_lua, set_by_lua, rewrite_by_lua, access_by_lua, content_by_lua, header_filter_by_lua, body_filter_by_lua, log_by_lua, ngx.timer., balancer_by_lua*

This table can be used to store per-request Lua context data and has a life time identical to the current request (as with the Nginx variables).

Consider the following example,

location /test {

rewrite_by_lua '

ngx.ctx.foo = 76

';

access_by_lua '

ngx.ctx.foo = ngx.ctx.foo + 3

';

content_by_lua '

ngx.say(ngx.ctx.foo)

';

}

Then GET /test will yield the output

79

That is, the ngx.ctx.foo entry persists across the rewrite, access, and content phases of a request.

Every request, including subrequests, has its own copy of the table. For example:

location /sub {

content_by_lua '

ngx.say("sub pre: ", ngx.ctx.blah)

ngx.ctx.blah = 32

ngx.say("sub post: ", ngx.ctx.blah)

';

}

location /main {

content_by_lua '

ngx.ctx.blah = 73

ngx.say("main pre: ", ngx.ctx.blah)

local res = ngx.location.capture("/sub")

ngx.print(res.body)

ngx.say("main post: ", ngx.ctx.blah)

';

}

Then GET /main will give the output

main pre: 73

sub pre: nil

sub post: 32

main post: 73

Here, modification of the ngx.ctx.blah entry in the subrequest does not affect the one in the parent request. This is because they have two separate versions of ngx.ctx.blah.

Internal redirection will destroy the original request ngx.ctx data (if any) and the new request will have an empty ngx.ctx table. For instance,

location /new {

content_by_lua '

ngx.say(ngx.ctx.foo)

';

}

location /orig {

content_by_lua '

ngx.ctx.foo = "hello"

ngx.exec("/new")

';

}

Then GET /orig will give

nil

rather than the original "hello" value.

Arbitrary data values, including Lua closures and nested tables, can be inserted into this "magic" table. It also allows the registration of custom meta methods.

Overriding ngx.ctx with a new Lua table is also supported, for example,

ngx.ctx = { foo = 32, bar = 54 }

When being used in the context of init_worker_by_lua*, this table just has the same lifetime of the current Lua handler.

The ngx.ctx lookup requires relatively expensive metamethod calls and it is much slower than explicitly passing per-request data along by your own function arguments. So do not abuse this API for saving your own function arguments because it usually has quite some performance impact.

Because of the metamethod magic, never "local" the ngx.ctx table outside your Lua function scope on the Lua module level level due to worker-level data sharing. For example, the following is bad:

-- mymodule.lua

local _M = {}

-- the following line is bad since ngx.ctx is a per-request

-- data while this

ctx

variable is on the Lua module level

-- and thus is per-nginx-worker.

local ctx = ngx.ctx

function _M.main()

ctx.foo = "bar"

end

return _M

Use the following instead:

-- mymodule.lua

local _M = {}

function _M.main(ctx)

ctx.foo = "bar"

end

return _M

That is, let the caller pass the ctx table explicitly via a function argument.