Azure APIM配置指定vary-by参数时缓存不生效问题咨询

数据老陈

2026-8-26

APIM内置缓存未命中排查步骤

以下排查点不需要访问Azure门户，仅通过调整测试方式、核对策略配置即可定位90%以上的同类问题：

核对缓存键配置的名称大小写：APIM的<vary-by-header>、<vary-by-query-parameter>对名称匹配默认大小写敏感。你当前策略里配置的查询参数为小写开头的productCode、pageNo、limit，如果Postman实际传参用的是大写开头的ProductCode、PageNo、Limit，会被识别为完全不同的缓存键，不可能命中缓存。同理要确认userAuthorizationToken请求头的传参大小写和配置完全一致，传参时多余的空格、连接符差异都会导致缓存键不匹配。
检查Postman默认配置的干扰：Postman默认开启Send no-cache header开关，会自动在所有请求里携带Cache-Control: no-cache头，而你当前策略里配置了must-revalidate="true"，只要请求带了no-cache头，APIM会直接跳过缓存查询回源，这是测试阶段最常见的缓存失效原因。测试前先到Postman的设置里关掉这个开关，再发起请求。
检查策略节点顺序问题：你当前的入站策略里，<cache-lookup>节点放在了<base />标签之后。<base />标签会按顺序继承全局、产品、API级别的上层入站策略，如果上层策略里提前返回了响应、或者注入了绕过缓存的逻辑，后面配置的cache-lookup根本不会执行。缓存查询逻辑必须放在<base />标签之前，才能保证优先执行缓存匹配。
检查后端响应的缓存限制：APIM内置缓存默认不会存储带Cache-Control: no-cache/no-store、Pragma: no-cache、Set-Cookie头的响应。你可以在第一次调用接口时查看Postman收到的响应头，如果存在上述字段，需要在outbound阶段先删除这些响应头，再执行<cache-store>，否则缓存条目根本不会写入。
确认缓存写入的触发条件：<cache-store>仅会在后端返回HTTP 200响应时执行存储，如果第一次调用接口返回了4xx、5xx、3xx类状态码，不会生成任何缓存条目，后续请求自然无法命中。第一次调用后要先确认返回状态码为200，等待1-2秒让缓存完成异步写入，再发起第二次相同参数的请求验证。

当前存在配置风险的策略片段：

<policies>
    <inbound>
        <base />
        <cache-lookup vary-by-developer="false" vary-by-developer-groups="false" downstream-caching-type="none" must-revalidate="true" allow-private-response-caching="true" caching-type="internal" >
            <vary-by-header>userAuthorizationToken</vary-by-header>
            <vary-by-query-parameter>productCode</vary-by-query-parameter>
            <vary-by-query-parameter>pageNo</vary-by-query-parameter>
            <vary-by-query-parameter>limit</vary-by-query-parameter>
        </cache-lookup>
    </inbound>
    <backend>
        <base/>
    </backend>
    <outbound>
        <cache-store duration="2400" />
        <base/>
    </outbound>
    <on-error> ....etc

最小可用的修正参考配置：

<policies>
    <inbound>
        <!-- 缓存查询优先于base执行，避免被上层策略拦截 -->
        <cache-lookup vary-by-developer="false" vary-by-developer-groups="false" downstream-caching-type="none" must-revalidate="false" caching-type="internal" >
            <vary-by-header>userAuthorizationToken</vary-by-header>
            <!-- 参数名和实际传参大小写完全对齐 -->
            <vary-by-query-parameter>ProductCode</vary-by-query-parameter>
            <vary-by-query-parameter>PageNo</vary-by-query-parameter>
            <vary-by-query-parameter>Limit</vary-by-query-parameter>
        </cache-lookup>
        <base />
    </inbound>
    <backend>
        <base/>
    </backend>
    <outbound>
        <base/>
        <!-- 写入缓存前移除禁止缓存的响应头 -->
        <set-header name="Cache-Control" exists-action="delete" />
        <set-header name="Pragma" exists-action="delete" />
        <cache-store duration="2400" />
    </outbound>
    <on-error>
        <base/>
    </on-error>
</policies>

验证顺序建议：
1. 关闭Postman的no-cache自动头配置，确保请求不带绕过缓存的标识
2. 第一次调用接口，确认返回200状态码，等待2秒待缓存写入完成
3. 不修改后端数据，第二次完全相同参数调用，对比两次响应时间，如果第二次响应时间明显更短（通常缓存命中响应耗时会比回源低50%以上），说明基础缓存逻辑正常
4. 基础逻辑验证通过后，再做修改数据库的缓存有效性验证，排除其他变量干扰

内容的提问来源于stack exchange，提问作者itaustralia