文档

缓存插件

更新时间:

通过缓存可以将后端返回的应答缓存在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:仅处理AppIdapps配置列表中的请求的Cache-Control

  • 对于应答的Header, 默认情况网关仅缓存Content-TypeContent-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不会被缓存。

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