APISIX proxy-cache 插件用法

APISIX 的 proxy-cache 插件可以对上游的查询进行缓存，这样就不需要上游的应用服务自己实现缓存了，或者也能少实现一部分缓存，通用的交给插件来做。

下面的操作都是基于 APISIX 3.2 版本进行配置，关于 proxy-cache 的详细配置的可以参考文档：https://apisix.apache.org/docs/apisix/3.2/plugins/proxy-cache/ 不过文档很多地方说的不是太清楚，这里把重点的地方补充一下，首先是插件的参数：

1. cache_strategy 这个表示我们插件的缓存策略，支持配置 disk 或 memory，默认是 disk
2. cache_zone 这个表示我们使用的存储区域，对于内存或者磁盘都可以详细配置，这个需要在配置文件中进行配置。
3. cache_key 这个是我们要缓存请求的 key，key 是判断是否缓存的依据，可以指定多个 APISIX 或者 nginx 的变量，也可以指定常量字符串。需要注意的是不是所有的变量都可以使用，比如 request_body 变量就是不能使用的，因为如果 body 太大，上下文传递会有比较大的开销，所以设置了结果也是空的。
4. cache_bypass  这个指定不进行缓存的情况，也是一个数组，可以写多个变量，如果至少有 1 个变量的不为空并且不等于 0，那么就会跳过缓存。这个配置不太好理解，具体是什么变量并没有说，通过查看插件源码发现取的是 ctx.var 中的值，所以其实这个并不是请求的 URL 参数，也不是请求的 Header 内容，而是 APISIX 里面的变量，当然也包括 nginx 的变量，当变量存在时就会自动绕过请求，如果内置变量不满足要求，我们可以通过实现自定义变量来解决。
5. cache_method 这个好理解，就是哪些方法会被缓存，可以指定一个数组。
6. cache_http_status 这个表示上游的哪些状态码会被缓存，也是一个数组。
7. hide_cache_headers  如果设置为 true，会将响应的 Expires 和 Cache-Control 头响应到客户端中，默认是会去掉的。
8. cache_control 如果设置为 true，将按照 HTTP 规范中的行为进行缓存，这个仅对于内存策略生效。
9. no_cache  这个和 cache_bypass 非常类似，同样是配置一个变量列表，不过这个是在响应阶段处理，也就是上游服务主动告诉 APISIX 这个请求是否缓存，变量的含义和上面一样，支持内置变量和自定义变量。
10. cache_ttl  缓存的过期时间，单位是秒，当上面的 cache_control 未启用或者服务器未返回缓存控制头时生效，如果启动了 cache_control 则以响应的控制头为准，同样这个仅对内存策略生效。

根据官网的说明，有下面的几点需要注意：

1. 如果是基于磁盘的缓存，无法在插件中设置过期时间，默认就是 10s，但是可以通过服务的响应头 Expires 和 Cache-Control 设置过期时间。
2. 如果上游服务不可用时，那么 APISIX 会返回 502 和 504 状态码，这个时候缓存时间是默认的 10s。
3. 在 cache_key, cache_bypass 以及 no_cache 中指定的变量，如果变量值不存在，则结果为空字符串。如果其中写了常量，结果会将变量值和常量一块拼接起来。

开启插件之前，首先需要在本地配置文件添加缓存区域的配置，否则启用插件以及后续调用时会报错，首先编辑 config.yaml 添加配置如下：

apisix:     # ...     proxy_cache:         # 磁盘缓存时间 默认是 10s，可以在这里修改         cache_ttl: 10s         zones:             # 磁盘的 cache_zone 的名称           - name: disk_cache_one             # 索引需要在内存中存储，设置内存的大小限制             memory_size: 50m             # 磁盘缓存的大小限制             disk_size: 1G             # 缓存文件的路径             disk_path: "/tmp/disk_cache_one"             # 缓存级别配置             cache_levels: "1:2"             # 内存的 cache_zone 名称           - name: memory_cache_one             # 内存缓存的大小限制             memory_size: 512m 

上面就分别配置了磁盘和内存的 cache_zone 当然可以配置多个，比如大小限制不一样或者存储路径不一样，针对于不同插件的配置。再比如我们这里只使用内存作为缓存，所以也可以不配置磁盘的。总之，插件中需要用到的配置，在配置文件中必须找得到才可以，修改好之后我们保存配置，然后重启 APISIX 服务。

我们这里打算通过自定义一个 header 头来判断请求是否走缓存，由于变量在 APISIX 或 nginx 的内置变量中不存在，所以我们编写一个自定义变量的插件来解决，插件内容如下：

-- -- Licensed to the Apache Software Foundation (ASF) under one or more -- contributor license agreements.  See the NOTICE file distributed with -- this work for additional information regarding copyright ownership. -- The ASF licenses this file to You under the Apache License, Version 2.0 -- (the "License"); you may not use this file except in compliance with -- the License.  You may obtain a copy of the License at -- --     http://www.apache.org/licenses/LICENSE-2.0 -- -- Unless required by applicable law or agreed to in writing, software -- distributed under the License is distributed on an "AS IS" BASIS, -- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -- See the License for the specific language governing permissions and -- limitations under the License. -- local ngx = ngx local core = require("apisix.core") local plugin = require("apisix.plugin")  local schema = {     type = "object",     properties = {         name = {type = "string"}, 	label = {type = "integer"}     },     required = {"name"}, }  local plugin_name = "custom-vars"  local _M = {     version = 0.1,     priority = 99,     name = plugin_name,     schema = schema, }  defined_var_names = {"custom_username", "cache_bypass"}  core.ctx.register_var("custom_username", function(ctx)     return get_custom_username() end)  core.ctx.register_var("cache_bypass", function(ctx)     local bypass = core.request.header(ctx, "cache-bypass")     if not bypass then         return ""     end     return bypass end)  function get_custom_username()     local req_headers = ngx.req.get_headers()     local username = req_headers.user     if username ~= "" then         return username     end     return nil end   function _M.check_schema(conf, schema_type)     if schema_type == core.schema.TYPE_METADATA then         return core.schema.check(metadata_schema, conf)     end     return core.schema.check(schema, conf) end   function _M.init()     -- call this function when plugin is loaded     local attr = plugin.plugin_attr(plugin_name)     if attr then         core.log.info(plugin_name, " get plugin attr val: ", attr.val)     end end   function _M.destroy()     -- call this function when plugin is unloaded end  -- sorted phase: -- rewrite -> access -> before_proxy -> header_filter -> body_filter -> delayed_body_filter -> log function _M.rewrite(conf, ctx)     -- core.log.warn("plugin rewrite phase, conf: ", core.json.encode(conf))     -- core.log.warn("plugin rewrite phase, ctx: ", core.json.encode(ctx, true))     -- core.log.warn("plugin rewrite phase, username: ", get_username()) end   function _M.access(conf, ctx)     -- core.log.warn("plugin access phase, conf: ", core.json.encode(conf))     -- core.log.warn("plugin access phase, ctx: ", core.json.encode(ctx, true))     -- core.log.warn("plugin access phase, ngx headers: ", core.json.encode(ngx.req.get_headers())) end  function _M.before_proxy(conf, ctx)     -- After access and before the request goes upstream end  function _M.header_filter(conf, ctx)     -- Response header filter end  function _M.body_filter(conf, ctx)     -- Response body filter end  function _M.delayed_body_filter(conf, ctx)     -- delayed_body_filter is called after body_filter     -- it is used by the tracing plugins to end the span right after body_filter end  function _M.log(conf, ctx)     -- Log processing after response end  local function list_vars()     local args = ngx.req.get_uri_args()     if args["json"] then         return 200, defined_var_names     else         return 200, table.concat(defined_var_names, "n") .. "n"     end end   function _M.control_api()     return {         {             methods = {"GET"},             uris = {"/v1/plugin/custom-vars"},             handler = list_vars,         }     } end  return _M  

这里插件名称我们叫 custom-vars，是专门注册自定义变量的插件，我们注册了 custom_username 和 cache_bypass 这两个变量，并且添加了 Control API，我们将源码保存为 custom-vars.lua 并放到 APISIX 的 plugins 目录下，然后在配置文件中添加插件，如果之前没有添加过需要复制 config-default.yaml 中所有的插件，然后再补充上我们的插件。

具体如何加载插件可以参考之前写过的插件开发的文章。

由于我们在插件中注册了全局变量，只要插件被加载就可以，我们无需使用它也可以使用其中的自定义变量，但是假如我们要访问插件的 Control API 那么则必须在某个路由上启用插件。

使用专门的自定义变量插件的好处是我们不需要修改 proxy-cache 的源码在里面注册变量，这样假如 APISIX 升级了并且 proxy-cache 的源码有所变化我们也不需要再进行更新，只需要加入我们的 custom-vars 插件即可，对 APISIX 原有插件不会有任何影响，也是为了解耦。

加入插件后不要忘记重启 APISIX，然后我们来添加一个路由：

curl -X PUT http://127.0.0.1:9180/apisix/admin/routes/100      -H 'X-API-KEY: <api-key>' -d ' {   "uri": "/hello",   "name": "示例路由",   "plugins": {     "custom-vars": {       "name": "vars"     },     "proxy-cache": {       "cache_bypass": [         "$cache_bypass"       ],       "cache_control": false,       "cache_http_status": [         200       ],       "cache_key": [         "$uri",         "-cache-id"       ],       "cache_method": [         "GET",         "PURGE"        ],       "cache_strategy": "memory",       "cache_ttl": 30,       "cache_zone": "memory_cache_one",       "hide_cache_headers": false     }   },   "upstream": {     "nodes": [       {         "host": "10.0.1.12",         "port": 1980,         "weight": 1       }     ],     "type": "roundrobin",     "hash_on": "vars",     "scheme": "http",     "pass_host": "pass"   },   "status": 1 }' 

现在我们就添加了路由，然后我们访问路由添加 -i 参数就可以看到 APISIX 响应的字段，比如：

curl localhost:9080/hello -i 

第一次会看到 APISIX-Cache-Status: MISS 因为数据未缓存，然后再次请求就可以看到 APISIX-Cache-Status: HIT 表示缓存已经命中，同时会返回 Age 响应头，表示当前缓存的存活时间，当时间超过 TTL 时，缓存就会被删除。

然后我们也可以选择不使用缓存，比如：

curl localhost:9080/hello -i -H 'Cache-Bypass: 1' 

这时候我们会看到 APISIX-Cache-Status: BYPASS 表示没有使用缓存，而是直接请求上游服务。

假如我们要缓存 POST 之类的请求，那么这个时候 $request_body 肯定也要作为 cache_key 的一部分，但是这个时候上下文中又没有这个变量，那么怎么办呢？可以换一种方式，由于 $request_body 本身可能比较大，我们可以使用它做一个 Hash，只要请求体内容不变，那么 Hash 结果也是确定的，而且缓存的 key 也比较小，由于同时有 $uri 进行区分，选用 md5 这样的函数完全够了，碰撞的概率也是极小的，我们可以在上面插件中注册一个标识请求体的变量，比如：

core.ctx.register_var("request_body_uuid", function(ctx)     local body = core.request.get_body()     if not body then         return ""     end     return ngx.md5(body) end) 

这样我们就可以使用 $request_body_uuid 这样的变量的，那么我们在创建路由的时候 cache_key 配置如下：

{     "cache_key": [        "$uri",        "$request_body_uuid"      ] } 

这样就可以缓存 POST 请求了，如果要缓存带参数的 GET 请求可以将 $uri 变量替换为 $request_uri 变量，后者是包含参数并且未规范化的。

最后我们还可以删除路由的缓存，使用 HTTP 的 PURGE 方法发起请求：

curl localhost:9088/hello -X PURGE -i 

如果成功删除缓存会返回 200 OK，否则如果不存在缓存则会返回 404，但是前提路由配置中一定要允许 PURGE 方法，我们上面创建时就指定了，如果不指定则无法使用上面的命令删除缓存，并且启用了之后这个请求也是用于 APISIX 删除缓存，并不会请求上游的服务。

另外下面会给出 OpenResty 中两个 Lua 模块的仓库，其中有很多好用的函数可以参考，并且由于 APISIX 是基于 OpenResty 的，所以在 APISIX 插件开发中都是可用的。

Reference:

1. APISIX 官方中文版文档参考
2. OpenResty 提供的 Lua 模块
3. OpenResty 的 Lua core API 参考