Drogon 版本演进全解读:从 ChangeLog 看 C++ Web 框架七年技术迭代
Drogon 版本演进全解读:从 ChangeLog 看 C++ Web 框架七年技术迭代
本指南以 Drogon 仓库根目录的 ChangeLog.md 为骨架,系统梳理 Drogon(一个运行于 Linux/macOS/Unix/Windows 的 C++14/17/20 HTTP Web 应用框架)从 1.0.0-beta1(2019 年)到 1.9.13(2026 年)的完整演进脉络。通过对照 lib/inc/drogon、orm_lib/inc/drogon/orm 等源码目录,你将掌握框架各版本新增的核心 API 的真实签名与用法、ORM/协程/中间件等关键能力的沉淀过程,以及如何依据 ChangeLog 快速定位源码实现。
版本时间线与发布节奏
ChangeLog 采用 Keep a Changelog 风格,每个版本分为 API changes list、Changed、Fixed(早期版本为 Changes/Added)三类条目,并附有与上一版本的 diff 链接。从版本序列可以清晰看到 Drogon 的演进节奏:
| 版本 | 发布时间 | 里程碑主题 |
|---|---|---|
| 1.0.0-beta1 ~ beta21 | 2019-06 ~ 2020-08 | 框架奠基:路由、AOP、ORM、drogon_ctl、流水线优化 |
| 1.0.0 | 2020-09-27 | 首个正式版 |
| 1.1.0 ~ 1.4.0 | 2020-10 ~ 2021-03 | 协程支持(1.4.0)、Redis 支持(1.5.0) |
| 1.5.0 ~ 1.7.5 | 2021-04 ~ 2022-02 | Redis/WebSocket/限流器/会话事件/异步通知 |
| 1.8.0 ~ 1.8.6 | 2022-09 ~ 2023-08 | 流水线模式、请求流、YAML 配置、drogon_test |
| 1.9.0-rc.1 ~ 1.9.13 | 2023-09 ~ 2026-05 | 中间件、WebDAV、ORM JOIN、when_all 协程门控等 |
当前仓库未发布版本([Unreleased])预告了 HttpAppFramework::hasDbClient() 与 hasFastDbClient() 两个新方法。
最新版本 1.9.13 深度解析(2026-05-06)
框架层面新增 API
Unreleased 与 1.9.13 最值得关注的是框架运行状态查询能力。在 HttpAppFramework.h 中,新增了两个纯虚方法:
virtual bool hasDbClient(const std::string &name = "default") const = 0;
virtual bool hasFastDbClient(const std::string &name = "default") const = 0;
文档注释明确要求“此方法必须在框架 run 之后调用”。它们的用途是查询指定名称的普通数据库客户端与 fast(无锁)数据库客户端是否已被创建,可避免在插件或后续初始化逻辑中盲目调用 getDbClient() 导致异常,适合在应用启动后期做依赖健康检查。从源码结构看,这两个方法对应 DbClientManager.h 与 RedisClientManager.h 中客户端池的注册状态。
请求对象增强
1.9.13 为 HttpRequest.h 新增三组 API:
clearHeaders()(L163):一次性清空请求的全部 HTTP 头部,适合在代理/转发场景中基于原始请求构建“干净”的新请求;setQueryParameter(key, value)(L444)与setBodyParameter(key, value)(L451):分别向请求的 query string 和 body 参数表写入键值对,便于在过滤器或 AOP 建议中修改参数后再向下游传递。
数据库事务模式:BEGIN IMMEDIATE / BEGIN EXCLUSIVE
1.9.13 起,SQLite 事务支持三种启动模式,对应 DbClient.h 中的枚举:
enum class TransactionMode
{
Deferred, ///< BEGIN — 首次写操作时才加锁(默认)
Immediate, ///< BEGIN IMMEDIATE — 立即获取写锁(仅 SQLite)
Exclusive, ///< BEGIN EXCLUSIVE — 立即获取排他锁(仅 SQLite)
};
Immediate 与 Exclusive 在写入密集的 SQLite 场景下可以提前锁定、规避“database is locked”竞争窗口。创建事务时可显式传入该模式,例如 app().getDbClient()->newTransaction(TransactionMode::Immediate)。
UploadFile 内存数据构造
UploadFile.h 新增了从内存数据直接构造 UploadFile 的构造函数:
explicit UploadFile(const void *data,
const size_t len,
const std::string &fileName = "memory.bin",
const std::string &itemName = "file",
ContentType contentType = CT_APPLICATION_OCTET_STREAM);
与原有的“文件路径构造”版本相比,该重载允许在不落盘的情况下把缓冲区内容包装成上传文件对象,适合内存中生成的报表、图片等响应式文件流。
ORM JOIN 支持与代码生成器外键自动检测
1.9.13 为 ORM 全面引入了 JOIN 能力。在 BaseBuilder.h 中定义了 JoinType 枚举(InnerJoin、LeftJoin、RightJoin、FullJoin),并以 JoinClause 结构体承载表名与 ON 两侧字段;FilterBuilder.h、Mapper.h、CoroMapper.h 均提供 innerJoin/leftJoin/rightJoin/fullJoin(table, onLeft, onRight) 链式方法,最终由 BaseBuilder 拼装出 ... FROM t1 INNER JOIN t2 ON t1.id = t2.user_id 形式的 SQL。drogon_ctl 的模型生成器同步支持基于外键的关联自动检测,配合 JOIN 可直接在 ORM 层完成多表查询。
WebDAV 方法与按请求压缩控制
- WebDAV 方法:
HttpMethod枚举新增Propfind、Mkcol、Copy、Move,对应字符串PROPFIND、MKCOL、COPY、MOVE,见 HttpTypes.h。同时修复了 HttpClient 不发 WebDAV 请求的问题,使 Drogon 可用作 WebDAV 客户端/服务端的基础。 - 按请求压缩控制:
HttpResponse::setAllowCompression(bool)(见 HttpResponse.h)与allowCompression()使开发者可以对单个响应决定是否启用压缩,覆盖全局压缩配置,适合对已压缩内容或小体积响应跳过压缩开销。
其他值得注意的修复
1.9.13 修复清单还覆盖:HTTP 日期格式化改为与 locale 无关(避免不同语言环境下日期头格式错乱)、HTTP 头中非法数字解析、连接数限制 bug、共享库视图加载失败处理、drogon_ctl 在 clang-cl 下的编译、正则 WebSocket 路由的中间件初始化顺序、SharedLibManager 用 execvp() 替换 system()(消除 shell 注入面)等。构建层面为 CMake finder 模块加入了 Homebrew Apple Silicon 路径探测。
1.9.x 系列功能演进回顾
1.9.0 ~ 1.9.5:协程深化与中间件(2023-09 ~ 2024-06)
- 1.9.0-rc.1:放弃 C++14 构建支持,全面转向 C++17 起;
HttpRequest::isHead()保留原始方法信息;新增访问路由匹配参数的方法;execCommandSync允许省略模板参数;引入 Prometheus 插件(见 plugins/PromExporter.h)。 - 1.9.1:自定义错误处理器可拿到
HttpRequestPtr;新增列自增函数;setExceptionHandler改为返回框架引用以支持链式调用;自定义会话(Custom sessions)能力落地。 - 1.9.2:集成 spdlog 作为日志后端;支持异步发送 chunked 响应;
drogon_ctl press新增-k选项(保活压测)。 - 1.9.3:新增
getParameter()与getOptionalParameter();WebSocket 数据面改用std::string_view;CI 引入 cpplint。 - 1.9.4:WebSocket 支持客户端证书;
WebSocketConnection新增 JSON 发送重载;实现数据库断线重连循环。 - 1.9.5:支持 PostgreSQL 连接选项;WebSocket 控制器支持正则路由;新增
registerMiddleware方法。
其中 registerMiddleware(见 HttpAppFramework.h)配合 HttpMiddleware.h 的 HttpMiddlewareBase::invoke(req, nextCb, mcb) 接口,构成了与过滤器(Filter)互补的中间件拦截链。
1.9.6 ~ 1.9.9:请求流与安全加固(2024-07 ~ 2025-01)
- 1.9.6:
HttpServer支持setsockopt;请求流(RequestStream)支持——服务端可以边收边读请求体,见 RequestStream.h;MultiPartParser支持 PATCH;新增 prometheus 示例(examples/prometheus_example)。 - 1.9.7:协程互斥锁(coroutine mutex);
requestsBufferSize配置;SQLite3 异常类型细化;新增运行期热重载 SSL 证书的方法(无需重启进程)。 - 1.9.8:就地 Base64 编解码;客户端连接状态检查;
Hodor插件新增白名单(见 plugins/Hodor.h);PostgreSQL 转义标识符支持;查询参数允许空值;drogon_ctl支持发送自定义 HTTP 请求。 - 1.9.9:Cookie 新增 Partitioned 标志(Cookie.h 的
setPartitioned(bool),对应 CHIPS 规范,用于第三方场景下的分区存储);移除系统 locale 依赖。
1.9.10 ~ 1.9.12:稳定性与连接管理(2025-02 ~ 2026-01)
- 1.9.10:新增
setConnectionCallback;ORM 查询返回避免多余拷贝;quit()线程安全;AccessLogger插件新增path_exempt配置(见 plugins/AccessLogger.h,值为正则或正则数组,匹配的路径不记日志)。 - 1.9.11:
execSqlCoro新增重载(DbClient.h 与 L249 的 vector 版本);构建期间不再写入源码目录;drogon_ctl create models新增-o|--output输出目录选项;支持 iOS 编译;WebSocketMessageParser 支持 continuation frame;新增RawParameter(SqlBinder.h)以向 SQL 注入原始参数;新增 CORS 示例(examples/cors)。 - 1.9.12:实现 when_all 协程门控——coroutine.h 中的
when_all(tasks...)可并发等待多个 Task;模型新增toString方法;MySQL ORM 支持无符号整型;MySQL 异常错误码透传到SqlError。
跨版本能力沉淀:按主题纵深
HTTP 协议层
从早期“支持 HTTP pipelining 优化”(1.0.0-beta3)到 1.9.13 的 WebDAV 与按请求压缩,协议层经历了:content-length 校验(非法值返回 400)、chunked 编码请求处理(1.0.0-beta19)、101 Switching Protocols 响应不再携带 content-length(1.9.8)、TLS 1.0/1.1 默认禁用(1.1.0)、头部统一小写化与 webp/avif 类型(1.4.0)、按 Range 发送文件(1.7.3)、自定义 MIME 类型(1.7.3)、bro/brotli 压缩(1.0.0-beta15/16)以及 HttpRequest::newFileResponse 内存缓冲支持(1.5.0)。这些能力沉淀在 HttpResponse.cc、StaticFileRouter.cc 等实现中。
ORM 与数据库
ORM 是演进最密集的模块之一:Criteria 从基础比较到 Not In(1.7.5)、not like(1.8.0)、可选的 &&/|| 运算符(1.9.0);QueryBuilder(1.8.5)与 1.9.13 的 JOIN 体系共同支撑复杂查询;SqlBinder 支持 std::string_view(1.8.1)、std::optional(1.2.0)、函数指针绑定修复、非 const 引用参数重载(1.7.4)。数据库客户端侧:MySQL 自动重连(1.8.0)、PostgreSQL pipeline 模式(1.8.0)与异步 LISTEN/NOTIFY(1.8.3)、数据库断线重连循环(1.9.4)。注意 RawParameter 用于传入已转义的原始 SQL 片段,使用时应自行保证安全。
协程支持
1.4.0 引入协程,此后持续强化:async_run(1.7.3)、switchThreadCoro()/queueInLoopCoro(1.8.4)、协程过滤器(1.8.0)、CoroMapper 方法链(1.7.4 附近)、协程互斥锁(1.9.7)与 when_all 门控(1.9.12)。开发协程接口时需注意 ChangeLog 反复提及的边界修复:协程帧泄漏、sync_wait/co_future 的 use-after-free、awaitable 赋值时协程帧释放、Windows 协程异常等,这些修复使 coroutine.h 的语义趋于严谨。
中间件、过滤器与插件生态
- AOP:从同步 join point(1.0.0-beta7)到
PreSendingAdvice(1.7.0)、每个响应可修改的新 join point(1.0.0-beta18),再到“所有过滤器、AOP 建议与处理器均在 IO 线程内执行”的约束(1.8.5)。 - 插件:AccessLogger(1.7.0,含
path_exempt)、Hodor(含白名单)、RealIpResolver(1.9.2 移入 PreRouting 阶段)、SlashRemover、SecureSSLRedirector、PromExporter、GlobalFilters(1.8.5),插件支持无配置文件注册(1.8.5)且以shared_ptr存储。 - 会话:会话事件
onSessionStart/onSessionDestroy(1.8.3)、同站会话 Cookie 选项(1.8.0)、自定义会话(1.9.1)。
构建、跨平台与工具链
ChangeLog 记录了从“修 Windows 编译”到系统化 CI 的过程:MSVC/MinGW/MSYS2 兼容修复、OpenBSD/FreeBSD/Android/HaikuOS 实验支持、iOS 编译(1.9.11)、Apple Silicon Homebrew 路径探测、BUILD_CTL/BUILD_EXAMPLES 选项规范化、BUILD_TRANTOR_SHARED 更名 BUILD_SHARED_LIBS(1.8.0)、find_package(Drogon) 与 DrogonConfig.cmake(1.0.0-beta6)、CPack 生成 .deb/.rpm(1.7.2)、CPPLINT/clang-format/codespell 进入 CI 质量门禁。drogon_ctl 的模型/视图/控制器生成器也在持续修复,如 --clear-output(1.9.13,见 create_model.cc)、--path-to-namespace(1.1.0)、模型生成中的复合主键修复等。
如何依据 ChangeLog 定位源码
ChangeLog 每一条目都能在源码中找到对应实现,推荐检索路径:
- 框架 API:
HttpAppFramework接口集中在 HttpAppFramework.h,实现位于 HttpAppFrameworkImpl.cc; - 请求/响应:HttpRequest.h 与 HttpResponse.h(实现见 HttpRequestImpl.cc、HttpResponseImpl.cc);
- ORM:orm_lib/inc/drogon/orm 目录下的 Mapper/FilterBuilder/BaseBuilder/Criteria/SqlBinder;
- 插件:plugins 目录及 lib/src 中同名实现;
- 工具命令:drogon_ctl 目录下的 create.cc/press.cc/help.cc 等;
- 测试佐证:ChangeLog 中“修复”类条目大多伴随 lib/tests/unittests 与 lib/tests/integration_test 的用例更新,可交叉验证行为。
结语
透过 ChangeLog 的 2000 余行记录,可以完整还原 Drogon 从 2019 年 beta 到 2026 年 1.9.13 的能力地图:协程与异步 I/O 的持续打磨、ORM 查询能力的系统化补全、HTTP/WebSocket 协议细节的严谨修正、跨平台构建的长期投入,以及插件/中间件生态的逐步完善。对于使用 Drogon 的开发者,ChangeLog 既是升级迁移的索引,也是理解框架设计取舍的第一手资料——每个“API changes list”条目,都能在 lib/inc/drogon 与 orm_lib 中找到它今日的最终形态。