用 AWS Emulator 做本地联调:哪些 AWS 行为能离线验证
AWS Emulator 是一个用 Rust 编写的本地 AWS 模拟器,让 AWS CLI、SDK 和编码 agent 通过本机 HTTPS 端点调用同一套 AWS API。它能离线验证的是调用路径、请求与响应结构、错误码与消息,以及保真度测试覆盖到的工作流;保真度分数按服务以 k of n 公布,未实现的操作返回 501。本地通过应视为必要条件,覆盖范围之外的行为仍需回云确认。
- 能离线验证的核心是“调用形状”:同样的 CLI/SDK 命令、同样的请求与错误结构、同一套签名流程。
- 能验证到什么程度,取决于该服务公布的保真度测试分数;分数是快照,不是承诺。
- 未实现的操作返回 HTTP 501;保真度测试没有覆盖的行为,本地通过不能推出线上通过。
简短回答:AWS Emulator 能离线验证的是“调用形状”和“被保真度测试覆盖的行为”。你的 AWS CLI、SDK 和编码 agent 用同一套 AWS API 请求打到本机 HTTPS 端点,请求结构、响应体、错误码与消息,以及工作流产生的资源与数据,都可以在保真度测试覆盖范围内对照真实 AWS 检查。超出这个范围的行为,本地通过不能当作线上通过的证据。
下面的信息来自 AWS 在 2026 年 11 月 11 日发布的新闻博客(Test your applications against AWS locally with AWS Emulator)。抓取到的正文有截断,具体服务清单、安装包细节与版本信息,应以官方仓库和文档为准。
一、它能替你确认的四类事实#
AWS Emulator 是一个用 Rust 实现的本地模拟器,开源,按原文说法没有额外的服务费,只有实际部署到 AWS 时才为资源付费。它启动后在本机提供 HTTPS 端点,CLI、SDK 和编码 agent 通过环境变量指向这个端点,应用代码保持不变。具体能确认的事情可以分成四类。
- 调用路径没有分叉。你用的还是原来的 CLI 命令和 SDK 调用,只是 endpoint 换成了本机。测试里创建 DynamoDB 表、写入一项、再读回来的流程,与线上是同一段代码。
- 请求与响应的形状。模拟器从 AWS API models 仓库中的 API model 构建,和 AWS SDK 使用同一批模型,因此请求结构和返回错误的形状与 AWS 一致。它支持的范围,也就是这些有 API model 的服务。
- 签名与凭证链路。进程模式要求每个请求都用 Signature Version 4(SigV4)签名,与 AWS 的要求相同。模拟器每次启动都会生成新凭证,access key ID 以
EMULATOR开头,并拒绝用其他密钥签名的请求;它只使用一个账号000000000000。这既能验证你的签名和凭证加载是否正确,也能降低误连真实账号的风险。 - 未实现操作的失败方式。如果某个操作还没实现,模拟器返回 HTTP 501(Not Implemented),测试会立刻失败,而不是拿到一个看起来正常的假结果。
另外,模拟器在同一端口提供 /__admin/health 健康检查端点,脚本或容器可以先等它就绪,再开始跑测试。
二、能验证到什么程度,要看保真度分数#
“本地通过”是否有意义,取决于它和真实 AWS 的接近程度。原文用保真度测试(fidelity test)来衡量:每个测试是一段短程序,用 AWS SDK 跑一个工作流,比如存一个对象再读回、删除,并断言 AWS 的行为。每个测试都先在真实 AWS 上验证过;只有当模拟器在每次调用的状态码、响应体、确切的错误码与消息,以及工作流创建的资源与数据上都与 AWS 一致时,这个测试才算通过。
每个版本会按服务公布通过数量,形式是 k of n,例如 40 of 50,表示该服务的 50 个保真度测试中有 40 个通过。测试集公开在 GitHub 的 aws-emulator-evaluation-suite 仓库,包括尚未通过的用例。原文特别提醒,分数应读作“一个仍在改进的产品的快照”:新增测试时,即使模拟器变好了,分数也可能下降。
因此实际做法是:先列出你的代码真正调用的操作,再对着分数和公开测试集核对。测试集覆盖到的操作,本地结果有明确参照;没覆盖到的操作,本地通过只能说明“模拟器这样返回”,不能说明 AWS 也这样返回。
三、两种跑法:本机进程与进程内嵌入#
本机进程模式
这是通用方式。模拟器在 127.0.0.1:9297 上提供 HTTPS 服务,只监听本机地址。启动时它会生成自己的凭证、配置文件和证书,写到 ~/.aws/emulator/9297/ 目录。你在 shell 或测试脚本里设置环境变量,把 AWS CLI 和 SDK 指向本机,同时清掉可能提供真实凭证的变量。
export AWS_ENDPOINT_URL=https://127.0.0.1:9297
export AWS_SHARED_CREDENTIALS_FILE=~/.aws/emulator/9297/emulator_credentials
export AWS_CONFIG_FILE=~/.aws/emulator/9297/config
export AWS_EC2_METADATA_DISABLED=true
export AWS_DISABLE_HOST_PREFIX_INJECTION=true
export AWS_REGION=us-east-1
export AWS_DEFAULT_REGION=us-east-1
unset AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY AWS_SESSION_TOKEN AWS_PROFILE
上面这段是原文给出的示例配置,本次未执行。原文没有逐项解释每个变量的含义,使用前建议查官方文档。部分 SDK 还需要额外设置才能信任模拟器的证书,原文举的例子是 AWS SDK for Java 需要配置 trust store。
还有一个默认行为值得注意:模拟器默认会发送匿名的使用与错误数据,可以关闭。在受限网络或对数据外发敏感的环境里,应先确认这项设置。
进程内嵌入模式
如果你的测试用 Rust 写,可以把模拟器直接嵌进测试进程,通过 SDK 的 HTTP 客户端接进去,不必经过网络访问独立服务器。每个嵌入实例维护自己的状态,测试之间不共享桶、表和队列,可以并行跑很多个。原文说明嵌入模式目前只对 AWS SDK for Rust 提供,需要把 aws-emulator-embedded crate 加到 Cargo.toml 的 [dev-dependencies]。
use aws_emulator_embedded::{AwsEmulatorEmbedded, EmbeddedOptions};
#[tokio::test]
async fn put_then_get_returns_the_item() {
let emulator = AwsEmulatorEmbedded::new(EmbeddedOptions::default());
let config = aws_config::defaults(aws_config::BehaviorVersion::latest())
.http_client(emulator.http_client())
.region(aws_config::Region::new("us-east-1"))
.credentials_provider(emulator.aws_credentials_provider())
.load()
.await;
let ddb = aws_sdk_dynamodb::Client::new(&config);
// 建表、写项、读项的调用与线上保持一致
}
这段代码依据原文示例改写,本次未编译或执行,预期行为不作实际结果。选择上可以这样分:多语言脚本、CLI 联调和编码 agent 用进程模式;Rust 单元测试、需要并行隔离的用例用嵌入模式。
四、一次最小联调的步骤#
- 安装。Linux 上提供 RPM 或 Debian 包;macOS 和 Windows 上需要按文档里的短 Dockerfile 自行构建镜像并在容器中运行,原文明确说不发布现成镜像。
- 启动模拟器,确认日志里给出的地址、配置文件和证书路径。
- 在另一个终端设置上面的环境变量,并清掉真实凭证。
- 用健康检查端点和
aws sts get-caller-identity确认请求确实打到了模拟器。 - 运行现有测试或 CLI 脚本。命令本身不需要改。
原文给出的安装命令针对 Amazon Linux 2023,其他发行版和版本的支持情况待核实:
PKG=https://downloads.aws.com/aws-emulator/packages/aws-emulator/LTS/latest
sudo dnf install -y $PKG/aws-emulator-x86_64.rpm
aws-emulator -v
验证请求是否落到本机,可以用原文的两个动作(示例,未执行):
curl --cacert ~/.aws/emulator/9297/ca.pem \
https://127.0.0.1:9297/__admin/health
aws sts get-caller-identity
再跑一遍 S3 和 DynamoDB 的基本流程,这也是原文演示的内容(示例,未执行):
aws s3 mb s3://local-getting-started
echo "hello from the emulator" > hello.txt
aws s3 cp hello.txt s3://local-getting-started/
aws s3 ls s3://local-getting-started/
aws dynamodb create-table --table-name kiro-demo \
--attribute-definitions AttributeName=id,AttributeType=S \
--key-schema AttributeName=id,KeyType=HASH \
--billing-mode PAY_PER_REQUEST
aws dynamodb put-item --table-name kiro-demo \
--item '{"id": {"S": "item-1"}, "msg": {"S": "hello"}}'
aws dynamodb get-item --table-name kiro-demo \
--key '{"id": {"S": "item-1"}}'
五、本地通过不能推出的结论#
第一,不能推出未覆盖行为也一致。保真度测试是按服务逐个用例累积的,测试集之外的操作没有对照结论。第二,不能推出线上运行条件一致。真实 AWS 的配额、限流、IAM 策略评估、跨账号访问、区域差异、网络延迟与重试、计费,这些是否被模拟,本次材料没有涉及,需要查官方文档或回云验证。第三,不能推出编码 agent 的产出可直接上线。原文演示了让 agent 在本地建表、写项、读回,这证明的是迭代循环变快,不是产物的正确性。
还要注意,材料中没有给出任何性能数字。Rust 实现被描述为在笔记本上 CPU 和内存占用较低,但没有可核对的指标,不宜引用为性能结论。
六、落地时的几条建议#
- 把本地通过定义为必要条件。流水线里保留一组关键路径的回云对照,尤其是保真度测试未覆盖的操作。
- 用健康检查等就绪。不要靠固定 sleep,脚本先轮询
/__admin/health,再跑测试。 - 主动做状态隔离。嵌入模式每个实例独立状态,适合并行;进程模式下多个测试共用同一实例时,要自己清理桶、表和队列,避免用例互相污染。
- 把 501 当信号。看到 501 就记录为“模拟器未实现”,不要把它当成 AWS 的行为写进断言。
- 按操作核对保真度。先列调用清单,再查分数与公开测试集,别用一个服务的总分代表所有操作。
- 确认遥测设置。默认会发送匿名使用与错误数据,按团队的数据外发要求决定是否关闭。
最后说明不确定性:原文正文在“How we keep”处被截断,服务覆盖范围、安装包支持矩阵、嵌入式 crate 的版本与许可等信息并不完整。价格方面,原文只说模拟器本身无额外服务费、部署到 AWS 时按资源付费,具体计费口径仍应以 AWS 官方价格页为准。把这些前提写进团队的使用说明,比记住某一条命令更有用。
常见问题(FAQ)
AWS Emulator 能替代真实 AWS 做联调吗?
保真度分数 40/50 是什么意思?
本地返回 501 说明什么?
参考来源
以上为本文写作时的参考资料,引用观点以原文为准。