Oat++框架C/C++编码入门:DTO传输与Restful服务开发
一、Oat++框架介绍
Oat++是C++服务器开发领域热门的轻量级、高性能、零依赖的C++ Web服务端开发框架,它是专为构建可扩展的Web服务、RESTful API和高并发应用而设计的。Oat++项目设计初衷非常明确,不替代Nginx做纯静态站点,而是作为C++原生的REST微服务框架。
Oat++特别适合嵌入式、机器人、微服务等场景,也很适用于需要处理高并发请求的C++后端服务。
行业内主流的C++ Web服务框架很多,比如有Drogon/cpp-httplib/Poco等,与Drogon相比,Oat++更轻量级、依赖更少,与cpp-httplib相比,Oat++提供了更完整的MVC分层架构、DI与测试客户端,与Poco相比,Oat++提供的API接口更聚焦Web服务端场景。
Oat++的核心特性如下:
1.零依赖
纯C++实现,核心逻辑不依赖Boost/OpenSSL/Jsoncpp等第三方库,编译产物很轻量,可轻松移植到嵌入式设备、云服务器等多种平台。
2.高性能
采用异步I/O与多线程模型,内存资源占用低,适合高并发场景。
3.功能和生态完善
内置HTTP服务端/客户端、路由、JSON序列化、Swagger UI、拦截器(AOP)和依赖注入等模块,可快速构建RESTful API服务。
4.轻量易用
API设计简洁,适合C++开发者快速上手,可快速开发RESTful服务。

二、Oat++框架解析
1.Oat++框架核心概念

2.Oat++框架主要组件
2.1 Application:应用程序入口
通过run()方法启动整个服务。它负责加载所有用OATPP_CREATE_COMPONENT声明的组件(如ConnectionProvider、HttpRouter、ObjectMapper等),并完成依赖注入。
样例代码:
class App {
public:
OATPP_CREATE_COMPONENT(std::shared_ptr<oatpp::network::Server>, server)
void run() {
auto server = getComponent<...>();
server->run();
}
};
2.2 Component:组件容器
采用类似Spring的依赖注入(DI)容器思想,以类型和字符串作为key,管理组件的创建与共享。所有组件都通过宏注册,编译期类型安全。
2.3 Router:路由器
内部维护一张映射表,将(方法,路径)映射到Endpoint。路由支持路径参数、通配符、前缀匹配,并允许注册拦截器。
2.4 Endpoint:端点
描述一个具体的处理函数,包含:
请求路径和方法。
参数绑定规则(从query、path、header、body中获取)。
请求与响应的DTO类型。
响应拦截器列表。
2.5 Handler:处理器
真正执行业务的函数指针或可调用对象,接收Request并返回Response。Oat++支持同步处理和协程异步处理两种风格。

Oat++处理Http请求的流程如下:
step.01: ConnectionProvider::getConnection()
step.02: ConnectionHandler::handleConnection()
step.03: HttpProcessor 解析 HTTP 请求
step.04: HttpRouter::getRoute(method, path)
step.05: ApiController 生成的 Endpoint Handler
step.06: 参数映射(PATH / QUERY / BODY_DTO / HEADER)
step.07: 业务逻辑 → createDtoResponse / createResponse
三、Oat++框架核心接口
1.Environment:运行时入口
所有Oat++应用必须在main()中初始化和销毁Environment实例。
Environment::init():初始化
Environment::destroy():释放所有组件与内存池
OATPP_LOGI/D/W/E(tag, fmt, ...):框架内置的日志宏
#include "oatpp/core/base/Environment.hpp"
int main() {
// 初始化内存分配器、组件注册表
oatpp::base::Environment::init();
// ... 应用逻辑 ...
// 释放资源
oatpp::base::Environment::destroy();
return 0;
}
2.Server:Oat服务的生命周期管理
Server(provider, handler):构造服务器,绑定连接提供者与会话处理器
run(conditional):主循环阻塞运行
stop():通知主循环退出
getStatus():获取"STATUS_RUNNING"等状态常量
#include "oatpp/network/Server.hpp"
oatpp::network::Server server(connectionProvider, connectionHandler);
server.run(); // 阻塞运行,循环 accept → handle
server.stop(); // 停止主循环
3.ConnectionProvider:TCP监听
指定需要监听的Tcp网址和端口
#include "oatpp/network/tcp/server/ConnectionProvider.hpp"
auto provider = oatpp::network::tcp::server::ConnectionProvider::createShared({
"0.0.0.0", // 绑定地址
8080, // 端口
oatpp::network::Address::IP_4 // IPv4
});
// provider->getProperty("port") 可获取实际绑定端口
4.HttpRouter:路由表管理
route(method, pathPattern, handler):绑定HTTP Method和路径模式到Handler
addController(controller):自动注册Controller中所有ENDPOINT
getRoute(method, path):解析请求,返回匹配的路由
logRouterMappings():打印路由表(调试用)
补充:路径模式支持"{param}"占位符,例如"/books/{bookId}"。
#include "oatpp/web/server/HttpRouter.hpp"
auto router = oatpp::web::server::HttpRouter::createShared();
// 方式一:直接绑定 Handler
router->route("GET", "/hello", std::make_shared<MyHandler>());
// 方式二:注册 ApiController(推荐)
router->addController(std::make_shared<BookController>());
// 调试:打印所有路由映射
router->logRouterMappings();
5.HttpConnectionHandler:连接处理
createShared(router):创建多线程HTTP处理器(每个HTTP连接对应一个线程)
setErrorHandler(handler):设置全局错误处理器
addRequestInterceptor(i):路由匹配前拦截(鉴权、日志)
addResponseInterceptor(i):响应写出前拦截(CORS、压缩)
getConnectionsCount():查看当前活跃连接数
#include "oatpp/web/server/HttpConnectionHandler.hpp"
auto handler = oatpp::web::server::HttpConnectionHandler::createShared(router);
handler->setErrorHandler(std::make_shared<MyErrorHandler>(objectMapper));
handler->addRequestInterceptor(std::make_shared<AuthInterceptor>());
handler->addResponseInterceptor(std::make_shared<LogInterceptor>());
handler->stop(); // 通知所有工作线程退出
6.ApiController:声明式REST控制器
createResponse(status, body):创建纯文本/字符串响应
createDtoResponse(status, dto):创建JSON DTO响应
Status::CODE_200等:HTTP状态码常量
#include "oatpp/web/server/api/ApiController.hpp"
#include "oatpp/core/macro/codegen.hpp"
#include OATPP_CODEGEN_BEGIN(ApiController)
class BookController : public oatpp::web::server::api::ApiController {
public:
BookController(OATPP_COMPONENT(std::shared_ptr<ObjectMapper>, objectMapper))
: oatpp::web::server::api::ApiController(objectMapper) {}
// 同步端点
ENDPOINT("GET", "/books/{bookId}", getBookById,
PATH(Int64, bookId)) {
// bookId 已自动从路径解析
return createResponse(Status::CODE_200, "OK");
}
// POST + JSON Body
ENDPOINT("POST", "/books", createBook,
BODY_DTO(Object<BookDto>, bookDto)) {
return createDtoResponse(Status::CODE_201, bookDto);
}
};
#include OATPP_CODEGEN_END(ApiController)
ENDPOINT 宏参数映射一览:

7.DTO:数据传输对象
#include "oatpp/core/macro/codegen.hpp"
#include "oatpp/core/Types.hpp"
#include OATPP_CODEGEN_BEGIN(DTO)
class BookDto : public oatpp::DTO {
DTO_INIT(BookDto, DTO)
DTO_FIELD(Int64, id);
DTO_FIELD(String, title);
DTO_FIELD(String, author);
DTO_FIELD(Float64, price);
DTO_FIELD(String, isbn, "isbn"); // 可指定 JSON 字段名
};
class BookListDto : public oatpp::DTO {
DTO_INIT(BookListDto, DTO)
DTO_FIELD(List<Object<BookDto>>, items);
DTO_FIELD(Int32, total);
};
#include OATPP_CODEGEN_END(DTO)
//创建实例
auto dto = BookDto::createShared();
8.AppComponent;依赖注入
使用方法:
void run() {
AppComponent components; // 注册所有组件
OATPP_COMPONENT(std::shared_ptr<oatpp::web::server::HttpRouter>, router);
OATPP_COMPONENT(std::shared_ptr<oatpp::network::ConnectionHandler>, connectionHandler);
OATPP_COMPONENT(std::shared_ptr<oatpp::network::ServerConnectionProvider>, connectionProvider);
// ...
}
代码样例:
#include "oatpp/core/macro/component.hpp"
class AppComponent {
public:
OATPP_CREATE_COMPONENT(std::shared_ptr<oatpp::network::ServerConnectionProvider>, serverConnectionProvider)([] {
return oatpp::network::tcp::server::ConnectionProvider::createShared(
{"0.0.0.0", 8080, oatpp::network::Address::IP_4}
);
}());
OATPP_CREATE_COMPONENT(std::shared_ptr<oatpp::web::server::HttpRouter>, httpRouter)([] {
return oatpp::web::server::HttpRouter::createShared();
}());
OATPP_CREATE_COMPONENT(std::shared_ptr<oatpp::data::mapping::ObjectMapper>, apiObjectMapper)([] {
auto mapper = oatpp::parser::json::mapping::ObjectMapper::createShared();
mapper->getSerializer()->getConfig()->includeNullFields = false;
return mapper;
}());
OATPP_CREATE_COMPONENT(std::shared_ptr<oatpp::network::ConnectionHandler>, serverConnectionHandler)([] {
OATPP_COMPONENT(std::shared_ptr<oatpp::web::server::HttpRouter>, router);
OATPP_COMPONENT(std::shared_ptr<oatpp::data::mapping::ObjectMapper>, objectMapper);
auto handler = oatpp::web::server::HttpConnectionHandler::createShared(router);
handler->setErrorHandler(std::make_shared<ErrorHandler>(objectMapper));
return handler;
}());
};
四、Oat++框架开发环境配置
1.源码编译安装
# 安装构建工具
sudo apt update
sudo apt install -y build-essential cmake git
# 克隆 Oat++ 核心库
git clone https://github.com/oatpp/oatpp.git
cd oatpp
git checkout 1.3.0 # 建议使用稳定 tag
mkdir build && cd build
cmake .. \
-DCMAKE_BUILD_TYPE=Release \
-DCMAKE_INSTALL_PREFIX=/usr/local \
-DOATPP_BUILD_TESTS=OFF
cmake --build . -j$(nproc)
sudo cmake --install .
sudo ldconfig
2.验证安装结果
ls /usr/local/include/oatpp/
# 检查静态库
ls /usr/local/lib/liboatpp.a
# 快速编译测试
cat > /tmp/oatpp_test.cpp << 'EOF'
#include "oatpp/core/base/Environment.hpp"
int main() {
oatpp::base::Environment::init();
oatpp::base::Environment::destroy();
return 0;
}
EOF
g++ -std=c++17 /tmp/oatpp_test.cpp -loatpp -o /tmp/oatpp_test && echo "OK"
五、Oat++框架常见问题
Q1:OATPP_CODEGEN_BEGIN/END 必须成对出现吗?
是的。DTO 和 ApiController 的代码生成段必须用 OATPP_CODEGEN_BEGIN / OATPP_CODEGEN_END 包裹,否则宏冲突会导致编译错误。
Q2:oatpp 1.3.x 编译报 oatpp::DTO / Int64 未定义?
oatpp 1.3.x 中类型别名(DTO、String、Int64 等)统一定义在 oatpp/core/Types.hpp。DTO 头文件应 #include "oatpp/core/Types.hpp",不要直接包含 oatpp/core/data/mapping/type/Object.hpp。
Q3:oatpp 1.3.x 中 ErrorHandler::renderError 编译失败?
1.3.x 移除了 renderError,改为实现 handleError(const Status& status, const oatpp::String& message, const Headers& headers)。JSON 错误响应需使用完整命名空间 oatpp::web::protocol::http::outgoing::ResponseFactory::createResponse(...)。
Q4:oatpp服务返回404?
检查:1) Controller 是否 addController 到 Router;2) 路径前缀是否匹配(api/books vs /api/books);3) HTTP Method 是否正确。
Q5:DTO 字段为 null 时 JSON 输出什么?
默认 includeNullFields = true 时输出 "field": null;设为 false 则省略 null 字段。
Q6:如何支持 HTTPS?
Oat++ 核心不内置 TLS,需配合反向代理(nginx/Caddy)终结 TLS,或使用 oatpp-openssl 社区模块。
Q7:生产环境推荐 Simple 还是 Async API?
IO 密集、高并发选 Async;逻辑简单、团队熟悉多线程选 Simple。多数内部 API 服务 Simple API 已足够。
参考阅读:
GitHub 仓库:https://github.com/oatpp/oatpp
示例项目:https://github.com/oatpp/oatpp-examples
oat++官方文档: https://oatpp.io/docs/start/
DAMO开发者矩阵,由阿里巴巴达摩院和中国互联网协会联合发起,致力于探讨最前沿的技术趋势与应用成果,搭建高质量的交流与分享平台,推动技术创新与产业应用链接,围绕“人工智能与新型计算”构建开放共享的开发者生态。
更多推荐



所有评论(0)