AWS SDK for Ruby V3 代码示例仓库指南:环境搭建、运行与测试
AWS SDK for Ruby V3 代码示例仓库指南:环境搭建、运行与测试
AWS SDK for Ruby Version 3 为 Ruby 开发者提供了一整套访问 AWS 基础设施服务的 API,使你可以直接在 Ruby 应用中调用 Amazon S3、Amazon EC2、Amazon DynamoDB 等服务。本文以当前仓库 ruby/ 目录为核心,完整讲解如何从零开始配置本地环境、解析依赖、运行各类代码示例、使用 RuboCop 统一代码风格,以及通过 RSpec 执行单元测试与集成测试。读完本文,你将掌握在该仓库中"看得懂示例、装得起环境、跑得通测试"的完整实战闭环。
一、仓库中的 Ruby 示例总体概览
在 README.md 的语言清单中,Ruby SDK 示例集中存放在 ruby/ 目录(对应 AWS SDK for Ruby Version 3)。从仓库目录结构看,该目录主要由以下几部分组成:
- example_code/:按 AWS 服务组织的单服务示例,目前包含 aurora、auto-scaling、cloudtrail、cloudwatch、codebuild、cognito、dynamodb、ec2、elasticbeanstalk、eventbridge、glue、iam、kms、lambda、polly、rds、s3、secretsmanager、ses、sns、sqs 等服务目录,每个目录下都有一个 README 说明示例内容与运行方式;
- cross_service_examples/:跨服务示例应用,如 feedback_sentiment_analyzer、item_tracker;
- helpers/:示例共用的辅助模块(如 colorizer.rb、question.rb、waiters.rb 等),用于交互式场景中的输出美化、问题提示与轮询等待;
- Gemfile:Ruby 依赖清单;
- Rakefile 与 run_tests.sh:测试与任务编排入口;
- Dockerfile:容器化运行环境(Beta)。
示例类型
按照 ruby/README.md 的划分,代码示例分为三种类型:
- 单服务操作(Single-service actions):展示如何调用单个服务函数,例如 DynamoDB 的
GetItem、PutItem、Query、Scan,S3 的ListBuckets、CreateBucket等。这类示例通常是一个 Ruby 文件对应一个 API 操作,便于快速查阅某个具体调用; - 单服务场景(Single-service scenarios):展示如何在同一服务内调用多个函数完成一个具体任务,例如 DynamoDB 的 PartiQL 单条与批量查询场景、S3 的入门场景
scenario_getting_started.rb; - 跨服务示例(Cross-service examples):横跨多个 AWS 服务的示例应用,位于 ruby/cross_service_examples/ 下。
如何查找示例
单服务操作与场景按服务归类在 ruby/example_code 中,每个服务目录内的 README 会列出该服务下所有示例并说明运行方法。以 dynamodb/README.md 为例,它既提供了 "Hello DynamoDB"(调用 ListTables)这类入门示例,也列出了完整的单操作清单(含源码行号锚点),以及 PartiQL 单条/批量查询场景,方便读者按需定位。
二、环境准备:AWS 账号与本地凭据
在运行任何示例之前,需要先完成两项 AWS 侧的前置配置(详见根目录 README.md 的说明):
- 注册 AWS 账号;
- 在本地配置 AWS 凭据(参见 README.md)。
配置完成后,SDK 会通过标准的凭据解析链(环境变量、~/.aws/credentials 文件、IAM 角色等)自动获取访问凭证,无需在代码中硬编码密钥。
⚠️ 费用与安全注意事项
ruby/README.md 对此给出了三条明确提醒:
- 运行示例代码可能产生 AWS 账号费用;
- 运行测试同样可能产生费用(集成测试会在你的账号中创建和销毁真实资源);
- 建议遵循最低权限原则(least privilege),只为任务授予所需的最小权限,切勿使用管理员权限运行示例。
此外,仓库中的示例并未在每一个 AWS 区域做过完整测试,在生产环境使用前应结合目标区域的服务可用性进行验证。
三、Ruby 版本要求与依赖解析
Ruby 版本
该代码以 Ruby 版本 3.1.2 进行测试。在 ruby/Gemfile 中通过 ruby '3.3.7' 声明了当前推荐的 Ruby 版本约束(README 中提到的测试版本为 3.1.2;如需固定其他版本,可修改或删除 Gemfile 中的该行声明)。同时,ruby/Dockerfile 的镜像基础即 ruby:3.1.2-buster,与 README 声明的测试版本保持一致。
先确认本机 Ruby 版本:
ruby -v
如果需要管理多个 Ruby 版本(如 rbenv、rvm),请参考 Ruby 官方安装文档。注意:若本机 Ruby 版本与 Gemfile 声明的版本不一致,Bundler 会因版本约束报错,此时需要调整 Gemfile 中的 ruby "x.y.z" 行。
安装依赖
在 ruby/ 目录下执行以下两条命令:
gem install bundler
bundle install
其中 gem install bundler 用于确保 Bundler 已安装,bundle install 则根据 ruby/Gemfile 解析并安装全部依赖。当前 Gemfile 声明的核心依赖包括:
| Gem | 用途 |
|---|---|
aws-sdk |
聚合 AWS SDK for Ruby V3 全部服务客户端,示例代码的直接依赖 |
rspec |
测试框架,用于运行仓库中的单元测试与集成测试 |
rake |
任务编排,配合 Rakefile 执行测试 |
rubocop / rubocop-github / rubocop-rake |
代码风格检查(详见下文"代码风格"一节) |
cli-ui |
交互式命令行示例的界面辅助 |
sinatra / rack / rack-test |
跨服务示例中构建本地 Web 界面与测试 |
sequel |
数据库 ORM,用于数据库类跨服务示例 |
mail / mime / zip / rubyzip / openssl / open-uri / json / multi_json / pp |
邮件、压缩、加解密、JSON 等通用工具依赖 |
四、代码风格:使用 RuboCop 统一格式
仓库依靠 RuboCop(版本参考 1.63 系列)保证 Ruby 代码在格式与风格上的一致性。若需向本仓库贡献 Ruby 代码,请按以下流程使用 RuboCop。
自定义配置
仓库提供了专门的 RuboCop 配置 .github/linters/.ruby-lint.yml,与仓库默认风格对齐,关键规则包括:
Metrics/MethodLength方法长度上限 50 行;Layout/LineLength行长度上限 150 字符;Metrics/BlockLength代码块长度上限 150 行;Metrics/AbcSize、Metrics/PerceivedComplexity、Metrics/CyclomaticComplexity复杂度指标关闭;Style/FrozenStringLiteralComment冻结字符串字面量注释关闭(允许不写# frozen_string_literal: true,但从源码看示例仍普遍保留该注释);Layout/EndOfLine关闭,兼容不同平台的换行符;Naming/FileName关闭,允许示例文件使用hello_xxx.rb、scenario_xxx.rb等描述性命名;Style/HashSyntax允许简写哈希语法(EnforcedShorthandSyntax: either)。
安装与运行
先安装 RuboCop:
gem install rubocop
对单个文件或目录执行检查(必须指定仓库的自定义配置,否则会使用 RuboCop 内置默认规则):
rubocop --config .github/linters/.ruby-lint.yml path/to/ruby/file_or_directory
对整个 ruby/ 目录递归检查:
rubocop --config .github/linters/.ruby-lint.yml .
CI 集成
在 GitHub Actions 工作流 .github/workflows/lint-ruby.yml 中,Ruby 代码的 lint 检查在 pull_request 时触发:先通过 tj-actions/changed-files 收集 ruby/**/*.rb 变更文件,再用 Ruby 3.0 环境安装 RuboCop,最后对变更文件执行 rubocop --config .github/linters/.ruby-lint.yml "${changed_files<a href="https://link.gitcode.com/i/e8013ee33b76cc90535c7eedf6c731c4" target="_blank">@]}"。这意味着提交 PR 时,只检查本次变更的文件,而非全量代码。此外,[ruby/Rakefile 也提供了 rake rubocop 任务,通过 RuboCop::RakeTask 以相同配置执行检查。
五、测试体系:RSpec 的单元测试与集成测试
仓库中所有测试均使用 RSpec,存放在各示例目录的 spec 子目录中(例如 ruby/example_code/dynamodb/basics/spec/)。每个服务或跨服务示例的 README 会说明运行测试所需的额外条件。
单元测试(不产生费用)
单元测试使用 AWS SDK for Ruby 提供的 stub(桩)响应:测试运行时请求不会真正发送到 AWS,而是返回模拟响应,因此不会产生费用。运行单元测试时,在当前示例目录下带上 ~integ 标签过滤:
rspec --tag ~integ
~integ 表示排除带有 integ 标签的用例。例如 scenario_getting_started_dynamodb_spec.rb 中的用例都标注了 integ: true,在单元测试模式下会被跳过,只有执行集成测试时才会真正运行。
集成测试(可能产生费用)
集成测试会向 AWS 发送真实请求,在账号中创建和销毁真实资源,可能产生费用,务必谨慎运行。运行方式为:
rspec --tag integ
integ 标签会选中所有真实调用 AWS 的用例。从 DynamoDB 基础场景的测试代码可以看到集成测试的真实行为模式:创建一张随机表名的 DynamoDB 表、写入一批知名电影数据、执行 GetItem / PutItem / UpdateItem / Query / Scan 等操作并断言结果、最后删除表。整条链路(建表→写数据→增删改查→删表)完整覆盖了基础场景的全部 API 操作。
批量运行入口
仓库提供了两条批量执行路径:
- ruby/run_tests.sh:运行所有带
integ标签、同时排除被隔离(~@quarantine)用例的测试:
rspec . --tag integ --tag ~@quarantine
- ruby/Rakefile:通过
RSpec::Core::RakeTask定义了默认任务rake(等价于rake spec),模式匹配*/**/*_spec.rb,并同样附加--tag integ --tag ~@quarantine选项;同时还提供了基于Rake::TestTask的rake test(匹配*/**/tests/test_*.rb)。
六、Docker 镜像(Beta)与容器化运行
仓库为 Ruby 示例提供了容器化支持(Beta 阶段):
- ruby/Dockerfile 基于
ruby:3.1.2-buster,将源码复制到/ruby工作目录,执行bundle install预装依赖,并以rake作为默认命令——即容器启动后默认直接运行全部测试; - 示例代码计划发布到 Amazon ECR(Elastic Container Registry)的公共镜像,镜像会预装全部 Ruby 示例并预解析依赖,让你可以在隔离环境中直接探索示例;
- 截至 2023 年 1 月,SDK for Ruby 镜像(ECR Public 上的
b4v4v1s0/ruby)仍在积极开发中,处于 Beta 状态,使用前请关注仓库 issue 中的进展说明。
七、典型示例实战:以 DynamoDB 与 S3 为例
DynamoDB:入门到 PartiQL 场景
在 ruby/example_code/dynamodb/ 目录中:
- Hello DynamoDB:运行
ruby hello/hello_dynamodb.rb,通过ListTables验证 SDK 环境可用; - 基础场景(Learn the basics):运行
ruby scaffold.rb,演示了完整操作闭环——创建可存放电影数据的表、单条 Put/Get/Update 电影记录、从示例 JSON 批量写入电影数据、按年份 Query 查询、按年份区间 Scan 扫描、删除记录并删除整表; - PartiQL 单条查询:运行
ruby partiql/scenario_partiql_single.rb,演示用 SELECT / INSERT / UPDATE / DELETE 语句完成单条记录的增删改查; - PartiQL 批量查询:运行
ruby partiql/scenario_partiql_batch.rb,演示用多条 SELECT / INSERT / UPDATE / DELETE 语句批量操作数据。
对应源码与测试可继续深入阅读:基础操作封装在 dynamodb_basics.rb(GetItem、PutItem、UpdateItem、Query、Scan、DeleteItem 等),建表与数据写入逻辑在 scaffold.rb,测试用例见 scenario_getting_started_dynamodb_spec.rb。
S3:对象存储基础操作
在 ruby/example_code/s3/ 目录中,示例覆盖了对象存储的典型操作:Hello 示例通过 ListBuckets 入门,基础场景 scenario_getting_started.rb 串起建桶、上传/下载对象、删除对象与删桶的完整流程;同时按 API 拆分了 bucket_create.rb、bucket_list.rb、object_get.rb、object_copy.rb、bucket_policy.rb、bucket_cors.rb 等单操作文件,详细清单见 s3/README.md。
八、常见问题排查
- Bundler 版本约束报错:Gemfile 中
ruby "3.1.2"(或当前的 3.3.7)与本机 Ruby 不一致时,bundle install会失败。解决方法是修改或删除该行声明以匹配本机版本,或使用版本管理工具切换 Ruby。 rubocop检查结果与仓库风格不一致:务必使用--config .github/linters/.ruby-lint.yml指定自定义配置,否则会套用 RuboCop 内置默认规则,导致大量误报(例如行宽 150、方法长度 50 等仓库内自定义上限与默认值不同)。- 测试结果不稳定或费用意外产生:先确认当前执行的是
--tag ~integ(桩响应、无费用)还是--tag integ(真实请求、可能计费);集成测试务必在非生产账号或最小权限环境下执行。 - Docker 环境不可用:镜像目前仍处于 Beta 开发阶段,遇到问题可改用本地
gem install bundler && bundle install的方式。
九、延伸阅读
- ruby/Gemfile:完整依赖清单;
- ruby/Rakefile:rake 测试与 lint 任务定义;
- ruby/run_tests.sh:批量集成测试入口脚本;
- ruby/Dockerfile:容器化构建配置;
- .github/linters/.ruby-lint.yml:RuboCop 自定义规则;
- .github/workflows/lint-ruby.yml:PR 阶段自动 lint 的 CI 工作流;
- README.md:根目录说明,包含 SDK 前置条件与凭据配置指引。
Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved. SPDX-License-Identifier: Apache-2.0