企业官网建设流程全解析

• 示例工程
• 教程
• 后端

AWS CodeBuild 是亚马逊云科技（AWS）提供的全托管持续集成（CI）服务，用于编译源代码、运行单元测试并产出可部署的构建产物。本指南以 aws-doc-sdk-examples 仓库中 ruby/example_code/codebuild 目录下的官方示例为骨架，讲解如何通过 AWS SDK for Ruby 完成三类最常见的 CodeBuild 编程操作：列出全部构建项目（list_projects）、查询历史构建及其状态（list_builds与batch_get_builds）、以及触发一次构建（start_build）。读完本文，你将能够配置好 Ruby 开发环境，运行官方示例，并理解这些 API 调用的返回结构，从而在自己的 Ruby 脚本或流水线中直接复用。

一、示例目录总览

仓库中 ruby/example_code/codebuild 目录下共包含 4 个文件：

这三个 Ruby 脚本是典型的"单服务动作（Single-service actions）"示例：每个脚本只调用 CodeBuild 服务的少数几个 API，聚焦展示单个函数的具体用法。按 ruby/README.md 的分类说明，这类示例与"单服务场景（Scenarios，多次调用同服务不同函数完成一个任务）"以及"跨服务示例"相区别，是最适合快速学习和复制的最小可运行代码。

二、前置条件

根据 codebuild/README.md 与 ruby/README.md，运行示例前需要完成以下准备。

2.1 AWS 账户与凭证

• 需要一个可用的 AWS 账户；运行示例会产生 API 调用，部分操作（如真实触发构建）可能产生费用。
• 必须先在本地配置 AWS 凭证（Access Key / Secret Key），SDK 才能完成身份认证。配置方式与全局前置要求见仓库根目录的 README.md 中 "Prerequisites for all AWS SDKs" 一节。
• 强烈建议遵循最小权限原则（least privilege）：只为执行脚本所用的 IAM 身份授予必要权限。本文三个示例实际用到的 API 权限大致为codebuild:ListProjects、codebuild:ListBuilds、codebuild:BatchGetBuilds与codebuild:StartBuild，可按需收敛。

2.2 Ruby 版本与依赖管理

• ruby/Gemfile 中声明了 Ruby 版本约束ruby '3.3.7'；而 ruby/README.md 记录该示例集曾在 Ruby 3.1.2 上进行过测试。实践中建议使用与仓库声明一致或更高的 3.x 版本，可用ruby -v检查当前版本。
• SDK for Ruby 相关依赖通过 ruby/Gemfile 中的gem 'aws-sdk'引入。从 ruby/Gemfile.lock 可以看到锁定的aws-sdk-codebuild (1.91.0)版本（第 204 行），以及aws-sdk对aws-sdk-codebuild (~> 1)的版本约束（第 909 行）。也就是说，aws-sdk-codebuild采用 1.x 语义化版本，aws-sdk聚合宝石会自动带入该服务 SDK。

进入 ruby 目录后执行：

gem install bundler bundle install

若本地 Ruby 版本与 Gemfile 约束不一致，可修改或删除 ruby/Gemfile 中的ruby '3.3.7'声明。

2.3 代码风格（仅贡献时需要）

若希望向仓库贡献 Ruby 代码，ruby/README.md 说明项目使用 Rubocop 进行代码风格检查，配置见.ruby-lint.yml。日常运行示例本身无需 lint。

三、示例一：列出所有构建项目（list_projects）

文件 aws-ruby-sdk-codebuild-example-list-projects.rb 的完整代码如下：

# snippet-start:[codebuild.Ruby.listProjects] require 'aws-sdk-codebuild' # v2: require 'aws-sdk' client = Aws::CodeBuild::Client.new resp = client.list_projects({ sort_by: 'NAME', # accepts NAME, CREATED_TIME, LAST_MODIFIED_TIME sort_order: 'ASCENDING' # accepts ASCENDING, DESCENDING }) if resp.projects.empty? puts 'No projects found!' else resp.projects.each { |p| puts p } end # snippet-end:[codebuild.Ruby.listProjects]

要点解读：

• 客户端初始化：Aws::CodeBuild::Client.new会从环境变量、~/.aws/credentials或 IAM 角色等凭证链自动读取凭证与区域配置，无需显式传参。
• 参数说明：
  • sort_by指定排序字段，合法值为NAME、CREATED_TIME、LAST_MODIFIED_TIME（默认按名称）；
  • sort_order指定排序方向，合法值为ASCENDING或DESCENDING。
• 返回结构：list_projects返回对象的projects字段是一个项目名称字符串数组（同时包含next_token用于分页，此示例未处理分页）。
• 输出行为：账户下没有任何项目时打印No projects found!；否则逐行打印项目名。

值得注意的是，源码注释中保留了 v2 兼容写法# v2: require 'aws-sdk'——即旧版 SDK for Ruby v2 时代只需require 'aws-sdk'，而 SDK v3 推荐按服务引入require 'aws-sdk-codebuild'，以减小加载体积。

四、示例二：列出构建记录并查看状态（list_builds + batch_get_builds）

文件 aws-ruby-sdk-codebuild-example-list-builds.rb 展示了如何"先列表、后取详情"的两步式调用：

# snippet-start:[codebuild.Ruby.listBuilds] require 'aws-sdk-codebuild' # v2: require 'aws-sdk' client = Aws::CodeBuild::Client.new build_list = client.list_builds({ sort_order: 'ASCENDING' }) if build_list.ids.empty? puts 'No builds found!' else builds = client.batch_get_builds({ ids: build_list.ids }) builds.builds.each do |build| puts "Project: #{build.project_name}" puts "Phase: #{build.current_phase}" puts "Status: #{build.build_status}" end end # snippet-end:[codebuild.Ruby.listBuilds]

要点解读：

• list_builds只返回构建 ID 列表（ids字段），不返回完整构建详情；sort_order同样接受ASCENDING/DESCENDING。
• batch_get_builds接收构建 ID 数组，返回builds数组，每个元素是完整的构建对象。
• 示例提取了三个最常用的构建属性：
  • project_name：该构建所属的 CodeBuild 项目名；
  • current_phase：当前所处阶段（如SUBMITTED、PROVISIONING、BUILD、FINALIZING等）；
  • build_status：构建最终状态（如SUCCEEDED、FAILED、FAULT、TIMED_OUT等）。
• 空结果时输出No builds found!，避免对空数组迭代产生误解。

这一"列表 + 批量查询详情"的组合是 CodeBuild 编程中的典型模式：列表接口轻量、适合分页遍历；详情接口信息丰富，适合需要渲染状态面板或做告警判断的场景。

五、示例三：触发一次构建（start_build）

文件 aws-ruby-sdk-codebuild-example-build-project.rb 演示了从命令行接收项目名并立即启动构建：

# snippet-start:[codebuild.Ruby.buildProject] require 'aws-sdk-codebuild' # v2: require 'aws-sdk' project_name = '' if ARGV.length != 1 puts 'You must supply the name of the project to build' exit 1 else project_name = ARGV[0] end client = Aws::CodeBuild::Client.new begin client.start_build(project_name: project_name) puts "Building project #{project_name}" rescue StandardError => e puts "Error building project: #{e.message}" end # snippet-end:[codebuild.Ruby.buildProject]

要点解读：

• 命令行参数校验：脚本要求恰好 1 个参数（项目名），参数数量不符时输出提示并以退出码 1 终止，属于健壮的 CLI 脚本写法。
• start_build只需传入project_name即可按该项目的构建配置（构建环境、构建命令、artifact 设置等）启动一次构建。
• 异常处理：使用begin/rescue StandardError捕获调用失败（例如项目不存在、IAM 权限不足、超出并发配额等），打印Error building project: ...而不是让脚本直接崩溃。

执行方式：

ruby aws-ruby-sdk-codebuild-example-build-project.rb my-codebuild-project

start_build属于会产生实际构建消耗的写操作，请在确认目标项目配置正确后再运行。

六、运行与验证

所有示例脚本都在 ruby/example_code/codebuild 目录下直接以 Ruby 执行，不需要编译：

# 列出构建项目 ruby aws-ruby-sdk-codebuild-example-list-projects.rb # 列出构建记录及状态 ruby aws-ruby-sdk-codebuild-example-list-builds.rb # 启动指定项目的构建 ruby aws-ruby-sdk-codebuild-example-build-project.rb <PROJECT_NAME>

建议的验证顺序：先运行list_projects确认凭证与区域配置正确、能看到已有项目；再运行list_builds观察历史构建；最后仅在有意触发构建时运行build-project脚本。

关于测试：按 codebuild/README.md 的说明，本目录的示例代码目前未包含自动化测试。对比仓库中其他 Ruby 服务示例（例如 ruby/README.md 所述，测试统一使用 RSpec，单元测试通过 stubbed responses 不产生真实 AWS 请求、可用rspec --tag ~integ运行；集成测试会真实创建/销毁资源、可用rspec --tag integ运行），本目录既没有spec文件夹也没有测试脚本。因此，验证本目录示例的唯一途径就是直接运行脚本观察输出，并注意"运行示例可能对 AWS 账户产生费用"的官方提醒。

七、费用与安全注意事项

codebuild/README.md 的 ⚠ Important 部分明确提醒：

• 费用：运行这些代码可能对你的 AWS 账户产生费用，尤其是start_build会真实消耗 CodeBuild 构建时长；具体计费以 AWS Pricing 与 Free Tier 为准。
• 运行测试同样可能产生费用（本目录虽无测试，但这是该仓库所有示例的通用约定）。
• 最小权限：只授予完成任务所需的最低 IAM 权限。
• 区域差异：CodeBuild 并非在每个 AWS 区域都可用，示例代码也未在全部区域逐一测试，部署前请确认目标区域支持该服务。

八、进一步学习

• 继续阅读仓库内的 ruby/README.md 了解 SDK for Ruby v3 示例的整体组织方式、依赖解析与测试约定；
• 查看本仓库其他语言（如 go 、dotnetv3 等目录）中 CodeBuild 的示例做横向对比；
• 若希望参与完善这些示例，可参考 CONTRIBUTING.md 了解贡献流程；
• 官方文档：CodeBuild 用户指南、CodeBuild API Reference 与 SDK for Ruby 的Aws::CodebuildAPI 参考（链接见 codebuild/README.md 的 Additional resources 小节）。

三个脚本加在一起，覆盖了 CodeBuild 编程中最核心的"读"与"写"两类操作：list_projects/list_builds/batch_get_builds用于读取项目与构建状态，start_build用于写入新的构建请求。掌握了它们，你就具备了用 Ruby 搭建 CI 监控脚本、触发按需构建的完整基础。

• 示例工程
• 教程
• 后端