AWS SDK for C++ CodeBuild 代码示例：构建列表、项目查询与构建启动实战

• 示例工程
• 教程
• 后端

导读

本指南围绕 AWS Code Examples 仓库中 cpp/example_code/codebuild/README.md 所展示的 AWS SDK for C++ CodeBuild 代码示例展开，覆盖构建列表（ListBuilds）、项目列表（ListProjects）与启动构建（StartBuild）三个核心操作。读完本文，你将掌握如何用 C++ 编写 CodeBuild 管理程序、如何按排序参数与分页令牌遍历构建/项目列表，以及如何触发一次构建任务，并能基于仓库内的 CMake 构建脚本与 GTest 测试用例完成编译、运行与验证。

说明：CodeBuild 是 AWS 的全托管持续集成服务，能够编译源码、运行单元测试并产出可部署的构建产物。运行示例会产生 AWS 费用，请参考 AWS Pricing 与 Free Tier，并遵循最小权限原则。

环境准备与工程结构

前置条件

在使用示例之前，需要先完成 AWS SDK for C++ 的安装与配置：

1. 按照官方 Getting started 指南获取并构建 SDK，配置 AWS 凭证（访问密钥/角色）。
2. 阅读 Getting started with the AWS SDK for C++ code examples 了解本仓库代码示例的组织结构与构建方式。

本目录文件清单如下：

• list_builds.cpp —— 列出构建（带分页与详情查询）
• list_projects.cpp —— 列出项目
• start_build.cpp —— 启动构建
• codebuild_samples.h —— 三个操作共享的函数声明
• CMakeLists.txt —— 顶层构建脚本
• tests/ —— GTest 单元测试与 Mock HTTP 基础设施

共享接口设计

三个示例函数统一声明在 codebuild_samples.h 的AwsDoc::CodeBuild命名空间中，均接收Aws::Client::ClientConfiguration参数以控制客户端行为（如 Region、超时等）：

SortOrderType枚举来自aws/codebuild/model/SortOrderType.h，取值为ASCENDING、DESCENDING与NOT_SET，供main函数通过命令行参数映射。

启动构建：StartBuild

核心实现

start_build.cpp 中的startBuild是三者中最直接的调用：

bool AwsDoc::CodeBuild::startBuild(const Aws::String &projectName, const Aws::Client::ClientConfiguration &clientConfiguration) { Aws::CodeBuild::CodeBuildClient codeBuildClient(clientConfiguration); Aws::CodeBuild::Model::StartBuildRequest startBuildRequest; startBuildRequest.SetProjectName(projectName); Aws::CodeBuild::Model::StartBuildOutcome outcome = codeBuildClient.StartBuild( startBuildRequest); if (outcome.IsSuccess()) { std::cout << "Successfully started build" << std::endl; std::cout << "Build ID: " << outcome.GetResult().GetBuild().GetId() << std::endl; } else { std::cerr << "Error starting build" << outcome.GetError().GetMessage() << std::endl; } return outcome.IsSuccess(); }

要点解析：

• 先构造CodeBuildClient，传入ClientConfiguration即可完成客户端初始化；SDK 会自动从环境变量/凭证链解析认证信息。
• StartBuildRequest只需设置ProjectName，即触发该 CodeBuild 项目按构建规格（buildspec）执行构建。
• 返回的Build对象中GetId()是形如test-project:2e7cc8d4-5658-48ec-b3e6-e4072f495178的全局唯一构建 ID，可用于后续BatchGetBuilds查询。

main 函数与运行方式

示例的main被#ifndef TESTING_BUILD包裹（start_build.cpp），测试构建时会被排除，避免与 GTest 入口冲突：

int main(int argc, char **argv) { if (argc != 2) { std::cout << "Usage: run_start_build <project_name>" << std::endl; return 1; } Aws::SDKOptions options; options.loggingOptions.logLevel = Aws::Utils::Logging::LogLevel::Trace; Aws::InitAPI(options); { Aws::String projectName = argv[1]; Aws::Client::ClientConfiguration clientConfig; // Optional: Set to the AWS Region (overrides config file). // clientConfig.region = "us-east-1"; AwsDoc::CodeBuild::startBuild(projectName, clientConfig); } Aws::ShutdownAPI(options); return 0; }

使用说明：

• 启动前必须已存在 CodeBuild 项目，否则StartBuild会返回ResourceNotFoundException。
• 与其它两个示例不同，此处将日志级别设为Trace，便于排查凭证或请求问题。
• 可通过取消注释clientConfig.region显式指定 Region（例如us-east-1），否则回退到 AWS 配置文件。
• Aws::InitAPI/Aws::ShutdownAPI是 SDK 初始化与清理的固定模式，所有 AWS C++ 程序都必须在main中成对调用。

列出构建：ListBuilds + BatchGetBuilds

核心实现

list_builds.cpp 演示了「分页列表 + 批量取详情」的组合模式：

bool AwsDoc::CodeBuild::listBuilds(Aws::CodeBuild::Model::SortOrderType sortType, const Aws::Client::ClientConfiguration &clientConfiguration) { Aws::CodeBuild::CodeBuildClient codeBuildClient(clientConfiguration); Aws::CodeBuild::Model::ListBuildsRequest listBuildsRequest; listBuildsRequest.SetSortOrder(sortType); Aws::String nextToken; // Used for pagination. do { if (!nextToken.empty()) { listBuildsRequest.SetNextToken(nextToken); } Aws::CodeBuild::Model::ListBuildsOutcome listBuildsOutcome = codeBuildClient.ListBuilds( listBuildsRequest); if (listBuildsOutcome.IsSuccess()) { const Aws::Vector<Aws::String> &ids = listBuildsOutcome.GetResult().GetIds(); if (!ids.empty()) { std::cout << "Information about each build:" << std::endl; Aws::CodeBuild::Model::BatchGetBuildsRequest getBuildsRequest; getBuildsRequest.SetIds(listBuildsOutcome.GetResult().GetIds()); Aws::CodeBuild::Model::BatchGetBuildsOutcome getBuildsOutcome = codeBuildClient.BatchGetBuilds( getBuildsRequest); if (getBuildsOutcome.IsSuccess()) { const Aws::Vector<Aws::CodeBuild::Model::Build> &builds = getBuildsOutcome.GetResult().GetBuilds(); std::cout << builds.size() << " build(s) found." << std::endl; for (auto val: builds) { std::cout << val.GetId() << std::endl; } } else { std::cerr << "Error getting builds" << getBuildsOutcome.GetError().GetMessage() << std::endl; return false; } } else { std::cout << "No builds found." << std::endl; } nextToken = listBuildsOutcome.GetResult().GetNextToken(); } else { std::cerr << "Error listing builds" << listBuildsOutcome.GetError().GetMessage() << std::endl; return false; } } while (!nextToken.empty()); return true; }

要点解析：

• ListBuilds只返回构建 ID 列表（每次最多约 100 个），不会携带构建详情，因此示例紧接着用BatchGetBuilds一次性批量获取这些 ID 对应的完整Build对象——这是「先列表后批量取详情」的标准省流模式。
• 分页通过nextToken驱动：ListBuilds结果中的GetNextToken()非空时，将其回填到下一次请求的SetNextToken()，直到遍历完所有页。
• SortOrderType决定返回顺序（ASCENDING/DESCENDING），通常配合构建时间排序。

main 函数与运行方式

// Usage: run_list_builds <ASCENDING | DESCENDING> int main(int argc, char **argv) { if (argc != 2) { std::cout << "Usage: run_list_builds <ASCENDING | DESCENDING>"; return 1; } Aws::SDKOptions options; Aws::InitAPI(options); { Aws::String sortOrderType = argv[1]; Aws::CodeBuild::Model::SortOrderType sortType = Aws::CodeBuild::Model::SortOrderType::NOT_SET; if (Aws::Utils::StringUtils::CaselessCompare(argv[1], "ASCENDING")) { sortType = Aws::CodeBuild::Model::SortOrderType::ASCENDING; } else if (Aws::Utils::StringUtils::CaselessCompare(argv[1], "DESCENDING")) { sortType = Aws::CodeBuild::Model::SortOrderType::DESCENDING; } else { std::cout << "Invalid sort order type." << std::endl; } Aws::Client::ClientConfiguration clientConfig; AwsDoc::CodeBuild::listBuilds(sortType, clientConfig); } Aws::ShutdownAPI(options); return 0; }

参数说明：

• 唯一参数必须是ASCENDING或DESCENDING（大小写不敏感，通过StringUtils::CaselessCompare匹配）；其它输入会打印Invalid sort order type.并以NOT_SET调用，实际行为取决于服务端默认。
• 若账户内没有任何构建记录，输出No builds found.。

列出项目：ListProjects

核心实现

list_projects.cpp 与 ListBuilds 同构，但把分页结果累积到本地容器后统一输出：

bool AwsDoc::CodeBuild::listProjects(Aws::CodeBuild::Model::SortOrderType sortType, const Aws::Client::ClientConfiguration &clientConfiguration) { Aws::CodeBuild::CodeBuildClient codeBuildClient(clientConfiguration); Aws::CodeBuild::Model::ListProjectsRequest listProjectsRequest; listProjectsRequest.SetSortOrder(sortType); Aws::String nextToken; // Next token for pagination. Aws::Vector<Aws::String> allProjects; do { if (!nextToken.empty()) { listProjectsRequest.SetNextToken(nextToken); } Aws::CodeBuild::Model::ListProjectsOutcome outcome = codeBuildClient.ListProjects( listProjectsRequest); if (outcome.IsSuccess()) { const Aws::Vector<Aws::String> &projects = outcome.GetResult().GetProjects(); allProjects.insert(allProjects.end(), projects.begin(), projects.end()); nextToken = outcome.GetResult().GetNextToken(); } else { std::cerr << "Error listing projects" << outcome.GetError().GetMessage() << std::endl; } } while (!nextToken.empty()); std::cout << allProjects.size() << " project(s) found." << std::endl; for (auto project: allProjects) { std::cout << project << std::endl; } return true; }

要点解析：

• ListProjects返回项目名称列表，同样通过nextToken分页；示例将所有页合并进allProjects，最后统一打印总数与每个项目名。
• 与 ListBuilds 的差异在于：项目列表无需二次BatchGet即可满足大多数场景，因此这里不做详情查询。
• 错误处理上仅打印错误信息并继续循环（不会return false），从源码结构看这属于示例的简化处理，实际生产代码建议在连续失败时中断并设置退避重试。

main 函数与运行方式

// Usage: run_list_projects <ASCENDING | DESCENDING> int main(int argc, char **argv) { if (argc != 2) { std::cout << "Usage: run_list_projects <ASCENDING | DESCENDING>"; return 1; } Aws::SDKOptions options; Aws::InitAPI(options); { Aws::String sortOrderType = argv[1]; Aws::CodeBuild::Model::SortOrderType sortType = Aws::CodeBuild::Model::SortOrderType::NOT_SET; if (Aws::Utils::StringUtils::CaselessCompare(argv[1], "ASCENDING")) { sortType = Aws::CodeBuild::Model::SortOrderType::ASCENDING; } else if (Aws::Utils::StringUtils::CaselessCompare(argv[1], "DESCENDING")) { sortType = Aws::CodeBuild::Model::SortOrderType::DESCENDING; } else { std::cout << "Invalid sort order type." << std::endl; } Aws::Client::ClientConfiguration clientConfig; AwsDoc::CodeBuild::listProjects(sortType, clientConfig); } Aws::ShutdownAPI(options); return 0; }

构建与运行示例

CMake 构建机制

顶层 CMakeLists.txt 采用本仓库的标准模式：

• 通过find_package(AWSSDK REQUIRED COMPONENTS codebuild)定位已安装的 SDK；Windows 构建时自动复制 SDK 动态库到输出目录（AWSSDK_CPY_DYN_LIBS）。
• AWSDOC_SOURCE变量允许在命令行限定参与编译的源文件（例如只构建某一个 action），未定义时用file(GLOB "*.cpp")收集全部源文件。
• 每个源文件生成一个可执行文件，命名规则为run_+ 源文件名去掉后缀。例如list_builds.cpp生成run_list_builds。

因此，构建与运行单个示例的命令为（在构建目录内执行）：

cd <BUILD_DIR> cmake <path-to-root-of-this-source-code> make ./run_list_builds ASCENDING ./run_list_projects DESCENDING ./run_start_build <project_name>

README 也明确指出：可执行文件位于构建目录，名称以run_为前缀，源码文件中的main函数注释里写明了各自的用法说明（如Usage: run_start_build <project_name>）。若源文件位于其它目录，请查阅对应目录下的 README。

单元测试：Mock HTTP 离线验证

tests/ 目录提供了一套不依赖真实 AWS 资源的 GTest 测试：

• codebuild_gtests.cpp 定义了CodeBuild_GTests测试基类与MockHTTP基础设施：CustomMockHTTPClient会为凭证请求单独返回 mock 凭证响应（避免误用服务接口的 mock 数据），其它请求则返回通过addResponseWithBody()从 JSON 文件载入的预置响应体。
• gtest_list_builds.cpp 与 gtest_list_projects.cpp 以ASCENDING顺序调用listBuilds/listProjects，标签后缀_2_表示需要凭证与权限。
• gtest_start_build.cpp 通过 mock_input/StartBuild.json 注入一个完整的StartBuild响应（构建状态IN_PROGRESS、阶段QUEUED、超时 60 分钟），然后以"test-project"为参数调用startBuild，标签后缀_3_表示无需真实凭证。
• mock JSON 同时展示了真实Build对象的典型字段：id、buildNumber、buildStatus、currentPhase、environment（如BUILD_GENERAL1_SMALL、LINUX_CONTAINER）、source（GITHUB 类型 + buildspec）等，可用于理解StartBuild返回值结构。

运行测试

README 提供的测试命令如下（注意 ⚠ 运行测试可能产生 AWS 费用，因为部分用例仍会访问服务端点）：

cd <BUILD_DIR> cmake <path-to-root-of-this-source-code> -DBUILD_TESTS=ON make ctest

在BUILD_TESTS=ON时，顶层 CMake 会通过add_subdirectory(tests)进入 tests/CMakeLists.txt：

• 优先find_package(GTest)，未找到时自动通过FetchContent拉取 googletestrelease-1.12.1。
• 构建目标codebuild_gtest，并注入TESTING_BUILD宏与SRC_DIR宏（后者供MockHTTP::addResponseWithBody定位mock_input/下的 JSON 文件）。
• 源码编译时对每个gtest_*.cpp自动关联其对应的../源文件（即把gtest_list_builds.cpp与list_builds.cpp一起编译），并用gtest_add_tests注册测试。

测试标签约定（见各测试文件头注释）：

• _1_：需要凭证、权限与 AWS 资源；
• _2_：需要凭证与权限；
• _3_：不需要凭证。

注意事项与延伸阅读

成本与安全

• 运行这些代码与测试都可能产生 AWS 费用；建议在非生产账号或预算受控环境中执行。
• 请遵循 IAM 最小权限最佳实践：列表类操作只需codebuild:ListBuilds、codebuild:BatchGetBuilds、codebuild:ListProjects，启动构建需要codebuild:StartBuild（必要时附加项目指定的 service role 权限）。
• 这些示例并非在所有 AWS 区域经过测试，请参考 AWS Regional Services 确认目标区域可用性。

运行前提

• StartBuild需要一个已存在的 CodeBuild 项目；ListBuilds/ListProjects在无数据时分别输出No builds found.与0 project(s) found.。
• 凭证解析遵循 SDK 默认链路（环境变量 → 共享凭证文件 → IAM 角色等），ClientConfiguration可覆盖 Region 等参数。

相关资源

• CodeBuild User Guide
• CodeBuild API Reference
• SDK for C++ CodeBuild reference

本目录位于仓库的cpp/example_code/codebuild/，同类 C++ 示例可参考cpp/example_code/下的其它服务目录；测试基础设施（MockHTTP、preconditionError等）在多个服务示例中复用，理解本目录即可触类旁通。

• 示例工程
• 教程
• 后端