AWS SSM SDK缓存DescribeParametersCommand结果的原因及规避方法

问题现象 #

使用@aws-sdk/client-ssm时遇到异常行为：

• 先调用一次DescribeParametersCommand，再创建新参数，第二次调用DescribeParametersCommand无法获取刚创建的参数，输出length:0
• 但如果注释掉第一次的DescribeParametersCommand调用，第二次查询就能正确获取新参数，输出length:1

异常场景代码：

import {SSMClient, PutParameterCommand, ParameterType, DescribeParametersCommand, DeleteParametersCommand } from "@aws-sdk/client-ssm";

const client = new SSMClient({});
const name = 'param-name';

// 清理参数以便重复测试
await client.send(new DeleteParametersCommand({ Names: [name] }));

// 第一次调用DescribeParameters
const res1 = await client.send(new DescribeParametersCommand({}));
const list1 = (res1.Parameters || []).filter(p => p.Name === name);

// 创建新参数
await client.send(new PutParameterCommand({ Name: name, Value: 'value', Type: ParameterType.STRING }));

// 第二次调用DescribeParameters，预期能获取新参数但实际不行
const res2 = await client.send(new DescribeParametersCommand({}));
const list2 = (res2.Parameters || []).filter(p => p.Name === name);

console.log('length:', list2.length); // 输出length:0

注释第一次调用后正常的代码：

import {SSMClient, PutParameterCommand, ParameterType, DescribeParametersCommand, DeleteParametersCommand } from "@aws-sdk/client-ssm";

const client = new SSMClient({});
const name = 'param-name';

await client.send(new DeleteParametersCommand({ Names: [name] }));

// 注释掉第一次DescribeParameters调用
// const res1 = await client.send(new DescribeParametersCommand({}));
// const list1 = (res1.Parameters || []).filter(p => p.Name === name);

await client.send(new PutParameterCommand({ Name: name, Value: 'value', Type: ParameterType.STRING }));

const res2 = await client.send(new DescribeParametersCommand({}));
const list2 = (res2.Parameters || []).filter(p => p.Name === name);

console.log('length:', list2.length); // 输出length:1

原因分析 #

这是AWS SDK v3的默认行为：HTTP客户端会对Describe*这类只读操作的响应做缓存优化。第一次调用DescribeParameters后，SDK缓存了结果，第二次调用直接返回缓存数据，导致看不到刚创建的新参数。这个缓存机制没有在官方文档中明确标注，但属于SDK内部的性能优化逻辑。

解决方案 #

1. 单个请求禁用缓存 #

在发送第二次DescribeParametersCommand时，添加Cache-Control头强制跳过缓存：

const res2 = await client.send(new DescribeParametersCommand({}), {
  headers: {
    "Cache-Control": "no-cache"
  }
});

2. 全局禁用客户端缓存 #

初始化SSMClient时，配置HTTP客户端关闭缓存：

import { SSMClient } from "@aws-sdk/client-ssm";
import { NodeHttpHandler } from "@aws-sdk/node-http-handler";

const client = new SSMClient({
  requestHandler: new NodeHttpHandler({
    cache: false
  })
});

3. 用GetParameter替代查询单个参数 #

如果只是验证单个参数是否存在，推荐使用GetParameterCommand，它针对单个参数查询，不会触发批量缓存，能实时获取最新状态：

import { GetParameterCommand } from "@aws-sdk/client-ssm";

// 创建参数后直接查询
const getRes = await client.send(new GetParameterCommand({ Name: name }));
console.log('参数存在:', !!getRes.Parameter); // 输出true

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