企业官网建设流程全解析

• 后端
• 网络

Bearer Token（不记名令牌）是 OAuth 2.0 与现代 Web API 最通用的认证方式之一，调用方只需在请求头中携带Authorization: Bearer <token>即可完成身份校验。本文围绕 cpp-httplib 的客户端 API，系统讲解set_bearer_token_auth()、make_bearer_token_authentication_header()等核心接口的使用方法，并结合仓库源码揭示其底层实现原理与安全边界，帮助你用 C++ 正确、安全地对接 GitHub、Slack 等任何基于令牌的 API 服务，读完即可在你的项目中直接落地。

前置准备：引入头文件与创建客户端

cpp-httplib 是 header-only 库，只需在编译单元中包含 httplib.h 即可，无需链接额外库（除非使用 TLS 功能需要链接 OpenSSL 等后端，见 t01-tls-backends.md）。

#include "httplib.h" httplib::Client cli("https://api.example.com");

对于 HTTPS 接口，建议为客户端指定 CA 证书目录或文件，仓库提供了参考实现：例如 example/client.cc 与 example/server_and_client.cc 都展示了通过cli.set_ca_cert_path(...)加载 CA 的写法，可按需参考。

基础用法：一次设置，所有请求自动携带令牌

Bearer Token 认证最常见的场景是：获取一次令牌（如 OAuth 2.0 授权码流程换取 access_token），后续所有请求都携带它。cpp-httplib 为此提供了set_bearer_token_auth()，传入令牌后，库会自动为你构造Authorization: Bearer <token>请求头。

httplib::Client cli("https://api.example.com"); cli.set_bearer_token_auth("eyJhbGciOiJIUzI1NiIs..."); // 你的 access token auto res = cli.Get("/me"); if (res && res->status == 200) { std::cout << res->body << std::endl; }

调用一次set_bearer_token_auth()后，该客户端实例发出的每一个请求都会携带令牌，无需在每次请求中重复传入。这是对接 GitHub、Slack 等令牌型 API 以及自建 OAuth 服务的标准写法。

源码视角：令牌存到哪里、何时注入请求头

从源码可以确认，令牌被保存在客户端实例内部，并在真正发送请求时自动注入：

• 成员存储：httplib.h 中ClientImpl持有std::string bearer_token_auth_token_；
• 设置接口：httplib.h 中ClientImpl::set_bearer_token_auth()仅是简单赋值，Client对外包装为 httplib.h；
• 注入时机：httplib.h 中，在组装请求行与头部之前，若请求尚未携带Authorization头，则按"先 Basic、后 Bearer"的优先级插入make_bearer_token_authentication_header(bearer_token_auth_token_, false)生成的头部。

注意这段逻辑有个重要的细节：如果请求本身已带有Authorization头，客户端设置的令牌不会被覆盖（!req.has_header("Authorization")才注入）。因此当你需要"单次请求临时换令牌"时，直接通过 per-request headers 传入即可，无需担心与已设置的默认令牌冲突。

按请求使用：单次请求临时指定令牌

当令牌只需要用于某一次请求，或不同请求需要不同令牌时，可以通过 headers 参数直接传入。cpp-httplib 提供了便捷的make_bearer_token_authentication_header()工厂函数：

httplib::Headers headers = { httplib::make_bearer_token_authentication_header(token), }; auto res = cli.Get("/me", headers);

该函数内部把"Bearer " + token组装成字段值，并返回std::pair<std::string, std::string>，键为Authorization（默认）或Proxy-Authorization（第二个参数传true时），实现见 httplib.h。它与 Basic 认证的make_basic_authentication_header()保持一致的签名风格，便于记忆。

提示：httplib::Headers本质上是std::multimap<std::string, std::string>类型，因此通过cli.Get(path, headers)、cli.Post(path, headers, body)等重载均可传入。

令牌刷新：捕获 401 后无缝续期

OAuth 2.0 的 access token 有生命周期，过期后服务器会返回401 Unauthorized。此时只需用新令牌再次调用set_bearer_token_auth()即可覆盖旧值，后续请求自动使用新令牌：

auto res = cli.Get("/me"); if (res && res->status == 401) { auto new_token = refresh_token(); // 用 refresh_token 换新 access token cli.set_bearer_token_auth(new_token); // 覆盖旧令牌 res = cli.Get("/me"); // 重试 }

由于set_bearer_token_auth()是简单的赋值操作（见 httplib.h），刷新令牌的开销极低，也天然具备线程安全所需的"先换值、后发请求"的顺序——你可以在重试前先更新令牌，再发起新请求。

服务端校验：用get_bearer_token_auth()解析请求中的令牌

如果你同时用 cpp-httplib 编写服务端，可以在处理器中通过httplib::get_bearer_token_auth(const Request &req)提取令牌进行校验。该函数实现于 httplib.h：

svr.Get("/me", [](const httplib::Request &req, httplib::Response &res) { auto token = httplib::get_bearer_token_auth(req); if (token.empty()) { res.status = 401; res.set_content("missing or invalid token", "text/plain"); return; } res.set_content("hello, " + token, "text/plain"); });

从源码可以看到两个值得注意的细节：

• scheme 匹配不区分大小写：实现中detail::case_ignore::equal使Bearer与bearer均可识别（RFC 9110 规定认证 scheme 大小写不敏感）；
• 长度防护：先判断value.size() >= strlen("Bearer ")再执行固定长度的substr，避免短值触发越界或异常；前缀不匹配或长度不足时返回空字符串。

仓库的单元测试 test/test.cc（BearerTokenAuthTest.SchemeValidation）专门验证了这几种边界情况："x"返回空、"Basic ..."不会被误判为 Bearer、"Bearer abc123"正确提取abc123、小写"bearer abc123"同样生效。

进阶一：设置默认请求头（适用多端点场景）

当客户端需要命中多个 API 端点时，除了set_bearer_token_auth()，还可以用set_default_headers()统一配置，例如把 Bearer 令牌与Accept、User-Agent一起注册为默认头：

httplib::Client cli("https://api.example.com"); cli.set_default_headers({ {"Authorization", "Bearer " + token}, {"Accept", "application/json"}, }); auto res1 = cli.Get("/me"); auto res2 = cli.Get("/projects");

该方式同样能做到"设置一次、处处携带"，与set_bearer_token_auth()的效果等价。需要注意两点：

• set_default_headers()是整体替换语义，即使只想增加一个头，也要把完整集合重新传入；
• 每次请求仍可通过 per-request headers 追加额外头部，二者会同时发送。

更完整的说明可参考 C03. 设置默认请求头，其中还给出了与每请求头组合使用的示例。

进阶二：通过代理访问时的 Bearer 认证（Proxy-Authorization）

当客户端经 HTTP 代理访问目标时，可以为代理单独配置 Bearer 令牌，此时生成的头部键为Proxy-Authorization而不是Authorization：

cli.set_proxy("proxy.example.com", 8080); cli.set_proxy_bearer_token_auth("proxy-pass"); // 发给代理 cli.set_bearer_token_auth("origin-token"); // 发给目标服务器

对应实现为 httplib.h 的ClientImpl::set_proxy_bearer_token_auth()，注入逻辑见 httplib.h：只有代理确实读取这条消息（is_proxy_enabled_for_host(host_)且非 TLS 隧道内直连）时才注入代理凭证，避免向目标服务器泄漏代理凭据。仓库测试 test/test.cc（ProxyTunnelTest.BearerCredentialsStayWithTheirHop）验证了"代理令牌只到代理、源站令牌只到源站"的隔离行为，README 中也有对应示例（README.md）。

安全边界与最佳实践

文档与源码共同提醒以下几点，直接影响生产环境的正确性：

1. Bearer Token 本身就是一种凭证：务必通过 HTTPS 传输（cli的 URL 使用https://），明文 HTTP 下令牌可被中间人截获；
2. 不要硬编码令牌：令牌不应写死在源码或配置文件里，建议从环境变量、密钥管理服务（如 Vault/KMS）或运行时凭据注入读取；
3. 避免跨跳泄漏：经代理访问时，源站令牌与代理令牌分别使用Authorization与Proxy-Authorization，二者不会互相串扰（见 httplib.h 的 hop-by-hop 处理）；
4. 重定向安全：从源码结构看，cpp-httplib 在重定向场景下有意识地不做凭证转发——测试 test/test.cc（RedirectToDifferentPort.DoNotForwardCredentialsBearerToken）验证了携带 Bearer 令牌的客户端在重定向到其他端口时不会把令牌泄露给新目标，这与浏览器对敏感头跨站处理的思路一致；
5. 令牌刷新：收到401后刷新令牌并重试是标准续期模式，若连续失败应终止重试并向上层报告，避免在凭证失效时反复空转。

小结

cpp-httplib 把 Bearer Token 认证封装成三个层面：全局默认（set_bearer_token_auth()）、单请求注入（make_bearer_token_authentication_header()）与代理专用（set_proxy_bearer_token_auth()），服务端则可用get_bearer_token_auth()反向解析。核心实现在 httplib.h 与 httplib.h，测试佐证在 test/test.cc，均可直接查阅验证。组合"设置一次、自动携带、401 刷新、HTTPS 传输"四步，即可稳妥地完成任何 OAuth 2.0 风格 API 的 C++ 客户端对接。

• 后端
• 网络