ngx_lua 提供了一系列共享内存相关的 API (ngx.shared.DICT)，可以很方便地通过设置过期时间来使得缓存被动过期，值得一提的是，当缓存的容量超过预先申请的内存池大小的时候，ngx.shared.DICT.set 方法则会尝试以 LRU 的形式淘汰一部分内容。
一、ngx.shared.DICT
语法: dict = ngx.shared.DICT
语法: dict = ngx.shared[name_var]
作用域: init_by_lua*, 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*, ssl_certificate_by_lua*, ssl_session_fetch_by_lua*, ssl_session_store_by_lua*
1.1
ngx.shared.DICT.set、ngx.shared.DICT.safe_set、ngx.shared.DICT.add、ngx.shared.DICT.safe_add
语法: success, err, forcible = ngx.shared.DICT:set(key, value, exptime?, flags?)
作用域: init_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*, ssl_certificate_by_lua*, ssl_session_fetch_by_lua*, ssl_session_store_by_lua*
“无条件”地往共享内存上插入key-value对，这里讲的“无条件”指的是不管待插入的共享内存上是否已经存在相同的key。
返回值：
success：成功插入为true，插入失败为false err：操作失败时的错误信息，可能类似"no memory" forcible：true表明需要通过强制删除（LRU算法）共享内存上其他字典项来实现插入，false表明没有删除 共享内存上的字典项来实现插入。
参数value：可设置 booleans, numbers, strings, 或 nil；参数exptime：表明key的有效期时间，单位是秒（s），默认值为0，表明永远不会过期；
参数flags：是一个用户标志值，会在调用get方法时同时获取得到。
语法: ok, err = ngx.shared.DICT:safe_set(key, value, exptime?, flags?)
作用域: init_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*, ssl_certificate_by_lua*, ssl_session_fetch_by_lua*, ssl_session_store_by_lua*
与set方法类似，区别在于不会在共享内存用完的情况下，通过强制删除（LRU算法）的方法实现插入。如果内存不足，会直接返回nil和err信息”no memory”。
注意：
set和safe_set共同点是：如果待插入的key已经存在，那么key对应的原来的值会被新的value覆盖！
栗子：
location /app/detail {
default_type plain/text;
content_by_lua_block {
ngx.shared.dict:set("dog", "it is a nice dog!")
ngx.shared.dict:safe_set("cat", "it is a nice cat!", 0, 1000)
}
}
location /app/test {
default_type text/plain;
content_by_lua_block {
local value, flags = ngx.shared.dict:get("dog")
ngx.say(value, flags)
local value, flags, stale = ngx.shared.dict:get_stale("cat")
ngx.say(value, flags, stale)
}
}
输出：
it is a nice dog! nil it is a nice cat! 1000 false
语法: success, err, forcible = ngx.shared.DICT:add(key, value, exptime?, flags?)
作用域: init_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*, ssl_certificate_by_lua*, ssl_session_fetch_by_lua*, ssl_session_store_by_lua*
与set方法类似，与set方法区别在于不会插入重复的键（可以简单认为add方法是set方法的一个子方法），如果待插入的key已经存在，将会返回nil和和err=”exists”
语法: ok, err = ngx.shared.DICT:safe_add(key, value, exptime?, flags?)
作用域: init_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*, ssl_certificate_by_lua*, ssl_session_fetch_by_lua*, ssl_session_store_by_lua*
与safe_set方法类似，区别在于不会插入重复的键（可以简单认为safe_add方法是safe_set方法的一个子方法），如果待插入的key已经存在，将会返回nil和和err=”exists”
1.2 ngx.shared.DICT.get、ngx.shared.DICT.get_stale
语法: value, flags = ngx.shared.DICT:get(key)
作用域: 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*, ssl_certificate_by_lua*, ssl_session_fetch_by_lua*, ssl_session_store_by_lua*
获取共享内存上key对应的值。如果key不存在，或者key已经过期，将会返回nil；如果出现错误，那么将会返回nil以及错误信息。
返回列表中的flags，是在ngx.shared.DICT.set方法中设置的值，默认值为0. 如果设置的flags为0，那么在这里flags的值将不会被返回。
语法: value, flags, stale = ngx.shared.DICT:get_stale(key)
作用域: 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*, ssl_certificate_by_lua*, ssl_session_fetch_by_lua*, ssl_session_store_by_lua*
与get方法类似，区别在于该方法对于过期的key也会返回，第三个返回参数表明返回的key的值是否已经过期，true表示过期，false表示没有过期。
1.3 ngx.shared.DICT.replace
语法: success, err, forcible = ngx.shared.DICT:replace(key, value, exptime?, flags?)
作用域: init_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*, ssl_certificate_by_lua*, ssl_session_fetch_by_lua*, ssl_session_store_by_lua*
与set方法类似，区别在于只对已经存在的key进行操作（可以简单认为replace方法是set方法的一个子方法），如果待插入的key在字典上不存在，将会返回nil和错误信息”not found”
1.4 ngx.shared.DICT.delete
语法: ngx.shared.DICT:delete(key)
作用域: init_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*, ssl_certificate_by_lua*, ssl_session_fetch_by_lua*, ssl_session_store_by_lua*
无条件删除指定的key-value对，其等价于 ngx.shared.DICT:set(key, nil)
1.5 ngx.shared.DICT.incr
语法: newval, err, forcible? = ngx.shared.DICT:incr(key, value, init?)
作用域: init_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*, ssl_certificate_by_lua*, ssl_session_fetch_by_lua*, ssl_session_store_by_lua*
对key对应的值进行增量操作，增量值是value，其中value的值可以是一个正数，0，也可以是一个负数。value必须是一个Lua类型中的number类型，否则将会返回nil和”not a number”；key必须是一个已经存在于共享内存中的key，否则将会返回nil和”not found”.
1.6
ngx.shared.DICT.lpush、ngx.shared.DICT.rpush、ngx.shared.DICT.lpop、ngx.shared.DICT.rpop
语法: length, err = ngx.shared.DICT:lpush(key, value)
作用域: init_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*, ssl_certificate_by_lua*, ssl_session_fetch_by_lua*, ssl_session_store_by_lua*
语法: length, err = ngx.shared.DICT:rpush(key, value)
作用域: init_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*, ssl_certificate_by_lua*, ssl_session_fetch_by_lua*, ssl_session_store_by_lua*
语法: val, err = ngx.shared.DICT:lpop(key)
作用域: init_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*, ssl_certificate_by_lua*, ssl_session_fetch_by_lua*, ssl_session_store_by_lua*
语法: val, err = ngx.shared.DICT:rpop(key)
作用域: init_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*, ssl_certificate_by_lua*, ssl_session_fetch_by_lua*, ssl_session_store_by_lua*
1.7 ngx.shared.DICT.ttl
语法: ttl, err = ngx.shared.DICT:ttl(key)
作用域: init_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*, ssl_certificate_by_lua*, ssl_session_fetch_by_lua*, ssl_session_store_by_lua*
requires: resty.core.shdict or resty.core
1.8 ngx.shared.DICT.expire
语法: success, err = ngx.shared.DICT:expire(key, exptime)
作用域: init_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*, ssl_certificate_by_lua*, ssl_session_fetch_by_lua*, ssl_session_store_by_lua*
requires: resty.core.shdict or resty.core
1.9 ngx.shared.DICT.flush_all
语法: ngx.shared.DICT:flush_all()
作用域: init_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*, ssl_certificate_by_lua*, ssl_session_fetch_by_lua*, ssl_session_store_by_lua*
1.10 ngx.shared.DICT.flush_expired
语法: flushed = ngx.shared.DICT:flush_expired(max_count?)
作用域: init_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*, ssl_certificate_by_lua*, ssl_session_fetch_by_lua*, ssl_session_store_by_lua*
1.11 ngx.shared.DICT.get_keys
语法: keys = ngx.shared.DICT:get_keys(max_count?)
作用域: init_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*, ssl_certificate_by_lua*, ssl_session_fetch_by_lua*, ssl_session_store_by_lua*
1.12 ngx.shared.DICT.capacity
语法: capacity_bytes = ngx.shared.DICT:capacity()
作用域: init_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*, ssl_certificate_by_lua*, ssl_session_fetch_by_lua*, ssl_session_store_by_lua*
requires: resty.core.shdict or resty.core
1.13 ngx.shared.DICT.free_space
语法: free_page_bytes = ngx.shared.DICT:free_space()
作用域: init_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*, ssl_certificate_by_lua*, ssl_session_fetch_by_lua*, ssl_session_store_by_lua*
requires: resty.core.shdict or resty.core
Pingback引用通告： openResty中ngx_lua模块提供的API | 精彩每一天