brpc HTTP 客户端完全指南：从 Channel 初始化到流式下载与 HTTPS 实战

brpc HTTP 客户端完全指南从 Channel 初始化到流式下载与 HTTPS 实战【免费下载链接】brpcbrpc is an Industrial-grade RPC framework using C Language, which is often used in high performance system such as Search, Storage, Machine learning, Advertisement, Recommendation etc. brpc means better RPC.项目地址: https://gitcode.com/GitHub_Trending/brpc/brpcbrpc 内置了一套与 protobuf 协议完全解耦的 HTTP/HTTP2 客户端实现只需把ChannelOptions.protocol设为PROTOCOL_HTTP或PROTOCOL_H2即可用一套统一的 RPC 框架访问任意 HTTP 服务网页、内置服务、pb 服务均可。本文以 docs/en/http_client.md 为主干结合仓库中的 http_c 示例 与 http_rpc_protocol.cpp 等源码系统讲解请求构造、URL 与 Host 头规则、压缩、错误码、渐进式下载与 HTTPS 的完整用法读者学完即可在业务代码中直接落地使用。关于 h2brpc 将 HTTP/2 协议统称为 h2无论是否加密。区别只体现在/connections页面的连接展示上未加密的 HTTP/2 连接显示为官方名称 h2c加密连接显示为 h2。http 与 h2 在 brpc 中的 API 基本一致本文中提到的所有 http 特性除特别说明外同样适用于 h2。也就是说掌握一套 API 即可同时驾驭 HTTP/1.x 与 HTTP/2。创建 Channel要使用brpc::Channel访问 http/h2 服务必须把ChannelOptions.protocol设置为PROTOCOL_HTTP或PROTOCOL_H2brpc::ChannelOptions options; options.protocol brpc::PROTOCOL_HTTP; // 或 brpc::PROTOCOL_H2 if (channel.Init(www.baidu.com /*any url*/, options) ! 0) { LOG(ERROR) Fail to initialize channel; return -1; }协议一旦设置Channel::Init的第一个参数就可以是任意合法 URL。注意Init()只使用 URL 中的 host 和 port其余部分会被丢弃——允许传完整 URL 只是省去用户自己解析 host/port 的代码。http/h2 Channel 同样支持 BNS 地址或其他命名服务NamingService详见 client.md 与 load_balancing.md。从 http_client.cpp 的完整示例可以看到生产环境中通常还会同时配置超时与重试brpc::ChannelOptions options; options.protocol FLAGS_protocol; // 默认 http可用 -protocol 切换 options.timeout_ms FLAGS_timeout_ms; // RPC 超时毫秒示例默认 2000 options.max_retry FLAGS_max_retry; // 最大重试次数不含首次示例默认 3 if (channel.Init(url, FLAGS_load_balancer.c_str(), options) ! 0) { LOG(ERROR) Fail to initialize channel; return -1; }GET 请求http/h2 与 protobuf 关系不大因此CallMethod除Controller和done外的参数全部传nullptr。done传非空即为异步 RPCbrpc::Controller cntl; cntl.http_request().uri() www.baidu.com/index.html; // 请求 URL channel.CallMethod(nullptr, cntl, nullptr, nullptr, nullptr/*done*/);cntl.response_attachment()是 http/h2 响应的 body类型为butil::IOBuf。IOBuf可通过to_string()转成std::string但该操作会分配内存并拷贝全部数据。如果性能敏感代码应当尽量直接消费IOBuf而不是强求连续内存——IOBuf本身就是零拷贝、链式缓冲区的设计参见 iobuf.md 与 iobuf.h。POST 请求默认的 HTTP 方法是 GET可通过set_method改为 POST 或其他方法。brpc 在 http_method.h 中定义了完整的HttpMethod枚举覆盖DELETE/GET/HEAD/POST/PUT/CONNECT/OPTIONS/TRACE以及 WebDAV 扩展方法如COPY/LOCK/MKCOL/MOVE/PROPFIND/PATCH/PURGE等并提供了HttpMethod2Str/Str2HttpMethod两个转换函数。POST 的数据放入request_attachment()它同样是butil::IOBuf可直接append字符串或char*brpc::Controller cntl; cntl.http_request().uri() ...; // 请求 URL cntl.http_request().set_method(brpc::HTTP_METHOD_POST); cntl.request_attachment().append({\message\:\hello world!\}); channel.CallMethod(nullptr, cntl, nullptr, nullptr, nullptr/*done*/);如果 body 需要大量格式化拼接建议使用butil::IOBufBuilder。它的接口与std::ostringstream一致当需要打印大量对象时通常比 C 风格 printf 更简洁、更高效brpc::Controller cntl; cntl.http_request().uri() ...; // 请求 URL cntl.http_request().set_method(brpc::HTTP_METHOD_POST); butil::IOBufBuilder os; os A lot of printing printable_objects ...; os.move_to(cntl.request_attachment()); channel.CallMethod(nullptr, cntl, nullptr, nullptr, nullptr/*done*/);示例程序 http_client.cpp 提供了-d参数非空时自动切换为 POST 并写入 body可直接用于验证./http_client http://www.foo.com:8765/EchoService/Echo -d {message:hello}修改 HTTP 版本brpc 客户端默认以 http/1.1 行为工作。相比 http/1.1http/1.0 缺少长连接KeepAlive。要与某些老旧 http 服务器通信时可把客户端配置为 http/1.0cntl.http_request().set_version(1, 0);需要注意设置 http 版本对 h2 无效客户端收到的 h2 响应、服务端收到的 h2 请求其版本均固定为 (2, 0)。brpc 服务端会自动识别 http 版本并作出相应响应无需用户干预。URL 解析URL 的通用形式RFC 3986 风格如下// foo://username:passwordexample.com:8042/over/there/index.dtb?typeanimalnamenarwhal#nose // \_/ \_______________/ \_________/ \__/ \___/ \_/ \______________________/ \__/ // | | | | | | | | // | userinfo host port | | query fragment // | \________________________________/\_____________|____|/ \__/ \__/ // scheme | | | | | | // authority | | | | | // path | | interpretable as keys // | | // \_______________________________________________|____|/ \____/ \_____/ // | | | | | // hierarchical part | | interpretable as values // | | // interpretable as filename | // | // interpretable as extension如前面示例所示Channel.Init()和cntl.http_request().uri()都需要 URL。那为什么设置过Init()之后还要再设置一次uri()在简单场景下确实重复了但在更复杂的场景下两者职责不同访问命名服务下的多台服务器例如 BNSChannel::Init接收对命名服务有意义的名称如 BNS 中的节点名而uri()赋值为完整 URL通过 http/h2 代理访问服务器Channel::Init接收代理服务器的地址uri()仍然赋值为目标 URL。Host 头规则框架对Host头的处理分四种情况该头在 h2 中名为:authority用户已设置Host头大小写不敏感框架不做任何改动用户未设置且 URL 含 host如http://www.foo.com/path请求携带Host: www.foo.com用户未设置URL 无 host如/index.html?namevalue但 Channel 用含有效域名的 http(s) 地址初始化Host头取目标服务器的域名——若地址是http://www.foo.com服务器看到Host: www.foo.com若地址是http://www.foo.com:8989则看到Host: www.foo.com:8989用户未设置URL 无 host且 Channel 初始化的地址也不含域名Host头取目标服务器的 IP 和端口——10.46.188.39:8989 的服务器会看到Host: 10.46.188.39:8989。常用操作速查以 http 请求为例响应侧用法对称常用操作如下读取名为Foo的 HTTP 头不存在时返回nullptrconst std::string* value cntl-http_request().GetHeader(Foo);设置名为Foo的 HTTP 头cntl-http_request().SetHeader(Foo, value);读取名为Foo的 queryconst std::string* value cntl-http_request().uri().GetQuery(Foo);设置名为Foo的 querycntl-http_request().uri().SetQuery(Foo, value);设置 HTTP 方法cntl-http_request().set_method(brpc::HTTP_METHOD_POST);设置 URLcntl-http_request().uri() http://www.baidu.com;设置content-typecntl-http_request().set_content_type(text/plain);读取 HTTP bodybutil::IOBuf buf cntl-request_attachment(); std::string str cntl-request_attachment().to_string(); // 触发底层拷贝写入 HTTP bodycntl-request_attachment().append(....); butil::IOBufBuilder os; os ....; os.move_to(cntl-request_attachment());在服务端侧http_server.cpp 展示了如何使用URI::QueryBegin()/QueryEnd()遍历所有 query 参数并以IOBufBuilder构造响应 body可与客户端侧用法对照学习。关于 HTTP 头的几点注意头字段名按 RFC 2616 第 4.2 节是大小写不敏感的。brpc 支持大小写不敏感的头字段名同时打印时会保留用户设置的原始大小写若多个头具有相同字段名按 RFC 2616 规定值应以逗号,合并具体如何消费这类值由用户自行处理query 之间以分隔key/value 之间以分隔值可以省略。例如key1value1key2key3value3是合法 query 串其中key2的值为空字符串。调试 HTTP 消息打开 GFlag-http_verbose框架会打印每个 http 请求与响应方便排查报文内容。该 flag 在 http_message.cpp 中定义同时还有配套的-http_verbose_max_body_length默认 512 字节控制打印 body 的最大长度超出部分会被截断显示。注意该 flag 只应用于测试或调试切勿用于线上服务——它会在日志中输出完整的请求/响应数据。其他相关 flag 见 flags.md。HTTP 错误处理当服务器返回非 2xx 状态码时HTTP RPC 视为失败客户端cntl-ErrorCode()被置为EHTTP错误码 1010见 errno.proto注册描述为 Bad http call见 controller.cpp。此时可通过cntl-http_response().status_code()获取更具体的 HTTP 状态码服务器还可以把描述错误的 html 或 json 写入cntl-response_attachment()作为 http body 返回给客户端。从源码看服务端处理非 2xx 时会统一把 RPC 错误码置为EHTTPhttp_rpc_protocol.cpp。如果客户端希望拿到 brpc 服务器返回的真实错误码而非统一收敛后的EHTTP需要设置 GFlag-use_http_error_codetrue——该 flag 同时会把 brpc 错误码写入响应头x-bd-error-code定义见 http_rpc_protocol.cpp。此外 retry_policy.h 展示了基于EHTTP定制重试策略的入口需要精细控制 http 重试行为时可参考。压缩请求 BodyController::set_request_compress_type(brpc::COMPRESS_TYPE_GZIP)会让框架尝试对 HTTP body 做 gzip 压缩。之所以说尝试是因为压缩可能不会发生当 body 小于-http_body_compress_threshold默认 512 字节时不会压缩。原因在于 gzip 并非很快的压缩算法body 很小时压缩带来的延迟可能比省下的传输时间还要大。该阈值的定义见 http_rpc_protocol.cpp实际压缩判定发生在请求发送路径上同文件第 665 行附近。解压响应 Body出于通用性考虑brpc不会自动解压响应 body。解压代码并不复杂用户可自行完成#include brpc/policy/gzip_compress.h ... const std::string* encoding cntl-http_response().GetHeader(Content-Encoding); if (encoding ! nullptr *encoding gzip) { butil::IOBuf uncompressed; if (!brpc::policy::GzipDecompress(cntl-response_attachment(), uncompressed)) { LOG(ERROR) Fail to un-gzip response body; return; } cntl-response_attachment().swap(uncompressed); } // Now cntl-response_attachment() contains the decompressed dataGzipDecompress(const butil::IOBuf, butil::IOBuf*)的声明见 gzip_compress.h同一头文件还提供了GzipCompress、ZlibCompress、ZlibDecompress等对称接口可满足不同的压缩/解压需求。渐进式下载Progressive Download普通 http 客户端要等 http body全部下载完成RPC 才算结束期间 body 一直驻留内存。如果 body 非常大甚至无限大例如直播用的 FLV 文件内存会持续增长直到 RPC 超时因此这类客户端不适合下载超大文件。brpc 客户端支持在读完 body 之前结束 RPC让用户随后逐步读取 http body。需要澄清的是这个特性不等于支持 http chunked 模式——brpc 的 http 实现从一开始就支持 chunked 传输这里要解决的是如何让用户处理超大或无限大的 http body这一更本质的问题与是否 chunked 无关。使用分三步第 1 步实现ProgressiveReader#include brpc/progressive_reader.h ... class ProgressiveReader { public: // 每读到一块数据时被调用。 // 返回错误会被视为*永久性*错误读取该数据的 socket 将被关闭。 // 临时性错误可通过阻塞本函数来处理但阻塞可能阻塞该 socket 上的 HTTP 解析。 virtual butil::Status OnReadOnePart(const void* data, size_t length) 0; // 没有更多数据可读时被调用。status 是该方法被调用的原因提示 // - status.ok(): 消息完整且被成功消费。 // - 其他: socket 损坏或 OnReadOnePart() 失败。 // 本方法只会被调用一次且仅一次之后不再有其他方法被调用用户可在其中释放对象内存。 virtual void OnEndOfMessage(const butil::Status status) 0; };OnReadOnePart在每次读到一块数据时被调用OnEndOfMessage在数据读完或连接断开时被调用。实现前请仔细阅读注释。接口的完整定义与协议层调用链说明见 progressive_reader.h其中ReadableProgressiveAttachment描述了从协议解析、RPC 结束到OnReadOnePart回调的完整数据流。第 2 步RPC 前声明渐进读取cntl.response_will_be_read_progressively();这会让 brpc 在读完全部 headers 后即结束 RPC。第 3 步RPC 后挂载读取器cntl.ReadProgressiveAttachmentBy(new MyProgressiveReader);MyProgressiveReader是用户实现的ProgressiveReader实例用户可在OnEndOfMessage内删除该对象。示例程序 http_client.cpp 中PartDataReader实现了上述接口OnReadOnePart逐块打印数据OnEndOfMessage通过CountdownEvent通知主线程并delete this配合-progressive与-progressive_read_timeout_ms渐进读取空闲超时示例默认 5000ms两个 flag 即可运行验证。服务端侧可用 http_server.cpp 中通过CreateProgressiveAttachment()Write()分片发送大文件的FileService配合测试。渐进式上传当前限制目前 POST 数据在发起 http 调用前必须是完整的因此 brpc http 客户端仍不适合上传超大 body。如果业务有超大上传需求需要等待该能力完善或在客户端自行做分片上传等处理。带认证访问服务器根据服务器的认证方式生成auth_data写入Authorization头即可cntl.http_request().SetHeader(Authorization, auth_data);若使用 curl 验证等价做法是加参数-H Authorization : auth_data。发送 HTTPS 请求https 是 http over SSL 的简称。SSL 并非 http 专属而是对所有协议通用客户端开启 SSL 的通用方法见 client.mdTurn on SSL 一节核心是设置ChannelOptions.mutable_ssl_options()可配置ciphers_name、sni_name、alpn_protocols等参数。brpc 为方便使用做了额外增强对于以https://开头的 URI 会自动启用 SSL无需手动设置ssl_options。同时Channel.Init也能识别https://前缀并自动开启 SSL开启 SSL 后-http_verbose还会打印证书信息。示例 http_server.cpp 展示了服务端通过ServerOptions.mutable_ssl_options()配置证书certificate/private_key/ciphers的对称做法仓库的 example/http_c 目录下自带cert.pem与key.pem可用于本地联调。小结通过本文可以看到brpc 的 http/h2 客户端在设计上追求少即是多协议只是ChannelOptions中的一个选项请求/响应统一建模为Controller上的 URL、Header、Query 与IOBuf附件CallMethod的参数在 http 场景下几乎全部留空。而在能力上它并不简陋——支持 h2、多命名服务、渐进式下载、gzip 压缩、SSL 自动识别与完整的错误码体系。上手时可从 example/http_c 示例目录出发对照 http_service.md 理解服务端写法再结合 client.md 与 iobuf.md 深入底层机制。【免费下载链接】brpcbrpc is an Industrial-grade RPC framework using C Language, which is often used in high performance system such as Search, Storage, Machine learning, Advertisement, Recommendation etc. brpc means better RPC.项目地址: https://gitcode.com/GitHub_Trending/brpc/brpc创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考