企业官网建设流程全解析

• 示例工程
• 教程
• 后端

Amazon Simple Notification Service（Amazon SNS）是 AWS 提供的全托管消息推送服务，它让应用、终端用户与设备能够"瞬时地从云端接收通知"。本文以 cpp/example_code/sns/README.md 为骨架，结合该目录下的全部 C++ 源码、构建脚本与 GoogleTest 测试，系统讲解如何用 AWS SDK for C++ 完成 SNS 的建站、订阅、发布、短信配置等全部核心操作。读完本文，你将掌握 10 个 SNS 单一操作接口的调用范式、Hello SNS 入门示例的分页处理技巧，以及"发布短信""发布消息到队列"等跨服务场景的完整实现路径。

示例全景：这份 README 能教会你什么

该文档对应的示例代码位于 cpp/example_code/sns，主题是使用 AWS SDK for C++ 与 Amazon SNS 服务交互。Amazon SNS 是"发布/订阅（pub/sub）"范式的典型实现：发布者（Publisher）把消息发送到Topic（主题），SNS 负责把消息扇出（fan-out）给所有订阅者（Subscriber）——订阅者可以是 HTTP/HTTPS 端点、邮箱、AWS Lambda 函数、SQS 队列、移动应用终端等。

从目录结构看，示例被清晰地分为三类：

其中所有可复用的操作函数被统一声明在 sns_samples.h 的AwsDoc::SNS命名空间中，每个函数都以bool返回值表示调用成败，并统一接受Aws::Client::ClientConfiguration作为客户端配置参数——这是整个目录的公共 API 契约。

运行前置条件与重要注意事项

环境准备

所有示例在运行前都必须完成 AWS SDK for C++ 的安装与配置，包括：

1. 安装并构建 SDK：按 AWS SDK for C++ 官方"Getting started"文档完成 SDK 的下载、编译与环境变量配置（即完成 Hello World 级别的 SDK 自检）；
2. 配置开发环境与凭据：每个源文件的文件头注释都强调"set up your development environment, including your credentials"，即需要配置 AWS 访问密钥（Access Key / Secret Key）；
3. 可选：指定区域：所有示例的main函数中都保留了如下可取消注释的代码，用于覆盖配置文件中的区域设置：

Aws::Client::ClientConfiguration clientConfig; // Optional: Set to the AWS Region (overrides config file). // clientConfig.region = "us-east-1";

官方提醒的成本与安全事项

文档明确列出四点运行警告，编写生产代码时务必逐条核对：

• 可能产生费用：运行示例代码以及运行测试都可能使你的 AWS 账户产生费用；
• 最小权限原则：建议按"least privilege"授权，只授予完成任务所需的最小权限集，而不要直接使用管理员权限；
• 区域差异：这些代码并未在所有 AWS 区域经过测试，部署前应确认目标服务在你使用的区域可用；
• 短信沙箱限制：首次使用 SNS 发送短信时，账户处于 SMS sandbox（短信沙箱）状态，只能向已验证的目的地手机号发送；且如果目的地在美国，还必须使用专用发起 ID（origination number）。

构建与运行：读懂 CMake 与 run_ 前缀可执行文件

构建系统约定

CMakeLists.txt 展示了这类示例的标准构建方式：

• 要求CMake ≥ 3.13，C++ 标准为C++11，默认构建共享库（BUILD_SHARED_LIBS ON）；
• 通过find_package(AWSSDK REQUIRED COMPONENTS sns)链接 AWS SDK 的 SNS 组件；
• Windows 下会把 SDK 的 DLL 自动拷贝到构建目录，便于直接调试运行；
• 支持用-DAWSDOC_SOURCE=xxx.cpp只构建指定文件（对单个操作进行快速验证非常有用）；
• 每个.cpp源文件会被编译成前缀为run_的可执行文件，例如create_topic.cpp生成run_create_topic；
• 当开启-DBUILD_TESTS=ON时，会额外进入tests子目录构建 GoogleTest 测试。

运行规则

文档给出的核心约定是：每个源文件都会生成一个可执行文件，命名规则是run_+ 源文件名（去掉后缀）。例如要运行my_action.cpp，在构建目录中执行：

./run_my_action

命令运行后会提示所需的参数。每个示例的main函数都带有参数个数校验，例如 create_topic.cpp 中：

int main(int argc, char **argv) { if (argc != 2) { std::cout << "Usage: run_create_topic <topic_name>" << std::endl; return 1; }

统一的程序骨架

几乎每个示例都遵循同一套 SDK 生命周期管理模板：

Aws::SDKOptions options; Aws::InitAPI(options); // 全局初始化，整个进程只应调用一次 { // 在此作用域内使用 SNSClient } Aws::ShutdownAPI(options); // 全局清理，与 InitAPI 成对出现

同时所有示例都用#ifndef TESTING_BUILD包裹main函数——当以测试模式构建（即定义TESTING_BUILD宏）时，main会被排除，从而允许测试代码直接调用AwsDoc::SNS命名空间下的函数。

入门第一步：Hello Amazon SNS（ListTopics）

入门示例 hello_sns/hello_sns.cpp 的目标是初始化 SNS 客户端并列出当前账号下的所有 Topic。它是理解 SDK 分页处理的极好素材：

Aws::SNS::SNSClient snsClient(clientConfig); Aws::Vector<Aws::SNS::Model::Topic> allTopics; Aws::String nextToken; // Next token is used to handle a paginated response. do { Aws::SNS::Model::ListTopicsRequest request; if (!nextToken.empty()) { request.SetNextToken(nextToken); } const Aws::SNS::Model::ListTopicsOutcome outcome = snsClient.ListTopics(request); if (outcome.IsSuccess()) { const Aws::Vector<Aws::SNS::Model::Topic> &paginatedTopics = outcome.GetResult().GetTopics(); if (!paginatedTopics.empty()) { allTopics.insert(allTopics.cend(), paginatedTopics.cbegin(), paginatedTopics.cend()); } } else { std::cerr << "Error listing topics " << outcome.GetError().GetMessage() << std::endl; return 1; } nextToken = outcome.GetResult().GetNextToken(); } while (!nextToken.empty());

这段代码有三个值得注意的设计点：

1. 分页（Pagination）模式：ListTopics默认返回有限条记录，通过响应中的NextToken令牌循环请求下一页，直到令牌为空——这是 AWS 列表类 API 的标准处理手法，ListSubscriptions同样采用了此模式；
2. 统一错误处理：每次调用后用outcome.IsSuccess()判断成败，失败时通过outcome.GetError().GetMessage()输出可读的错误信息并终止程序；
3. 输出统计：程序最终打印Hello Amazon SNS! You have N topics in your account.，并逐行列出所有 Topic 的 ARN，让新手立刻获得"第一次成功调用 SNS"的正反馈。

单一操作（Single actions）：十大 SNS API 逐个击破

以下 10 个操作是文档列出的核心"代码摘录"，每个都对应一个真实可运行的可执行文件。

CreateTopic：创建主题

create_topic.cpp 展示了最基础的"构造请求 → 调用客户端 → 检查结果"三步范式：

bool AwsDoc::SNS::createTopic(const Aws::String &topicName, Aws::String &topicARNResult, const Aws::Client::ClientConfiguration &clientConfiguration) { Aws::SNS::SNSClient snsClient(clientConfiguration); Aws::SNS::Model::CreateTopicRequest request; request.SetName(topicName); const Aws::SNS::Model::CreateTopicOutcome outcome = snsClient.CreateTopic(request); if (outcome.IsSuccess()) { topicARNResult = outcome.GetResult().GetTopicArn(); std::cout << "Successfully created an Amazon SNS topic " << topicName << " with topic ARN '" << topicARNResult << "'." << std::endl; } else { std::cerr << "Error creating topic " << topicName << ":" << outcome.GetError().GetMessage() << std::endl; topicARNResult.clear(); } return outcome.IsSuccess(); }

关键点：SetName只接受主题名称（不是 ARN）；创建成功后返回的topicARNResult是后续所有操作（订阅、发布、删除）都要用到的主题 ARN。运行方式：run_create_topic <topic_name>。

DeleteTopic：删除主题

delete_topic.cpp 与创建对称：只需在DeleteTopicRequest上SetTopicArn(topicARN)即可删除主题。注意：删除主题会同时删除该主题的所有订阅，是不可逆操作。运行方式：run_delete_topic <topic_arn>。

ListTopics 与 ListSubscriptions：分页遍历资源

list_topics.cpp 与 list_subscriptions.cpp 展示了两种略有差异的分页实现：

• listTopics在循环体内逐页打印 ARN；
• listSubscriptions先把所有页的数据累积到Aws::Vector<Aws::SNS::Model::Subscription>，循环结束后统一打印，并特判了"无订阅"的空结果场景（No subscriptions found）。

运行方式：run_list_topics、run_list_subscriptions，均无参数。

GetTopicAttributes：查看主题属性

get_topic_attributes.cpp 通过GetTopicAttributes读取主题的全部属性（如订阅数、策略、DisplayName 等），属性以Aws::Map<Aws::String, Aws::String>键值对形式返回：

if (outcome.IsSuccess()) { std::cout << "Topic Attributes:" << std::endl; for (auto const &attribute: outcome.GetResult().GetAttributes()) { std::cout << " * " << attribute.first << " : " << attribute.second << std::endl; } }

运行方式：run_get_topic_attributes <topic_arn>，前置条件为已存在的主题 ARN。与它同级的还有get_subscription_attributes.cpp（查询订阅属性）。

Publish：向主题发布消息

publish_to_topic.cpp 是发布/订阅模型的核心——生产者侧：

Aws::SNS::Model::PublishRequest request; request.SetMessage(message); request.SetTopicArn(topicARN); const Aws::SNS::Model::PublishOutcome outcome = snsClient.Publish(request); if (outcome.IsSuccess()) { std::cout << "Message published successfully with id '" << outcome.GetResult().GetMessageId() << "'." << std::endl; }

发布成功后服务端会返回MessageId，可用于后续追踪与去重。运行方式：run_publish_to_topic <message_value> <topic_arn_value>。

Subscribe / Unsubscribe：订阅与退订

订阅端由三个文件分别演示三种投递协议：

• subscribe_email.cpp：协议为"email"，端点填邮箱地址。注意Subscribe成功后返回的SubscriptionArn此时可能是PendingConfirmation状态，需要收件人点击确认邮件后订阅才生效；
• subscribe_app.cpp：协议为移动应用端点（endpoint ARN），适用于移动推送场景；
• subscribe_lambda.cpp：协议为 AWS Lambda 函数 ARN，实现"SNS 触发 Lambda"的事件驱动模式。

三者都遵循同一模式：request.SetTopicArn(topicARN)+request.SetProtocol(...)+request.SetEndpoint(...)。对应的unsubscribe.cpp只需在UnsubscribeRequest上设置订阅 ARN 即可退订。

SetSMSAttributes / GetSMSAttributes：短信配置管理

短信场景下，SNS 的默认设置通过账户级属性管理：

• set_sms_type.cpp：通过SetSMSAttributes写入DefaultSMSType属性，参数取值为"Transactional"（交易型，高优先级、通常按条计费）或"Promotional"（营销型，更便宜、可能延迟）：

Aws::SNS::Model::SetSMSAttributesRequest request; request.AddAttributes("DefaultSMSType", smsType);

• get_sms_type.cpp：通过GetSMSAttributes读取当前默认短信类型。源码注释特别提醒：request.AddAttributes("DefaultSMSType")是为了只取这一个属性，如果不加这一行，会返回账户的全部短信设置：

//Set the request to only retrieve the DefaultSMSType setting. //Without the following line, GetSMSAttributes would retrieve all settings. request.AddAttributes("DefaultSMSType");

运行方式：run_set_sms_type <sms_type>、run_get_sms_type。

场景（Scenarios）：把 API 串成真实业务

文档还列出了三个"多函数协作"的场景示例，展示了 SNS 在实际架构中的常见用法。

场景一：发布短信文本消息（publish_sms）

publish_sms.cpp 与"向主题发布"不同，它绕开主题，直接调用PublishRequest.SetPhoneNumber(phoneNumber)向指定手机号发短信。源码注释给出两个生产级限制：

• E.164 格式：手机号必须符合 E.164 国际格式，例如美国号码形如+12223334444；
• 短信沙箱：新账户只能向已验证号码发送；目的地在美国时还需专用发起 ID（origination number）。

运行方式：run_publish_sms <message_value> <phone_number_value>。

场景二：把消息发布到 SQS 队列（Topics and Queues）

文档描述该场景可完成以下流程：

1. 创建主题（FIFO 或非 FIFO 均可）；
2. 将多个 SQS 队列订阅到主题，并可选应用消息过滤策略（filter policy）；
3. 向主题发布消息；
4. 轮询各队列，确认消息被正确接收。

完整实现位于 messaging_with_topics_and_queues.cpp，它把 SNS 的CreateTopic、Subscribe、Publish与 SQS 的队列创建、轮询读取组合在一起，是"SNS 扇出到多个队列"这一经典解耦架构的可运行范本。

场景三：无服务器照片管理应用（Photo Asset Manager）

文档将跨服务示例 photo_asset_manager 也列为场景之一——它演示如何构建一个让用户按标签（labels）管理照片的无服务器应用。该应用体现了 SNS 在事件通知链中的实际价值：照片上传、标签分析、通知推送等环节相互配合，SNS 作为其中的消息枢纽承担解耦职责。

测试：GoogleTest 驱动的质量保障

文档提供了标准的测试构建与执行流程：

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

测试代码位于 cpp/example_code/sns/tests，从目录内容可以清晰地看出测试策略：

• 按操作划分的测试用例：gtest_create_topic.cpp、gtest_delete_topic.cpp、gtest_list_topics.cpp、gtest_publish_to_topic.cpp、gtest_set_sms_type.cpp、gtest_subscribe_email.cpp、gtest_unsubscribe.cpp等，与上文每个单一操作一一对应；
• Mock 输入支持：tests/mock_input/下存放了subscribe_app.xml、subscribe_email.xml、subscribe_lambda.xml等 XML 文件，用于模拟不同订阅协议所需的参数输入；
• 统一测试入口：test_main.cpp、sns_gtests.cpp/sns_gtests.h提供测试框架的组装与公共断言辅助；
• 无 main 参与：正因为源码中main被TESTING_BUILD宏隔离，测试代码才能直接复用AwsDoc::SNS命名空间中的真实函数，实现"既测函数逻辑、又不污染命令行入口"的双重目的。

结语与后续深入学习路径

本文从 cpp/example_code/sns/README.md 出发，完整梳理了 AWS SDK for C++ 操作 Amazon SNS 的整套示例体系：统一的run_可执行文件约定、Hello 入门的分页范式、10 个单一操作 API、3 个跨服务场景，以及基于 GoogleTest 的测试闭环。无论你是要搭建消息通知系统、实现短信告警，还是构建"主题→队列/Lambda"的异步解耦架构，这套示例都提供了可直接运行、可直接改造的参考实现。

若想继续深入，可以进一步研读该目录中的 sns_samples.h（完整 API 声明）、CMakeLists.txt（构建细节），以及跨服务的 topics_and_queues 场景 与 photo_asset_manager 应用。同时建议对照 Amazon SNS Developer Guide 与 Amazon SNS API Reference 查阅各请求/响应字段的完整取值范围，以在实际项目中获得最大收益。

• 示例工程
• 教程
• 后端