企业官网建设流程全解析

• 后端
• 网络

cpp-httplib 作为一款 header-only 的 C++ HTTP/HTTPS 客户端与服务端库，默认情况下不会自动跟随服务端返回的 3xx 重定向响应。本文围绕官方 Cookbook 文档 c04-follow-location.md 展开，讲解如何通过set_follow_location(true)一键开启自动跟随重定向，并结合仓库源码 httplib.h 与测试用例 test/test.cc 剖析其底层实现、HTTP→HTTPS 跳转的 TLS 要求、跨主机跳转的安全策略（凭据不转发）以及最大重定向次数限制，帮助读者在实际项目中安全、高效地处理 URL 迁移、站点跳转等常见场景。

默认行为：客户端不会跟随 3xx 重定向

在使用httplib::Client发起请求时，如果服务端返回了301 Moved Permanently、302 Found、303 See Other、307 Temporary Redirect、308 Permanent Redirect等 3xx 状态码，客户端默认只把它当作一次普通响应返回给你——响应对象的status就是 3xx，正文（如果有的话）随响应一并返回，除此之外不会做任何额外动作。

httplib::Client cli("http://example.com"); auto res = cli.Get("/old-path"); // 默认情况下：res->status == 302，并不会自动请求 Location 指向的新地址 if (res && res->status == 302) { std::cout << "Server wants us to redirect" << std::endl; }

从源码可以印证这一点：httplib.h中客户端成员follow_location_的默认值是false（见 httplib.h），对应的开关接口set_follow_location(bool on)只是简单地把该标志置位（见 httplib.h）。只有在这个标志为true时，请求发送流程中才会触发重定向逻辑：

if (300 < res.status && res.status < 400 && follow_location_) { req = std::move(req_save); ret = redirect(req, res, error); }

（见 httplib.h）

这段代码位于客户端send()的内部流程中，说明"跟随重定向"并不是在请求发出前预判的，而是在收到 3xx 响应、读取到Location头之后再重新组织请求、自动发起第二次请求。

开启自动跟随：set_follow_location(true)

要让客户端自动处理重定向链，只需要一行配置：

#include "httplib.h" #include <iostream> httplib::Client cli("http://example.com"); cli.set_follow_location(true); // 开启自动跟随重定向 auto res = cli.Get("/old-path"); if (res && res->status == 200) { std::cout << res->body << std::endl; }

（示例源自 c04-follow-location.md）

开启之后，客户端会读取 3xx 响应中的Location头，解析出目标 URL，然后自动以新的 URL 重新发起请求，直到拿到非 3xx 的最终响应为止。最终响应的内容（状态码、正文、头信息）会落入你调用的res对象，中间经过了多少次跳转对你透明无感。

值得注意的一点是：库为Response结构保留了location字段（见 httplib.h），最终响应中会记录最后一次跳转的Location值，方便你判断实际落到哪个地址。例如仓库测试YahooRedirectTest中断言开启跟随后请求yahoo.com最终得到200 OK，且res->location为https://www.yahoo.com/（见 test/test.cc）——这正是 HTTP→HTTPS 跳转的典型场景。

重定向链的类型覆盖

通过Location头的不同形态，自动跟随可以应对多种跳转写法：

• 绝对 URL：Location: https://another.example.com/new/path，直接跳到新主机；
• 相对路径：Location: /new/path，沿用当前主机与端口；
• 带查询串的相对地址：Location: new/path?page=2。

从实现上看，ClientImpl::redirect()会先把Location与当前请求路径合并解析（调用detail::resolve_relative_location），再拆解出 scheme、host、port、path、query 等组件（见 httplib.h）。仓库的在线测试分别覆盖了绝对路径跳转（/absolute-redirect/3）、普通跳转（/redirect/3）与相对路径跳转（/relative-redirect/3）三类用例，均断言最终得到200 OK（见 test/test.cc）。

302 与 303 的语义差异：POST 会被改写成 GET

detail::redirect()这个底层辅助函数（见 httplib.h）在重建请求时遵循了 HTTP 规范对 303 的处理约定：

if (res.status == StatusCode::SeeOther_303 && (req.method != "GET" && req.method != "HEAD")) { new_req.method = "GET"; new_req.body.clear(); new_req.headers.clear(); }

也就是说，当收到303 See Other且原始请求方法不是GET/HEAD（例如 POST）时，重定向请求会被强制改写为GET，并清空请求体与相关头部——这符合浏览器对 303 的标准行为（"看其他地方，改用 GET 获取结果"）。而 302/307/308 等其余状态码则保留原始方法与请求体，按原样重放。

HTTP → HTTPS 重定向：需要 TLS 后端支持

很多站点会把 HTTP 流量统一重定向到 HTTPS。开启set_follow_location(true)之后，这种scheme 或 host 变化的跨主机跳转同样会被透明处理：

httplib::Client cli("http://example.com"); cli.set_follow_location(true); auto res = cli.Get("/"); // 内部自动完成：http://example.com/ → https://example.com/

Warning：要跟随指向 HTTPS 的重定向，你必须使用带有 OpenSSL（或其他 TLS 后端，如 Mbed TLS 等）编译的 cpp-httplib。在没有 TLS 支持的情况下，跳转到 HTTPS 的重定向会直接失败。

这背后的实现非常直观：当目标 scheme 变为https时，ClientImpl::redirect()会进入create_redirect_client()分支，#ifdef CPPHTTPLIB_SSL_ENABLED保护了这条路径——编译时未启用 TLS 会设置Error::SSLConnection错误并返回失败（见 httplib.h）。而启用 TLS 后，库会新建一个SSLClient，并把原客户端的关键配置（超时、keep-alive、压缩选项、代理设置、CA 证书、证书校验开关等）迁移过去，随后继续处理后续的重定向链（见 httplib.h）。

仓库测试HttpsToHttpRedirectTest系列正是用SSLClient验证了 HTTPS 服务跳转到 HTTP 地址的场景同样可以自动跟随并返回200 OK（见 test/test.cc）。

跨主机跳转的安全策略：凭据与 Cookie 不会被转发

自动跟随重定向并非无脑转发所有请求头。当重定向目标是不同主机时，出于安全考虑（遵循 RFC 9110 对凭据处理的要求），create_redirect_client()会主动剔除以下头部（见 httplib.h）：

• Host（新请求必须按目标主机重新生成）
• Authorization（Basic / Bearer 等认证凭据）
• Proxy-Authorization
• Cookie/Cookie2

同时在setup_redirect_client()中明确注明：Basic 认证、Bearer Token、Digest 认证等凭据不会复制到跨主机重定向的客户端上（见 httplib.h）。这可以有效防止你的登录凭据被泄露给恶意或不可信的第三方主机。

仓库为此专门编写了TestDoNotForwardCredentialsOnRedirect测试：服务端捕获目标路径收到的Authorization头，断言跨主机跳转后该头为空（见 test/test.cc），对 Basic Auth、Bearer Token、Cookie 三种场景分别做了验证。作为对照，同源（同 scheme、同 host、同 port）重定向会走原客户端直接重发，不会删除这些头部，因此同源场景下的 Cookie 可以被保留。

重定向次数上限与超时控制

最大重定向次数（默认 20）

为了防止"重定向环"或恶意无限跳转拖垮客户端，库对同一请求允许的重定向次数有硬上限：

#ifndef CPPHTTPLIB_REDIRECT_MAX_COUNT #define CPPHTTPLIB_REDIRECT_MAX_COUNT 20

（见 httplib.h）

该宏默认值是20，可以在编译时通过自定义宏覆盖。每次重建请求时，redirect_count_都会减一（见 httplib.h）；当计数归零时，ClientImpl::redirect()会返回Error::ExceedRedirectCount错误（见 httplib.h），该错误的字符串描述为 "Maximum redirect count exceeded"（见 httplib.h）。

仓库测试TooManyRedirectTest专门构造了/redirect/21（21 次跳转 > 20 次上限）来验证：开启跟随后请求失败，res.error()恰好是Error::ExceedRedirectCount（见 test/test.cc）。在编写业务代码时，务必检查res->error()，因为跟随重定向的请求并不总是返回 200。

跟随重定向会累加请求时间

Note：跟随重定向会叠加总请求时间——每跳一次就是一次完整的网络往返。如果你的客户端设置了严格的读写超时，且跳转链很长，很可能在某一跳上超时失败。超时的配置方式请参考 Cookbook 的 C12. Set timeouts。

从实现上看，每次重定向都会调用cli.send(new_req, new_res, error)重新走一遍完整的连接与收发流程（见 httplib.h）。如果目标主机切换，还会额外经历一次新建SSLClient/ClientImpl的开销（见 httplib.h）。好在setup_redirect_client()会把原客户端的connection_timeout、read_timeout、write_timeout一并复制到新客户端（见 httplib.h），保证跨主机跳转时的超时策略与原始配置一致。对于可能经历多跳的场景，建议预留比单次请求更充裕的超时时间。

服务端如何发起重定向：Response::set_redirect

理解了客户端行为之后，再看服务端一侧：cpp-httplib 的Response提供set_redirect(url, status)便捷方法用于发出重定向响应，默认状态码为302 Found（见 httplib.h 与 httplib.h）。在服务端路由里可以这样写：

httplib::Server svr; svr.Get("/old", [](const httplib::Request &, httplib::Response &res) { res.set_redirect("/new"); // 默认 302 }); svr.Get("/moved", [](const httplib::Request &, httplib::Response &res) { res.set_redirect("https://example.com/final", // 指定状态码 httplib::StatusCode::MovedPermanently_301); });

它内部为响应设置Location头与对应的 3xx 状态码。仓库测试中也大量使用res.set_redirect(...)来构造重定向服务器，例如把请求转到另一个端口上的服务（见 test/test.cc）、同源跳转保留 Cookie（见 test/test.cc）等场景。客户端与服务端两侧配合使用，即可在开发环境中完整验证自动跟随重定向的行为。

总结与最佳实践

把官方 Cookbook 文档与仓库源码、测试对应起来，可以归纳出以下实践要点：

1. 默认不跟随 3xx：httplib::Client收到302就返回302，需要自动跟随请显式调用cli.set_follow_location(true)；
2. 最终结果落在原响应变量：跟随过程对调用方透明，中间跳转次数不感知，最终的非 3xx 响应即res指向的内容；
3. HTTP→HTTPS 跳转依赖 TLS 编译支持：未启用 OpenSSL/Mbed TLS 等后端时，跳往 HTTPS 的重定向会以Error::SSLConnection失败；
4. 跨主机跳转不转发凭据与 Cookie：Authorization、Cookie等敏感头会被剔除，同源跳转则保留，符合 RFC 9110 的安全要求；
5. 重定向次数上限 20：可用编译宏CPPHTTPLIB_REDIRECT_MAX_COUNT调整，超出后返回Error::ExceedRedirectCount，务必检查res->error()；
6. 注意累积耗时：多跳重定向会叠加网络往返时间，超时配置请参照 C12. Set timeouts 的相关说明。

源码与测试的对应位置为：客户端实现 httplib.h、底层重定向辅助函数 httplib.h、重定向测试用例 test/test.cc 与 test/test.cc。读者可以基于这些位置进一步阅读，深入理解 cpp-httplib 重定向机制的每一个细节。

• 后端
• 网络