API 网关：缓存插件

1. 使用方法

• 仅缓存GET方法的应答

• 不缓存使用默认分组二级域名的请求，默认分组二级域名有1000次/天的限制（海外Region及中国香港限制100次/天），仅用于测试场合

• 可在插件中加入如下的配置来区分不同的缓存

  • varyByApp：针对不同的App区分缓存

  • varyByParameters：针对不同的参数取值区分缓存，从绑定的API取同名的参数

  • varyByHeaders：针对不同的请求头区分缓存，如Accept,Accept-Language

• 现在用户在每个Region可以使用的缓存空间为1M（按用户区分）, 使用超期释放策略，缓存满了后不缓存后续的应答。

• 网关遵守后端应答中的Cache-Control头的约定来处理缓存，如果后端不返回Cache-Control头，则默认缓存，使用插件中配置的duration字段作为缓存超期时间。

• 最长允许的超期时间为48小时（172800秒）, 超过这个时间的配置无效，被视为48小时超期

• 网关默认不处理客户端的Cache-Control头，可以通过clientCacheControl来进行配置，mode取值为

  • off：忽略所有客户端请求中的Cache-Control头

  • all：处理对所有客户端的请求中的Cache-Control头

  • app：仅处理AppId在apps配置列表中的请求的Cache-Control头

• 对于应答的Header, 默认情况网关仅缓存Content-Type，Content-Encoding,Content-Language头，如果你需要更多的Headers, 可使用配置中的cacheableHeaders配置添加

2. 插件配置

可以选择JSON或者YAML格式的来配置您的插件，两种格式的schema相同，可以搜索yaml to json转换工具来进行配置格式的转换，yaml格式的模板见下表。

---
varyByApp: false    # 是否按照访问方的AppId来区分缓存内容,  默认为false
varyByParameters:   # 按照不同的参数取值来区分缓存内容
- userId            # 参数名称，如果后端参数映射为不同的名称，这里请填写映射后的参数名称
varyByHeaders:      # 是否按照不同的请求Header值来区分缓存内容
- Accept            # `Accept`表示按照不同的Accept头来区分缓存
clientCacheControl: # 允许客户端通过`Cache-Control`头来影响缓存策略, 默认`off`
  mode: "app"       # off: 拒绝所有端, all: 允许所有端, apps: 允许appId取值在`apps`列表中的端
  apps:             # 如果mode配置为`app`, 则允许`AppId`在以下列表中的取值
  - 1992323         # 消费者AppId, 注意不是AppKey
  - 1239922         # 消费者AppId, 注意不是AppKey
cacheableHeaders:   # 允许缓存的后端Headers, 默认只缓存`Content-Type`和`Content-Length`
- X-Customer-Token  # 允许缓存的Header名称
duration: 3600      # 默认超期的秒数        

3. 运行规则

• 当API网关命中Cache后，返回的应答中会包含头X-Ca-Caching: true

4. 使用限制

• 插件元数据的大小限制为50KB。

• 超过128K的应答BODY不会被缓存。

• 对于共享实例/Serverless实例来讲，每个用户每个Region的总限制为1M Bytes，专享实例请参考实例规格说明。