AWS 模拟器

仓库文件导航

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 用于构建和测试。不要将其用于生产工作负载或用于测试安全性。参见 Security in AWS Emulator。

文档：AWS Emulator User Guide

快速开始

使用 AI 编码代理

安装 aws-emulator skill，然后让你的代理设置模拟器。这需要 AWS CLI 2.35.0 或更高版本。参见 Getting started with an AI coding agent。

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

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

• Linux：安装 RPM 或 Debian 包并运行 aws-emulator。参见 Getting started on Linux。

• Windows / macOS：在由简短 Dockerfile 构建的容器中运行模拟器。参见 Getting started with Docker。

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

嵌入式模式（Rust 测试）

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

已知问题

要了解各服务与 AWS 的匹配程度，请查看发布页面上随每个版本发布的保真度评分。要检查你自己的项目是否预期可以正常工作，参见 Checking whether your project works with 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 代码。

• 至少 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。首次构建和 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 在收集遥测数据时严格遵循数据最小化原则，避免识别或关联到特定用户、账户或组织。其记录绝不包含你的请求或响应内容、你的代码、你的凭证或个人信息。我们不会与第三方共享遥测数据。

关于收集了哪些数据以及数据如何处理，详见 Telemetry in 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。