README_zh_CN.md

#include <iostream>
#include "webcc/client_session.h"
#include "webcc/logger.h"
int main() {
  // 首先配置日志输出（到控制台/命令行）
  WEBCC_LOG_INIT("", webcc::LOG_CONSOLE);
  // 创建会话
  webcc::ClientSession session;
  try {
    // 发起一个 HTTP GET 请求
    auto r =
        session.Send(webcc::RequestBuilder{}.Get("http://httpbin.org/get")());
    // 输出响应数据
    std::cout << r->data() << std::endl;
  } catch (const webcc::Error& error) {
    // 异常处理
    std::cerr << error << std::endl;
  return 0;
Request Builder





    

如你所见，这里通过一个辅助类 RequestBuilder，串联起各种参数，最后再生成一个请求对象。注意不要漏了最后的 () 操作符。
通过 Query() 可以方便地指定 URL 查询参数：
session.Send(webcc::RequestBuilder{}
                 .Get("http://httpbin.org/get")
                 .Query("key1", "value1")
                 .Query("key2", "value2")());
要添加额外的头部也很简单：
session.Send(webcc::RequestBuilder{}
                 .Get("http://httpbin.org/get")
                 .Header("Accept", "application/json")());
HTTPS

访问 HTTPS 和访问 HTTP 没有差别，对用户是透明的：
session.Send(webcc::RequestBuilder{}.Get("https://httpbin.org/get")());
注意：对 HTTPS/SSL 的支持，需要启用编译选项 WEBCC_ENABLE_SSL，也会依赖 OpenSSL。
调用 GitHub REST API

列出 GitHub 公开事件 (public events) 也不是什么难题：
auto r = session.Send(
    webcc::RequestBuilder{}.Get("https://api.github.com/events")());
然后，你可以把 r->data() 解析成 JSON 对象，随便用个什么 JSON 程序库。
我在示例程序里用的是 jsoncpp，但是 Webcc 本身并不理解 JSON，用什么 JSON 程序库，完全是你自己的选择。
RequestBuilder 本质上是为了解决 C++ 没有“键值参数”的问题，它提供了很多函数供你定制请求的样子。
Authorization

为了列出一个授权的 (authorized) GitHub 用户的“粉丝” (followers)，要么使用 Basic 认证：
session.Send(webcc::RequestBuilder{}
                 .Get("https://api.github.com/user/followers")
                 .AuthBasic(login, password)());
要么使用 Token 认证：
session.Send(webcc::RequestBuilder{}
                 .Get("https://api.github.com/user/followers")
                 .AuthToken(token)());
Keep-Alive

尽管 持久连接 (Keep-Alive) 这个功能不错，你也可以手动关掉它：
// No Keep-Alive
auto r = session.Send(
    webcc::RequestBuilder{}.Get("http://httpbin.org/get").KeepAlive(false)());
其他 HTTP 请求的 API 跟 GET 并无太多差别。
POST 请求

POST 请求需要一个“体” (body)，就 REST API 来说通常是一个 JSON 字符串。让我们 POST 一个 UTF-8 编码的 JSON 字符串：
session.Send(webcc::RequestBuilder{}
                 .Post("http://httpbin.org/post")
                 .Body("{'name'='Adam', 'age'=20}")
                 .Json()
                 .Utf8()());
除了 JSON 字符串，POST 请求的体可以为任何内容。它可以是一个文件的二进制内容，见：上传文件。它也可以是一个 URL 编码的字符串：
session.SetContentType("application/x-www-form-urlencoded", "utf8");
// 使用 UrlQuery 来组装 URL 编码字符串。
// 不要使用 RequestBuilder::Query()，那是专门给 GET 请求用的。
webcc::UrlQuery query;
query.Add("key1", "value1");
query.Add("key2", "value2");
// ...
auto r = session.Send(webcc::RequestBuilder{}
                          .Post("http://httpbin.org/post")
                          .Body(query.ToString())());
更多细节请参见：examples/form_urlencoded_client.cc。
Webcc 可以把大型的响应数据串流到临时文件，串流在下载文件时特别有用。
// stream = true
auto r = session.Send(
    webcc::RequestBuilder{}.Get("http://httpbin.org/image/jpeg")(), true);
// 把串流的文件移到目标位置
r->file_body()->Move("./wolf.jpeg");
不光下载，上传也可以串流：
auto r = session.Send(
    webcc::RequestBuilder{}.Post("http://httpbin.org/post").File(path)());
这个文件在 POST 时，不会一次加载到内存，而是读一块数据发一块数据，直到发送完。
注意，Content-Length 头部还是会设置为文件的真实大小，不同于 Transfer-Encoding: chunked 的分块数据形式。
多线程调用

一个 ClientSession 对象通常只能给一个线程用来发送请求，其 Send() 函数不可以在多个线程间并行调用。
但是，它的几个状态切换的函数，Start()，Stop() 和 Cancel()，是线程安全的，比如，Send() 在线程 A 里调用，Stop() 可以在线程 B 里调用。具体可参考 examples/heartbeat_client。
多线程调用示例:
void ThreadedClient() {
  std::vector<std::thread> threads;
  for (int i = 0; i < 3; ++i) {
    threads.emplace_back([]() {
      webcc::ClientSession session;
      try {
        auto r = session.Send(
            webcc::RequestBuilder{}.Get("http://httpbin.org/get")());
        std::cout << r->data() << std::endl;
      } catch (const webcc::Error&) {
  for (auto& t : threads) {
    t.join();
服务端 API





    

一个最小的服务器

下面是个 Hello, World! 级别的服务程序。
程序运行后，打开浏览器，输入 http://localhost:8080，页面显示 Hello, World!。
#include "webcc/logger.h"
#include "webcc/response_builder.h"
#include "webcc/server.h"
class HelloView : public webcc::View {
public:
  webcc::ResponsePtr Handle(webcc::RequestPtr request) override {
    if (request->method() == "GET") {
      return webcc::ResponseBuilder{}.OK().Body("Hello, World!")();
    return {};
int main() {
  try {
    webcc::Server server{ boost::asio::ip::tcp::v4(), 8080 };
    server.Route("/", std::make_shared<HelloView>());
    server.Run();
  } catch (const std::exception&) {
    return 1;
  return 0;
URL 路由

通过 Route() 方法，不同的 URLs 被路由到不同的视图。
你也可以路由不同的 URLs 到同一个视图：
server.Route("/", std::make_shared<HelloView>());
server.Route("/hello", std::make_shared<HelloView>());
甚至路由到同一个视图对象：
auto view = std::make_shared<HelloView>();
server.Route("/", view);
server.Route("/hello", view);
但是一般情况下，一个视图只处理一种特定的 URL（请参考 Book Server 示例）。
URL 可以是正则表达式。Book Server 示例用了一个正则表达式的 URL 来匹配书本的 ID。
最后，强烈建议你总是显式地指定一个路由所允许的 HTTP 方法：
server.Route("/", std::make_shared<HelloView>(), { "GET" });
运行服务器

关于服务器的最后一件事就是 Run()：
void Run(std::size_t workers = 1, std::size_t loops = 1);
工作者 (workers) 代表那些会被唤醒去处理 HTTP 请求的线程。理论上，工作者越多，并发能力越强。实际操作时，你得考虑你有多少个可用的 CPU 内核，然后为它分配一个合理的数目。
第二个参数 (loops) 代表运行 Asio 上下文 (IO Context) 的线程个数。一般来说，一个线程就足够了，但是也可以为多个。
Response Builder

服务端 API 提供了一个辅助类 ResponseBuilder，方便视图串联起各种参数，最后再生成一个响应对象。和 RequestBuilder 完全是同一种策略。
REST Book Server

假定你想创建一个关于书的服务，提供下面这些 REST API：
添加一本新书
获取一本书的详情
更新一本书的信息
删除一本书
这是一组典型的 CRUD 操作。
前两个操作通过 BookListView 实现：
ListView，DetailView 的命名方式，参考了 Django REST Framework。ListView 针对一列资源，DetailView 针对单个资源。
class BookListView : public webcc::View {
public:
  webcc::ResponsePtr Handle(webcc::RequestPtr request) override {
    if (request->method() == "GET") {
      return Get(request);
    if (request->method() == "POST") {
      return Post(request);
    return {};
private:
  // 查询书
  webcc::ResponsePtr Get(webcc::RequestPtr request);
  // 添加一本新书
  webcc::ResponsePtr Post(webcc::RequestPtr request);
其他操作通过 BookDetailView 实现：
class BookDetailView : public webcc::View {
public:
  webcc::ResponsePtr Handle(webcc::RequestPtr request) override {
    if (request->method() == "GET") {
      return Get(request);
    if (request->method() == "PUT") {
      return Put(request);
    if (request->method() == "DELETE") {
      return Delete(request);
    return {};
protected:
  // 获取一本书的详情
  webcc::ResponsePtr Get(webcc::RequestPtr request);
  // 更新一本书的信息
  webcc::ResponsePtr Put(webcc::RequestPtr request);
  // 删除一本书
  webcc::ResponsePtr Delete(webcc::RequestPtr request);
我们挑一个函数出来看一下吧：
webcc::ResponsePtr BookDetailView::Get(webcc::RequestPtr request) {
  if (request->args().size() != 1) {
    // NotFound (404) 意味着 URL 所指定的资源没有找到。
    // 这里用 BadRequest (400) 应该也是合理的。
    // 不过，后面可以看到，这个视图匹配了 "/books/(\\d+)" 这个 URL，参数肯定不会有问题的。
    // 所以这里的错误处理，只是出于防范，和编程的严谨。
    // Webcc 没有对 URL 参数做强类型的处理，那么代码写起来太复杂了。
    return webcc::ResponseBuilder{}.NotFound()();
  const std::string& book_id = request->args()[0];
  // 通过 ID 找到这本书，比如，从数据库里。
  // ...
  if (<没找到>) {
    return webcc::ResponseBuilder{}.NotFound()();
  // 把这本书转换成 JSON 字符串，并设为响应数据。
  return webcc::ResponseBuilder{}.OK().Data(<JsonStringOfTheBook>).
      Json().Utf8()();
最后一步，把 URLs 路由到特定的视图，然后开始运行：
int main(int argc, char* argv[]) {
  // ...
  try {
    webcc::Server server{ boost::asio::ip::tcp::v4(), 8080 };
    server.Route("/books",
                 std::make_shared<BookListView>(),
                 { "GET", "POST" });
    // ID 通过正则表达式匹配出来
    server.Route(webcc::R("/books/(\\d+)"),
                 std::make_shared<BookDetailView>(),
                 { "GET", "PUT", "DELETE" });
    // 开始运行（注意：阻塞调用）
    server.Run();
  } catch (const std::exception& e) {
    std::cerr << e.what() << std::endl;
    return 1;
  return 0;
完整实现请见 examples/book_server。
IPv6 支持

IPv6 服务端

只需把 Server 的 protocol 参数改成 boost::asio::ip::tcp::v6()：
webcc::Server server{ boost::asio::ip::tcp::v6(), 8080 };
IPv6 客户端

只需指定一个 IPv6 地址：
session.Send(webcc::RequestBuilder{}.Get("http://[::1]:8080/books")());

README_zh_CN.md

Latest commit

History

README_zh_CN.md

File metadata and controls

Webcc - C++ HTTP 程序库

客户端 API

一个完整的例子

Request Builder

HTTPS

调用 GitHub REST API

Authorization

Keep-Alive

POST 请求

多线程调用

服务端 API

一个最小的服务器

URL 路由

运行服务器

Response Builder

REST Book Server

IPv6 支持

IPv6 服务端

IPv6 客户端