AWS SDK for Ruby V3 代码示例仓库指南:环境搭建、运行与测试

原创2026-09-27 13:19:261,757 阅读
文章标签:示例工程教程后端

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 的说明):

  1. 注册 AWS 账号;
  2. 在本地配置 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 的方式。

九、延伸阅读


Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved. SPDX-License-Identifier: Apache-2.0

登录后查看全文
aws-doc-sdk-examples