AWS 开源本地 AWS API 模拟器 AWS Emulator

AWS Emulator README

AWS Emulator 是 AWS API 的本地模拟器。你可以用它来测试软件，而无需调用 AWS，可在自己的机器、开发服务器或持续集成（CI）环境中使用。你不需要 AWS 账户。你的请求会发往模拟器，而不是 AWS。因此你操作的是模拟资源，而不是 AWS 资源。AWS Emulator 不收取额外服务费。你只需在 AWS 上部署时为 AWS 资源付费。

该模拟器是一个本地程序，提供 AWS API 端点。它没有图形界面。启动模拟器后，你设置环境变量，将 AWS CLI 或 AWS SDK 指向其端点。然后照常运行代码。在嵌入式模式下，你改为将模拟器的 HTTP 客户端传给 SDK。

AWS Emulator 用于构建和测试。不要将其用于生产工作负载或测试安全性。参见 AWS Emulator 中的安全性。

文档： AWS Emulator 用户指南

快速开始

使用 AI 编码代理

安装 aws-emulator 技能，然后让你的代理设置模拟器。这需要 AWS CLI 2.35.0 或更高版本。参见使用 AI 编码代理入门。

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

服务器模式（CLI 和任意 SDK）

Linux： 安装 RPM 或 Debian 包并运行 aws-emulator。参见在 Linux 上入门。
Windows / macOS： 在由简短 Dockerfile 构建的容器中运行模拟器。参见使用 Docker 入门。

通过设置环境变量，将你的 SDK 指向正在运行的模拟器。参见将你的 AWS SDK 指向 AWS Emulator。

嵌入式模式（Rust 测试）

将模拟器添加为 dev-dependency，并在进程内运行，每个测试一个隔离实例。无需设置端点 URL、证书或环境变量。你的测试将模拟器的 HTTP 客户端直接接入 SDK 客户端。参见嵌入式模式入门，以及下文从源码构建了解其构建成本。

已知问题

要了解各服务与 AWS 的匹配程度，请查看发布页面上随每个版本发布的保真度评分。要检查你自己的项目是否预期可用，参见检查你的项目能否与 AWS Emulator 配合使用。

各个缺口记录在仓库的 issues/ 目录中。尚不可用的 API 和行为位于 issues/things-that-do-not-work/ 下，已修复的则移至 issues/things-that-now-work/。

从源码构建

如果你要修改模拟器、从检出副本运行它，或使用嵌入式模式，则需要此步骤。嵌入式模式会将模拟器编译进你的测试二进制文件，因此下面的先决条件和构建成本指南同样适用。大多数其他用户则安装预构建包（参见快速开始）。从源码构建在 Linux（x86_64 和 aarch64） 上受支持；在 Windows 和 macOS 上，请使用上面的 Docker 方式。

先决条件

带有 Cargo 的 Rust 工具链（通过 rustup 安装）。
C 编译器，例如 GCC 或 clang。部分依赖会构建 C 代码。
target/ 至少需要 100 GB 可用磁盘空间。工作区中每个 AWS 服务对应一个 crate，因此全部内容的调试构建体积很大，并且会随着服务的增加而增长。
多核机器。冷启动完整构建会编译每个服务 crate，因此首次构建需要一段时间；核心越少，耗时按比例越长。之后，修改某个服务后重新构建会快得多。

构建并运行

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

模拟器在 127.0.0.1:9297 上提供 HTTPS 服务（自签名证书）。

嵌入式模式构建成本

嵌入式模式会将模拟器编译进你的测试二进制文件，因此项目的首次 cargo test 构建会在构建你自己代码的同时构建模拟器的服务 crate。请为首次构建预留与上文从源码构建同一量级的时间，以及 target/，之后便是快速的增量构建。建议：在多个项目间复用一个 CARGO_TARGET_DIR，在 CI 中缓存 target/（或使用 sccache），并将模拟器固定到某个发布提交，以免每次变更都重新构建。

仓库布局

.
├── Cargo.toml              # workspace: one member per service, plus the core crates
├── services/
│   └── service-<name>/     # ONE CRATE PER SERVICE
│       ├── smithy-model/   # <name>.json — the Smithy model that drives the wire protocol
│       ├── build.rs        # generates the service declaration from the model
│       ├── src/
│       │   ├── service.rs  # request routing and refusal overrides
│       │   ├── state.rs    # this service's in-memory state
│       │   └── ops/        # one file per operation
│       └── tests/
├── core/
│   ├── router/             # the emulator binary: mounts every service on one endpoint
│   └── embedded/           # the in-process (embedded mode) facade
├── vendor/                 # framework crates — do not edit (replaced on update)
└── issues/                 # tracked fidelity issues

遥测

AWS Emulator 被配置为收集并向 AWS 报告使用数据，以便深入了解 AWS Emulator 的使用情况。遥测默认开启。AWS Emulator 在收集遥测数据时严格遵循数据最小化原则，防止识别或归因到特定用户、账户或组织。其记录绝不包含你的请求或响应内容、你的代码、你的凭证或个人信息。我们不会与第三方共享遥测数据。

有关收集哪些数据以及如何处理这些数据的详细信息，请参阅 AWS Emulator 中的遥测。要关闭遥测，请使用以下选项之一。

使用命令行选项

启动模拟器时，将 --telemetry 选项（短形式为 -t）设置为 off。此设置仅对该模拟器进程生效。

aws-emulator --telemetry off

在容器中，在 docker run 命令中的镜像名称后添加 --telemetry off。

使用环境变量

在启动模拟器之前，将 EMULATOR_TELEMETRY 设置为 off。此设置适用于你从该 shell 启动的每个模拟器。

EMULATOR_TELEMETRY 接受 on、true 或 1 来开启遥测，接受 off、false 或 0 来关闭遥测。值不区分大小写。任何其他值都会关闭遥测，并且启动通知会显示警告。

export EMULATOR_TELEMETRY=off
aws-emulator

使用配置文件

要为机器上的每次运行关闭遥测，请将以下行添加到模拟器设置文件 config.toml 中。该文件在 Linux 和 macOS 上位于 ~/.aws/emulator/config.toml，在 Windows 上位于 %USERPROFILE%\.aws\emulator\config.toml。要使用其他文件，请将 EMULATOR_CONFIG 环境变量设置为其路径。

[telemetry]
enabled = false

使用嵌入式配置 API

在嵌入式模式下，在创建模拟器时传入的选项中关闭遥测。

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

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

你可能会构建一个包含模拟器的工具，例如其他人运行的测试框架。如果是这样，请告知你的用户有关遥测的信息，并为他们提供关闭遥测的方法。你也可以在发布工具时关闭遥测。

报告问题和贡献

在 GitHub Issues 中报告缺陷和保真度差距。最有用的报告会指明服务、操作、你的 SDK 及版本、你发送的请求，以及响应与真实 AWS 的差异。本仓库不接受 PR。

许可证

本软件根据 CC0 1.0 Universal (CC0-1.0) 许可证授权，但 vendor/ 目录中的代码除外，该目录中的代码根据 Apache License 2.0 授权。详情请参阅 LICENSE，vendor/ 中代码的许可证请参阅 vendor/README.md。