技术文章

外部链接将在新标签页打开。

用 AWS Emulator 做本地联调:哪些 AWS 行为能离线验证

一句话回答

AWS Emulator 是一个用 Rust 编写的本地 AWS 模拟器,让 AWS CLI、SDK 和编码 agent 通过本机 HTTPS 端点调用同一套 AWS API。它能离线验证的是调用路径、请求与响应结构、错误码与消息,以及保真度测试覆盖到的工作流;保真度分数按服务以 k of n 公布,未实现的操作返回 501。本地通过应视为必要条件,覆盖范围之外的行为仍需回云确认。

核心要点 TL;DR
  • 能离线验证的核心是“调用形状”:同样的 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 单元测试、需要并行隔离的用例用嵌入模式。

四、一次最小联调的步骤#

  1. 安装。Linux 上提供 RPM 或 Debian 包;macOS 和 Windows 上需要按文档里的短 Dockerfile 自行构建镜像并在容器中运行,原文明确说不发布现成镜像。
  2. 启动模拟器,确认日志里给出的地址、配置文件和证书路径。
  3. 在另一个终端设置上面的环境变量,并清掉真实凭证。
  4. 用健康检查端点和 aws sts get-caller-identity 确认请求确实打到了模拟器。
  5. 运行现有测试或 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 是什么意思?
表示该服务的 50 个保真度测试中有 40 个通过。每个测试都用真实 AWS 校验过,要求状态码、响应体、错误码与消息、以及工作流创建的资源与数据都一致。分数会随测试集变化,新增测试时可能下降。
本地返回 501 说明什么?
说明该操作尚未实现。模拟器用 HTTP 501 Not Implemented 让测试立即失败,而不是返回一个看似成功的假结果。

参考来源

  1. Test your applications against AWS locally with AWS Emulator

以上为本文写作时的参考资料,引用观点以原文为准。

作者:沐小悠

本文约 14 分钟读完 · 关键词:AWS Emulator、本地联调、AWS CLI、AWS SDK、保真度测试

更多文章 GET 示例接口

「」标签下的其他文章