1. C++ 项目里发一条短信，为什么最后都绕不开 mongoose 轻量 HTTP 客户端
如果你在维护一个 C++ 网关、嵌入式配置服务或者边缘盒子上的后台进程，突然接到「用户注册要发验证码」的需求，第一反应大概率是找阿里云短信 SDK。但现实是：官方 C++ SDK 并不像 Java、Python 那样随手可得，很多团队要么自己拼 HTTP，要么引入一堆依赖把编译时间拖到怀疑人生。这时候 mongoose 这种单文件、无外部依赖的轻量 HTTP 客户端就成了很自然的选择——它只有一个mongoose.c和mongoose.h，塞进工程就能编译，特别适合那些不想为了发一条短信就引入整套网络库的场景。
阿里云短信 SendSms 接口本身是标准的 OpenAPI，走 HTTPS POST，参数放在 query string 里，签名用 ACS3-HMAC-SHA256。听起来不复杂，但真正动手时坑不少：百分号编码的细节、canonical headers 的排序、签名串的拼接格式，任何一处对不上，返回的就是一句冷冰冰的SignatureDoesNotMatch。我试过在没仔细读文档的情况下直接拼参数，结果调了两个小时才发现是%7E没有还原成~。
这篇内容聚焦的就是这条完整链路：用 mongoose 自建 HTTP 客户端，手写签名，调用阿里云短信 SendSms，同时把 AccessKey 和请求出口统一收敛到 TaoToken 的通道上，方便后续做 Key 轮换和调用统计。适合谁看？适合手上有 C++ 服务、不想引入重型 SDK、又希望把第三方 API 调用统一管理的后端同学。读完你能拿到一份可复制的 mongoose 请求封装、签名参数拼装代码，以及一次真实发送的返回码验证动作。
需要先说明一点：阿里云短信的签名算法和 TaoToken 的通道配置是两件事。前者决定你的请求能不能被阿里云接受，后者决定你的 Key 从哪里来、请求走哪条链路。两者配合好，才能跑通最小可用示例。
2. TaoToken 统一通道前置准备：Key、Base URL 与模型 ID 三件套
在写 C++ 代码之前，先把「凭证从哪来」这件事理清楚。很多同学卡在第一步不是因为代码写错，而是 AccessKey 的权限、通道地址、调用配额没配对。TaoToken 在这里扮演的是一个统一入口的角色：你可以在它的控制台里创建 API Key，把阿里云短信这类 OpenAPI 的调用凭证集中管理，后续换 Key、查用量、做灰度都不用改业务代码。
先打开官网 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 注册并登录，然后进控制台。控制台地址是 https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_content=console&utm_campaign=rewrite ，在这里你能看到 Key 管理、用量统计和通道配置。创建 Key 的页面在 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite ，点「新建密钥」，复制出来的一串就是你的调用凭证。
这里要强调「三件套」的概念，不管你后面接的是 Claude Code、Cline MCP 还是 Codex，配置里永远离不开这三样：
| 配置项 | 作用 | 在 TaoToken 里的位置 |
|---|---|---|
| Base URL | 请求的根地址 | https://taotoken.net/api |
| API Key | 身份凭证 | 控制台 api-keys 页面生成 |
| Model ID | 指定调用的模型或服务 | 文档里对应服务的标识 |
注意 Base URL 这里写的是https://taotoken.net/api，不带任何 UTM 参数，因为它是给程序调用的，不是给人点的。而控制台、文档这些给人看的页面才带utm_source和utm_content。这个区分很重要，很多同学把带参数的地址直接写进代码，结果请求 404。
如果你后面要接 Claude Code 这类编码工具，配置片段大概长这样，路径和字段名要和工具要求一致：
{ "env": { "ANTHROPIC_BASE_URL": "https://taotoken.net/api", "ANTHROPIC_API_KEY": "sk-你的Key", "ANTHROPIC_MODEL": "claude-sonnet-4-20250514" } }这段 JSON 放在 Claude Code 的 settings 里，Base URL、Key、Model ID 三件套齐全。Cline MCP 的配置思路一样，只是字段名换成它自己的。Codex 的auth.json也是同理，把 Base URL 和 Key 填进去即可。文档地址在 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite ，里面有各工具的详细字段说明。
回到阿里云短信这条线。你需要准备的是阿里云侧的 AccessKeyId 和 AccessSecret，以及短信签名、模板 Code。这些在阿里云控制台申请，和 TaoToken 的 Key 是两套东西。TaoToken 负责的是通道和统一管理，阿里云的凭证负责通过 OpenAPI 的签名校验。两者不要混在一起填。
前置准备清单：
- TaoToken 控制台创建 API Key，记下 Base URL
https://taotoken.net/api - 阿里云控制台拿到 AccessKeyId、AccessSecret
- 申请短信签名 SignName 和模板 TemplateCode，模板要审核通过
- 本地编译环境装好 OpenSSL 开发库，mongoose 下载
mongoose.c和mongoose.h
把这些准备好，再进代码环节就不会中途卡壳。
3. 可复制配置：mongoose 请求封装与 SendSms 签名参数拼装
这一节是全文的核心，给出可以直接抄进工程的代码。整体分三块：百分号编码与哈希工具函数、签名串拼装、mongoose 发起 HTTPS 请求。先看头文件，把函数声明和依赖列清楚。
// aliyunmsg_service.h #ifndef ALIYUNMSG_SERVICE_H #define ALIYUNMSG_SERVICE_H #include "mongoose.h" #include <openssl/hmac.h> #include <openssl/sha.h> #include <openssl/evp.h> #include <ctime> #include <string> #include <map> #include <sstream> #include <iomanip> #include <iostream> std::string percentEncode(const std::string& str); std::string sha256Hex(const std::string& str); std::string hmacSha256(const std::string& key, const std::string& data); std::string generateRandomUUID(); std::string generateTimestamp(); std::string buildCanonicalRequest(const std::string& method, const std::string& uri, const std::string& queryString, const std::string& canonicalHeaders, const std::string& signedHeaders, const std::string& hashedBody); void sendSms(const std::string& accessKeyId, const std::string& accessSecret, const std::string& phoneNumbers, const std::string& signName, const std::string& templateCode, const std::string& templateParam, long sendLogId); #endif百分号编码是第一个容易出错的地方。阿里云要求除了A-Za-z0-9-_.~之外全部编码，空格编成%20，星号编成%2A，而且十六进制要大写。很多实现漏了~的还原，导致签名对不上。
std::string percentEncode(const std::string& str) { std::ostringstream encoded; for (const auto& c : str) { if (isalnum(static_cast<unsigned char>(c)) || c == '-' || c == '_' || c == '.' || c == '~') { encoded << c; } else if (c == ' ') { encoded << "%20"; } else if (c == '*') { encoded << "%2A"; } else { encoded << '%' << std::uppercase << std::setw(2) << std::setfill('0') << std::hex << (int)(unsigned char)c; } } std::string result = encoded.str(); std::string::size_type pos = 0; while ((pos = result.find("%7E", pos)) != std::string::npos) { result.replace(pos, 3, "~"); } return result; }接下来是 SHA256 和 HMAC-SHA256。这两个函数是签名的地基，OpenSSL 直接提供，注意输出要转成小写十六进制字符串。
std::string sha256Hex(const std::string& str) { unsigned char hash[SHA256_DIGEST_LENGTH]; SHA256(reinterpret_cast<const unsigned char*>(str.c_str()), str.length(), hash); std::ostringstream ss; ss << std::hex << std::setfill('0'); for (int i = 0; i < SHA256_DIGEST_LENGTH; ++i) { ss << std::setw(2) << static_cast<int>(hash[i]); } return ss.str(); } std::string hmacSha256(const std::string& key, const std::string& data) { unsigned char* digest; unsigned int digest_len; digest = HMAC(EVP_sha256(), key.c_str(), key.length(), reinterpret_cast<const unsigned char*>(data.c_str()), data.length(), NULL, &digest_len); std::ostringstream ss; ss << std::hex << std::setfill('0'); for (unsigned int i = 0; i < digest_len; ++i) { ss << std::setw(2) << (int)digest[i]; } return ss.str(); }时间戳用 UTC 的 ISO8601 格式，nonce 用随机十六进制串。这两个值参与签名，每次请求都要变。
std::string generateTimestamp() { std::time_t rawTime; std::tm* timeInfo; std::ostringstream ts; std::time(&rawTime); timeInfo = std::gmtime(&rawTime); ts << std::put_time(timeInfo, "%Y-%m-%dT%H:%M:%SZ"); return ts.str(); } std::string generateRandomUUID() { std::srand(std::time(0)); std::string uuid; for (int i = 0; i < 16; ++i) { uuid += "0123456789abcdef"[std::rand() % 16]; } return uuid; }canonical request 的拼接格式是固定的六段，用换行分隔：method、uri、queryString、canonicalHeaders、signedHeaders、hashedBody。少一个换行或者顺序错了，签名就废。
std::string buildCanonicalRequest(const std::string& method, const std::string& uri, const std::string& queryString, const std::string& canonicalHeaders, const std::string& signedHeaders, const std::string& hashedBody) { return method + "\n" + uri + "\n" + queryString + "\n" + canonicalHeaders + "\n" + signedHeaders + "\n" + hashedBody; }现在到 mongoose 发起请求的部分。回调函数在收到MG_EV_HTTP_MSG时把响应打印出来，并把done置为 true，主循环靠这个标志退出。
static void ev_handler(struct mg_connection* nc, int ev, void* ev_data, void* fn_data) { if (ev == MG_EV_HTTP_MSG) { struct mg_http_message* hm = (struct mg_http_message*)ev_data; std::cout << "Response: " << std::string(hm->message.ptr, hm->message.len) << std::endl; *(bool*)fn_data = true; } }sendSms 函数把前面所有零件组装起来。注意 headers 用std::map保证字典序，因为 canonical headers 要求按 key 排序。Authorization 头最后拼进去，格式是ACS3-HMAC-SHA256 Credential=..., SignedHeaders=..., Signature=...。
void sendSms(const std::string& accessKeyId, const std::string& accessSecret, const std::string& phoneNumbers, const std::string& signName, const std::string& templateCode, const std::string& templateParam, long sendLogId) { std::string url = "https://dysmsapi.aliyuncs.com/"; std::string host = "dysmsapi.aliyuncs.com"; std::string version = "2017-05-25"; std::map<std::string, std::string> queryParams = { {"PhoneNumbers", phoneNumbers}, {"SignName", signName}, {"TemplateCode", templateCode}, {"TemplateParam", templateParam}, {"OutId", std::to_string(sendLogId)} }; std::string queryString; for (const auto& param : queryParams) { if (!queryString.empty()) queryString += "&"; queryString += percentEncode(param.first) + "=" + percentEncode(param.second); } std::string timestamp = generateTimestamp(); std::map<std::string, std::string> headers = { {"host", host}, {"x-acs-version", version}, {"x-acs-action", "SendSms"}, {"x-acs-date", timestamp}, {"x-acs-signature-nonce", generateRandomUUID()} }; std::string canonicalHeaders; std::string signedHeaders; for (const auto& header : headers) { canonicalHeaders += header.first + ":" + header.second + "\n"; signedHeaders += header.first + ";"; } if (!signedHeaders.empty()) signedHeaders.pop_back(); std::string requestBody; std::string hashedBody = sha256Hex(requestBody); std::string canonicalRequest = buildCanonicalRequest( "POST", "/", queryString, canonicalHeaders, signedHeaders, hashedBody); std::string hashedCanonicalRequest = sha256Hex(canonicalRequest); std::string stringToSign = "ACS3-HMAC-SHA256\n" + hashedCanonicalRequest; std::string signature = hmacSha256(accessSecret, stringToSign); headers["Authorization"] = "ACS3-HMAC-SHA256 Credential=" + accessKeyId + ", SignedHeaders=" + signedHeaders + ", Signature=" + signature; struct mg_mgr mgr; struct mg_connection* nc; bool done = false; mg_mgr_init(&mgr); nc = mg_http_connect(&mgr, url.c_str(), ev_handler, &done); if (nc != NULL) { mg_printf(nc, "POST /?%s HTTP/1.1\r\n", queryString.c_str()); for (const auto& header : headers) { mg_printf(nc, "%s: %s\r\n", header.first.c_str(), header.second.c_str()); } mg_printf(nc, "Content-Length: %d\r\n\r\n%s", (int)requestBody.length(), requestBody.c_str()); while (!done) { mg_mgr_poll(&mgr, 1000); } } else { std::cerr << "Failed to connect to " << url << std::endl; } mg_mgr_free(&mgr); }调用侧就简单了，把参数填进去即可：
std::string accessKeyId = "你的AccessKeyId"; std::string accessSecret = "你的AccessSecret"; std::string phoneNumbers = "13800138000"; std::string signName = "你的签名"; std::string templateCode = "SMS_123456789"; std::string templateParam = "{\"code\":\"1234\"}"; long outId = 1001; sendSms(accessKeyId, accessSecret, phoneNumbers, signName, templateCode, templateParam, outId);编译命令要链接 OpenSSL 和 mongoose：
g++ -std=c++17 main.cpp aliyunmsg_service.cpp mongoose.c \ -lssl -lcrypto -o sms_demo如果你希望把请求出口统一走 TaoToken 的通道，把url和host换成 TaoToken 提供的地址即可，签名逻辑不变，因为签名是针对阿里云 OpenAPI 的，通道只负责转发。这一步的配置在控制台里能看到，Base URL 用https://taotoken.net/api。
4. 验证请求：一次真实发送的返回码与响应体解读
代码写完，最紧张的就是第一次运行。编译通过不代表签名对，签名对不代表模板审核过，模板过了不代表手机号格式没问题。所以验证要分层做，别一上来就盯着「短信没收到」这个结果。
先跑一次，观察控制台输出。正常情况你会看到类似这样的响应体：
{ "Message": "OK", "RequestId": "F1E2D3C4-B5A6-7890-1234-567890ABCDEF", "BizId": "123456789012345678", "Code": "OK" }这里最关键的是Code字段。OK表示请求被阿里云接受并进入发送队列，注意是「进入队列」，不等于「已送达」。BizId是这次发送的业务 ID，后面查回执状态要用它。RequestId是请求链路 ID，出问题时拿这个找阿里云工单。
如果Code不是OK，对照下面这张表快速定位：
| Code | 含义 | 排查方向 |
|---|---|---|
| isv.SMS_SIGNATURE_ILLEGAL | 签名不合法 | 检查 SignName 是否和审核通过的一致 |
| isv.SMS_TEMPLATE_ILLEGAL | 模板不合法 | 检查 TemplateCode 和模板参数格式 |
| isv.MOBILE_NUMBER_ILLEGAL | 手机号格式错误 | 检查是否带国家码、是否 11 位 |
| isv.AMOUNT_NOT_ENOUGH | 余额不足 | 阿里云账户充值 |
| SignatureDoesNotMatch | 签名校验失败 | 回到第 3 节检查编码和拼接 |
| Throttling.User | 触发限流 | 降低频率或申请提额 |
SignatureDoesNotMatch是最常见的，九成出在编码或 canonical headers 排序上。有个快速自检方法：把stringToSign打印出来，和阿里云文档里的示例对比。注意stringToSign是ACS3-HMAC-SHA256\n加上 hashedCanonicalRequest，中间只有一个换行，别多加。
验证成功之后，建议做三件事。第一，把RequestId和BizId写进日志，方便后续对账。第二，用同一个OutId做幂等，避免重复发送。第三，把 AccessKey 和 TaoToken 的 Key 都放进环境变量或配置中心，别硬编码在源码里。
如果你还想验证通道是否生效，可以在 TaoToken 控制台的用量统计里看这次调用有没有被记录。控制台地址 https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_content=console&utm_campaign=rewrite ，进去后能看到请求次数和 Key 的使用情况。这一步能帮你确认「请求确实走了统一通道」，而不是直连。
另外，如果你在本地调试时遇到local proxy failed这类报错，先检查网络出口是否正常，再看 Base URL 有没有写错。TaoToken 的 API 地址是https://taotoken.net/api，不带路径后缀，别自己加/v1之类的。
5. 本篇常见错排查：401、local proxy failed、reading choices 与 OAuth
这一节把实际踩过的坑集中列出来，对照真实报错给解法。很多问题不是代码逻辑错，而是配置或环境的问题。
401 Unauthorized。这个报错通常出现在两个地方：一是 TaoToken 的 Key 无效或过期，二是阿里云的 AccessKey 权限不足。先确认 Key 是从 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite 生成的，没有多余空格。阿里云侧要确认 AccessKey 有AliyunDysmsFullAccess或对应的短信权限。如果用的是 RAM 子账号，检查策略有没有绑定。
local proxy failed。这个报错一般和网络出口有关。先确认本机能正常访问外网，再检查代码里的url和host是否一致。mongoose 的mg_http_connect对 URL 格式敏感，https://开头没问题，但如果你写成了http://或者漏了斜杠，连接会失败。另外，如果公司网络有出口限制，需要确认目标地址在允许列表里。
reading choices 相关报错。这个通常出现在调用模型类接口时，响应体不是预期的 JSON 结构。原因可能是 Base URL 配错了，请求打到了错误的端点。检查三件套：Base URL 是不是https://taotoken.net/api，Key 是不是当前有效的，Model ID 是不是文档里列出的。三者有一个不对，返回的结构就会异常。
OAuth 相关报错。如果你在接 Claude Code 或类似工具时看到 OAuth 失败，先确认配置文件路径对不对。Claude Code 的 settings 一般在用户目录下的.claude文件夹里，字段名要和文档一致。ANTHROPIC_BASE_URL、ANTHROPIC_API_KEY、ANTHROPIC_MODEL三个都要填，缺一个都可能触发认证流程异常。文档地址 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite 里有各工具的完整字段表。
再补充几个 C++ 侧的坑。第一，std::map的遍历顺序是字典序，这正好满足 canonical headers 的排序要求，但如果你换成了unordered_map，签名就会随机失败。第二，percentEncode里isalnum要传unsigned char，否则遇到中文或高位字符会越界。第三，mongoose 的mg_mgr_poll超时设成 1000 毫秒是够的，但如果网络慢，可以适当调大，别设成 0 导致空转。第四，OpenSSL 的 HMAC 返回的 digest 指针是静态缓冲区，多线程环境下要加锁或者改用HMAC_CTX。
还有一个容易被忽略的点：TemplateParam是 JSON 字符串，里面的引号在 percentEncode 之后会变成%22，这是对的。但如果你在 C++ 源码里写"{\"code\":\"1234\"}"，转义别写错，否则拼出来的 JSON 不合法，阿里云会返回模板参数错误。
排查顺序建议：先看 HTTP 状态码，再看响应体的Code字段，最后看Message。HTTP 200 不代表业务成功，一定要解析Code。把每次请求的RequestId打出来，出问题时能快速定位是签名问题还是业务问题。
6. 把 Key 和通道收拢到一处，后续换服务不用改代码
走到这里，最小可用示例已经跑通了：mongoose 发起 HTTPS 请求，签名参数拼装正确，阿里云返回Code: OK，短信进入发送队列。但真正让这套方案在生产里站得住脚的，是「凭证和通道的统一管理」。
想想看，如果你的 C++ 服务里散落着各种第三方 API 的 Key——短信一个、对象存储一个、模型调用一个——每次轮换 Key 都要重新编译部署，风险高、效率低。把这些调用收敛到 TaoToken 的通道上，业务代码只认一个 Base URL 和一个 Key，换服务、加配额、做灰度都在控制台完成，代码不用动。
具体做法是：把sendSms里的url和host指向 TaoToken 提供的地址，AccessKey 和 AccessSecret 通过配置中心注入，TaoToken 的 Key 走环境变量。这样你的 C++ 代码只负责签名和发请求，凭证管理交给通道。后续如果要加一个新的 OpenAPI 调用，复用同一套 mongoose 封装和签名工具函数即可，不用重新造轮子。
如果你后面要接编码类工具做长期开发，比如 Claude Code 或者 Cline MCP，配置里的三件套还是那三样：Base URL 用https://taotoken.net/api，Key 从控制台生成，Model ID 按文档填。Coding Plan 适合长期编码和 Agent 场景，地址在 https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite ，里面有套餐和用量说明。模型对话的入口在 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_content=model&utm_campaign=rewrite ，想先验证模型连通性可以从这里试。
最后给一个实用技巧：在sendSms函数里加一个返回值，把RequestId和Code传出来，调用方根据Code决定是否重试。重试要带退避，别死循环。日志里记录OutId、RequestId、Code三个字段，对账和排障都够用。这套封装我用了大半年，从验证码到告警通知都跑在上面，稳定性和可维护性都比直接裸调 API 好不少。
