Webcc 是我基于 Boost Asio 开发的轻量级 C++ HTTP 程序库,同时支持客户端与服务端。
几年前,它只支持简单的 SOAP 调用(名字叫 cSoap),结果慢慢演化成了一个纯粹的 HTTP 程序库,目前有 250 多次代码提交,还在不断完善,且应用在了我们公司的产品中,击败了 Qt 的 QtHttpServer。几乎是 C++ 最好用最完善的 HTTP 程序库了。
编译指南,目前只有英文版。
代码仓库: https://github.com/sprinfall/webcc。请认准链接,其他人 fork 的仓库,都不是最新的。
功能概述
- 跨平台: Windows,Linux 及 MacOS
- 简单好用的客户端 API,借鉴了 Python 的 requests 程序库
- 支持 SSL/HTTPS,依赖 OpenSSL(可选)
- 支持 GZip 压缩,依赖 Zlib(可选)
- 持久连接 (Keep-Alive)
-
数据串流 (Streaming)
- 客户端:可以上传、下载大型文件
- 服务端:可以伺服、接收大型文件
- 支持 Basic & Token 认证/授权
- 超时控制(目前仅客户端)
- 代码遵守 Google C++ Style
- 自动化测试和单元测试保证质量
- 无内存泄漏(VLD 检测)
客户端 API
先来看一个完整的例子:
#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;
}
如你所见,这里通过一个辅助类 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 和访问 HTTP 没有差别,对用户是透明的:
session.Send(webcc::RequestBuilder{}.Get("https://httpbin.org/get")());
注意:对 HTTPS/SSL 的支持,需要启用编译选项 WEBCC_ENABLE_SSL
,也会依赖 OpenSSL。
列出 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++ 没有“键值参数”的问题,它提供了很多函数供你定制请求的样子。
为了列出一个授权的 (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) // 应该替换成具体合法的 token
());
尽管 持久连接 (Keep-Alive) 这个功能不错,你也可以手动关掉它:
auto r = session.Send(webcc::RequestBuilder{}.
Get("http://httpbin.org/get").
KeepAlive(false) // 不要 Keep-Alive
());
其他 HTTP 请求的 API 跟 GET 并无太多差别。
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()
());
Webcc 可以把大型的响应数据串流到临时文件,串流在下载文件时特别有用。
auto r = session.Send(webcc::RequestBuilder{}.
Get("http://httpbin.org/image/jpeg")
(), true); // stream = 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
的分块数据形式。
更多示例和用法,请参考 examples 目录。
服务端 API
Hello, World!
下面是个 Hello, World!
级别的服务程序。
程序运行后,打开浏览器,输入 http://localhost:8080
,页面显示 Hello, World!
。
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(8080);
server.Route("/", std::make_shared<HelloView>());
server.Run();
} catch (const std::exception&) {
return 1;
}
return 0;
}
简单解释一下。一个服务器 (server) 对应多个视图 (view),不同的视图对应不同的资源,视图通过 URL 路由,且 URL 可以为正则表达式。
完整代码请见 examples/hello_world_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(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/rest_book_server.cc。
**粗体** _斜体_ [链接](http://example.com) `代码` - 列表 > 引用
。你还可以使用@
来通知其他用户。