BlackHalo logo
Published on

AWS Emulator:本地模拟AWS API的开源工具

Authors
  • Name
    super_linear
    github.com
Hercules-emulator-running-ubuntu
头图来源: Wikimedia Commons(请在文件页查看原作者与许可条款)

概述

AWS Emulator 是亚马逊云科技(AWS)官方发布的一款本地模拟器,用于在开发、测试和持续集成(CI)环境中模拟 AWS API 的行为。它允许开发者在不连接真实 AWS 服务、不创建 AWS 账户的情况下,使用模拟的资源进行代码测试。所有请求都发送到本地运行的模拟器,而非 AWS 云端,因此不会产生任何 AWS 资源费用。该模拟器是一个无图形界面的本地程序,启动后通过设置环境变量即可让 AWS CLI 或 SDK 指向其端点,从而像操作真实 AWS 一样运行代码。此外,它还支持嵌入式模式,特别适合 Rust 项目的单元测试,无需配置端点 URL 或证书。

快速开始

使用 AI 编码助手

如果使用 AI 编码助手(如 Amazon Q Developer),可以安装 aws-emulator 技能,然后让助手自动设置模拟器。这需要 AWS CLI 2.35.0 或更高版本。具体命令为:

aws agent-toolkit add-skill --skill-name aws-emulator --region us-east-1

服务器模式(CLI 和任何 SDK)

  • Linux:安装 RPM 或 Debian 包,然后运行 aws-emulator 命令。
  • Windows / macOS:通过 Docker 运行模拟器,使用官方提供的 Dockerfile 构建容器。

启动模拟器后,通过设置环境变量(如 AWS_ENDPOINT_URL)将 SDK 指向模拟器端点。详细步骤可参考官方文档中的“Pointing your AWS SDK at AWS Emulator”部分。

嵌入式模式(Rust 测试)

对于 Rust 项目,可以将模拟器作为开发依赖(dev-dependency)添加到 Cargo.toml 中,然后在测试代码中创建模拟器实例,每个测试用例使用独立的隔离实例。这种方式无需设置端点 URL、证书或环境变量,测试代码直接通过模拟器提供的 HTTP 客户端与 SDK 交互。示例代码:

use aws_emulator_embedded::{AwsEmulatorEmbedded, EmbeddedOptions, Telemetry};

fn main() {
    let emulator = AwsEmulatorEmbedded::new(
        EmbeddedOptions::default().telemetry(Telemetry::Off)
    );
    let _http_client = emulator.http_client();
}

已知问题与保真度

AWS Emulator 并非完美复制所有 AWS API 行为。每个版本发布时都会附带一份“保真度评分”(fidelity scores),用于说明各个服务与真实 AWS 的匹配程度。用户可以通过查看发布页面上的评分来了解当前模拟的准确度。此外,仓库的 issues/ 目录下记录了已知的差距:issues/things-that-do-not-work/ 存放尚未实现的功能,issues/things-that-now-work/ 存放已修复的问题。如果用户发现自己的项目无法正常工作,可以参考官方文档“Checking whether your project works with AWS Emulator”进行排查。

从源码构建

适用场景

  • 修改模拟器代码
  • 从 Git 检出运行
  • 使用嵌入式模式(嵌入式模式会将模拟器编译进测试二进制文件,因此构建成本与从源码构建相同)

大多数用户应直接使用预构建包(参见快速开始部分)。从源码构建仅支持 Linux(x86_64 和 aarch64),Windows 和 macOS 用户请使用 Docker 方式。

前提条件

  • Rust 工具链(通过 rustup 安装)
  • C 编译器(如 GCC 或 clang),因为部分依赖需要编译 C 代码
  • 至少 100 GB 可用磁盘空间用于 target/ 目录(工作区包含每个 AWS 服务一个 crate,调试构建体积庞大,且会随服务增加而增长)
  • 多核机器(首次完整构建需要编译所有服务 crate,核心数越少耗时越长)

构建与运行

cargo build -p aws-emulator-router
cargo run -p aws-emulator-router

模拟器将在 127.0.0.1:9297 上提供 HTTPS 服务(使用自签名证书)。

嵌入式模式构建成本

嵌入式模式会将模拟器编译进测试二进制文件,因此首次运行 cargo test 时会同时编译模拟器的所有服务 crate 和用户代码。首次构建的时间和磁盘占用与从源码构建相当,但后续增量构建会很快。建议:

  • 在多个项目间复用同一个 CARGO_TARGET_DIR
  • 在 CI 中缓存 target/ 目录或使用 sccache
  • 将模拟器固定到某个发布版本,避免每次变更都重新构建

仓库布局

.
├── Cargo.toml          # 工作区定义,每个服务一个成员,加上核心 crate
├── services/
│   └── service-<name>/ # 每个 AWS 服务一个 crate
│       ├── smithy-model/ # <name>.json — 驱动线协议的 Smithy 模型
│       ├── build.rs      # 从模型生成服务声明
│       ├── src/
│       │   ├── service.rs # 请求路由和拒绝覆盖
│       │   ├── state.rs   # 该服务的内存状态
│       │   └── ops/       # 每个操作一个文件
│       └── tests/
├── core/
│   ├── router/          # 模拟器二进制:将所有服务挂载到一个端点
│   └── embedded/        # 进程内(嵌入式模式)外观
├── vendor/              # 框架 crate — 请勿编辑(更新时会被替换)
└── issues/              # 跟踪的保真度问题

遥测

AWS Emulator 默认启用遥测,用于收集使用数据以改进产品。遥测遵循严格的数据最小化原则,不会识别或关联到特定用户、账户或组织。记录中绝不包含请求/响应内容、代码、凭证或个人数据。数据不会与第三方共享。

关闭遥测的方法

  1. 命令行选项:启动时添加 --telemetry off(或 -t off),仅对当前进程生效。
    aws-emulator --telemetry off
    
  2. 环境变量:设置 EMULATOR_TELEMETRY=off,对当前 shell 启动的所有模拟器生效。
    export EMULATOR_TELEMETRY=off
    aws-emulator
    
    可接受的值:on/true/1 开启,off/false/0 关闭,不区分大小写。其他值会关闭遥测并显示警告。
  3. 配置文件:在 ~/.aws/emulator/config.toml(Linux/macOS)或 %USERPROFILE%\.aws\emulator\config.toml(Windows)中添加:
    [telemetry]
    enabled = false
    
    可通过 EMULATOR_CONFIG 环境变量指定其他路径。
  4. 嵌入式 API:在创建模拟器时通过 Telemetry::Off 选项关闭。

如果开发者构建的工具中包含了模拟器,应告知用户遥测的存在并提供关闭方式,也可以默认关闭遥测。

报告问题与贡献

  • 报告问题:请在 GitHub Issues 中提交,最好包含服务名称、操作、SDK 版本、发送的请求以及响应与真实 AWS 的差异。
  • 贡献:该仓库不接受 Pull Request。

许可证

  • 除 vendor/ 目录外,代码采用 CC0 1.0 通用许可证(CC0-1.0)。
  • vendor/ 目录下的代码采用 Apache License 2.0。

详细内容请参阅仓库中的 LICENSE 文件和 vendor/README.md。

总结

AWS Emulator 为开发者提供了一个免费、本地化的 AWS API 模拟环境,支持多种使用方式(CLI、Docker、嵌入式),并提供了详细的保真度追踪和灵活的遥测控制。尽管首次构建成本较高,但其增量编译和缓存策略可以显著提升开发效率。对于需要频繁测试 AWS 集成代码的团队,这是一个值得尝试的工具。

原标题:AWS emulator。 HN 原始发布时间:2026年11月12日星期四。当前记录为 968 分、264 条评论。

阅读原文 · 查看 HN 讨论