Hical框架

写在前面 两万多行代码写下来，我把踩过的坑和想明白的事都总结在这了。不讲概念，只聊实战中每个设计"为什么这么做"。 搞 C++ Web 框架这事，从第一行代码到现在，说实话走了不少弯路。今天不聊怎么用，聊聊底层那些设计决策——为什么要这么写，当时碰到了什么问题，怎么一步步改成现在这样的。 一、编译期就把活干完 1. 一套模板搞定 TCP 和 SSL 最早我是分别写了 TcpConnection 和 SslConnection 两个类，代码重复率 80%以上，改一个 bug 要改两遍。后来换成 GenericConnection<SocketType>，内部用 if constexpr 做分支： 1 2 3 if constexpr (hIsSslStream<SocketType>) { co_await stream_.async_handshake(...); } 编译器直接在编译期把不匹配的分支丢掉——纯 TCP 的二进制里一个字节的 SSL 代码都没有。维护成本砍半，运行时零开销。这不是什么高深技巧，但真正落地用好的项目不多。 2. 用不到的模块，连编译都不参与 数据库、OpenAPI 这些模块，不是每个项目都用得上。我用 CMake option + 宏隔离的方式处理： 1 option(HICAL_WITH_DATABASE "Enable DB middleware" OFF) 代码里所有 DB 相关的逻辑都包在 #ifdef HICAL_HAS_DATABASE 里。你不开这个 option，这些代码连语法检查都不走，更别说占二进制体积了。比运行时搞个 feature flag 干净太多——运行时 flag 意味着代码虽然不执行，但死代码还在那占着 icache。 3. TRACE 日志：Release 下彻底消失 开发时满屏 TRACE 日志方便调试，但生产环境绝对不能有这些开销。我的做法是 NDEBUG 下 HICAL_LOG_TRACE 直接展开成 ((void)0)——注意，这不是"判断级别后跳过"，而是连参数求值的代码都不存在于二进制中。 ...

写在前面 你有没有想过，一个高并发网络服务器在同时给几千个客户端发消息时，底层到底在忙什么？ 最直觉的做法是加把锁——谁要发消息就抢锁、写 socket、放锁。但问题来了：如果 1000 个协程同时要给同一个连接发数据，它们就得排队等这把锁。锁竞争带来的上下文切换、cache 失效，会把性能拖进泥潭。 Hical 框架的解法很酷：用一个 MPSC（多生产者单消费者）无锁队列 做缓冲，配合一个协程写循环做消费。发消息的线程只管往队列里扔节点（wait-free，永远不阻塞），写循环协程在 IO 线程上批量取出、合并发送。 这篇文章会带你从零搞懂这个设计。不需要你有无锁编程的基础，但最好知道 C++ 的 atomic、shared_ptr 和"什么是协程"大概是怎么回事。 一、先搞清楚问题：为什么普通的锁不行？ 1.1 一个典型场景 假设你写了个聊天服务器。用户 A 发了条群消息，服务器要转发给群里 200 个在线用户。这意味着： 1 用户A的消息 → 广播逻辑 → 同时调用 200 个连接的 send() 如果 send() 内部用 mutex 保护写操作： 1 2 3 4 5 6 7 8 9 10 11 // 朴素实现（有严重性能问题） void Connection::send(std::string data) { std::lock_guard lock(writeMutex_); // 200个协程在这里排队 writeBuffer_.append(data); if (!writing_) { writing_ = true; doWrite(); // 触发实际的 socket 写入 } } 问题出在哪？ ...

优化背景 Hical 是我写的 C++20/26 Web 框架，跑 Hello World 压测时起初只有 27K QPS，而同类框架（Cinatra 165K、Drogon 170K）差了将近一个数量级。目标很明确：追平 Cinatra/Drogon 的水平。 整个优化过程分 6 个阶段，不是拍脑袋乱改，每一步都是 perf + 火焰图定位瓶颈 → 想方案 → 写代码 → 跑压测验证 的循环。能看到数字变化才算数。 阶段 1：协程帧削减（v2.5.1-v2.5.2） 发现问题 perf 火焰图第一个大头：14.5% CPU 在 scheduler::wake_one_thread_and_unlock + pthread_cond_signal。 一开始以为是跨线程调度问题，仔细一看不是——是 Boost.Asio scheduler 每次 co_await resume 都要走的内部调度流程太重了。一个 Hello World 请求居然走了 4 个协程帧： 1 2 3 4 5 handleSession: co_await async_read → 帧 1（必需，I/O 等待） co_await router_.dispatch() → 帧 2（Router 本身是协程） co_await handler(req) → 帧 3（同步 handler 被包装成协程，不必要！） co_await async_write → 帧 4（必需，I/O 等待） 帧 1 和 4 是真正的 I/O 等待不可消除，但帧 2 和 3 完全是浪费——一个同步的 return HttpResponse("Hello") 被裹了两层协程。 ...

Hical 框架开发心得：七个深刻教训 引言 Hical 是一个基于 Boost.Asio 的现代 C++20/26 高性能 Web 框架，采用原生 HTTP/WebSocket 网络栈（picohttpparser + 自研 WebSocket），从第一行代码到现在的 45+ 测试文件、3 层内存池、协程化数据库中间件、自研日志系统、OpenAPI 自动生成、WsHub 广播管理器、QPS 从 27K 到 159K 的优化历程，一路走来踩了不少坑，也收获了很多。 这篇文章不讲 API 用法，也不讲架构教程——那些在其他文章里都有。这篇只聊开发过程中的真实体会：哪些决策事后证明是对的，哪些看似优雅的方案差点把自己埋了，以及最终选择背后的取舍逻辑。 目录 Hical 框架开发心得：七个深刻教训 引言 目录 一、C++20 协程是双刃剑 1.1 协程让异步代码变清晰了……吗？ 1.2 co_await 后 this 可能已经死了 1.3 io_context 析构时的协程帧：成员声明顺序陷阱 1.4 co_spawn(detached) 的悬空引用陷阱 1.5 异常传播：catch 里不能 co_await 1.6 收获：协程不是银弹 二、PMR 三层内存池——收益大但陷阱多 2.1 为什么要三层 2.2 踩坑：upstream 选错导致跨线程竞争 2.3 踩坑：allocator 忘了传播 2.4 收获：PMR 的收益在高并发场景才显现 三、模板 + Concepts 比虚函数继承更适合网络框架 3.1 GenericConnection 的零成本分流 3.2 NetworkBackend concept：可替换但不多态 3.3 收获：编译期分支 > 运行时分支 四、自研日志系统的价值 4.1 为什么不用 spdlog 4.2 六层架构的设计决策 4.3 两个关键的性能优化 4.4 收获：核心框架值得自研，应用项目直接用 spdlog 五、双轨反射——为未来留后路 5.1 问题：C++26 还没来，但 API 要现在设计 5.2 宏回退层的实现策略 5.3 收获：用宏模拟未来语言特性 六、移除 Boost.Beast——火焰图驱动的依赖清退 6.1 Beast 到底慢在哪 6.2 picohttpparser + 零拷贝请求 6.3 自研 WebSocket 栈的取舍 6.4 收获：数据驱动的依赖决策 七、WsHub 广播管理器——从"能用"到"好用"的 WebSocket 架构 7.1 问题：裸连接管理的困境 7.2 WsHub 的核心设计 7.3 写串行化：被忽视的并发陷阱 7.4 收获：框架应该管理连接生命周期 后记：ThreadSanitizer CI 揪出的隐藏竞态（v2.6） Boost.Asio 对象的跨线程操作 stop() 的并发调用：门卫模式 教训 总结：七条核心原则 一、C++20 协程是双刃剑 1.1 协程让异步代码变清晰了……吗？ 在引入协程之前，一个 HTTP 请求的处理链是嵌套回调： ...

Hical 生产部署实践：从编译优化到容器化 框架开发完了，测试也通过了——然后呢？“本地跑得好好的"和"线上稳定运行"之间，隔着编译优化、进程管理、反向代理、监控告警、容器编排一整套工程实践。这篇文章把 Hical 从开发环境搬到生产环境的完整链路走一遍，每个环节都给出可直接复用的配置模板。 目录 Hical 生产部署实践：从编译优化到容器化 目录 一、编译优化：榨干最后一点性能 1.1 Release 基础参数 1.2 LTO（链接时优化） 1.3 PGO（Profile-Guided Optimization） 1.4 静态链接 vs 动态链接 二、进程管理：别让服务裸奔 2.1 systemd 服务配置 2.2 信号处理与 Graceful Shutdown 2.3 多线程与多 acceptor（SO_REUSEPORT） 三、反向代理：Nginx 挡在前面 3.1 HTTP 反向代理 3.2 WebSocket 代理 3.3 SSL 终止策略 四、监控与可观测性 4.1 Prometheus 指标暴露 4.2 日志接入 ELK / Loki 4.3 健康检查端点 五、容器化部署 5.1 多阶段 Dockerfile 5.2 docker-compose 完整示例 5.3 Kubernetes 部署参考 六、性能调优检查清单 系统级 Hical 应用级 PMR 内存池 数据库连接池 日志系统 调优流程 一、编译优化：榨干最后一点性能 1.1 Release 基础参数 开发阶段用 Debug 方便调试，上线必须切 Release。区别不只是 -O2，还有 assert 消除、NDEBUG 定义（Hical 的 HICAL_LOG_TRACE 宏在 NDEBUG 下编译期完全消除）： ...

Hical VS2022 快速上手 Demo 一个最小化的 Hical HTTP Server 示例，VS2022 编译即可运行，访问即返回含中文的 JSON 响应。 环境要求 项目 版本要求 Visual Studio 2022 17.6+ (需勾选"C++桌面开发"工作负载) vcpkg 最新版 CMake >= 3.20 (VS2022 自带即可) 第一步：安装依赖 (vcpkg) 1 2 3 4 5 6 7 # 如果还没装 vcpkg git clone https://github.com/microsoft/vcpkg.git C:\vcpkg cd C:\vcpkg .\bootstrap-vcpkg.bat # 安装 Hical 所需依赖（x64-windows 默认 triplet） .\vcpkg install boost-asio boost-system boost-json boost-beast openssl zlib --triplet=x64-windows 第二步：获取 Hical 源码 1 2 git clone https://github.com/user/hical.git cd hical 第三步：CMake 构建 1 2 3 4 5 # 配置（替换为你的 vcpkg 实际路径，-DHICAL_BUILD_TESTS=OFF 跳过测试编译，加快构建速度） cmake -B build -A x64 -DCMAKE_BUILD_TYPE=Release -DCMAKE_TOOLCHAIN_FILE=C:/vcpkg/scripts/buildsystems/vcpkg.cmake -DHICAL_BUILD_TESTS=OFF # 编译 cmake --build build --config Release 编译成功后，可执行文件位于： ...

起因 最初 Hical 的空闲超时实现就是传统做法：每个 HTTP 请求/每次 keep-alive 读等待都注册一个 steady_timer，读完成后取消，超时则关闭连接。实现上用的是 shared_ptr<function> 自引用环做回调链续期——每连接 2 次堆分配（shared_ptr 控制块 + function 对象），且每次续期都要重新构造回调。 v2.5.2 压测到 132K QPS 时，做热路径Review代码发现这个 timer 机制的问题： 每请求 2 次 epoll_ctl（注册 + 取消 timer） shared_ptr<function> 自引用环本身就有堆分配开销 140K QPS 下整体约产生 100 万次 epoll_ctl/sec，38% CPU 花在内核 _raw_spin_unlock_irqrestore（TCP spin_lock），而用户态框架代码只占不到 5% 瓶颈已经从用户态转移到内核态，减少进内核的次数成为核心策略。空闲超时的 timer 是明确可以砍掉的——30-60s 的超时精度要求本来就极低。 改良过程 分两步走： 第一步：先把 shared_ptr<function> 回调链改为独立协程 idleTimerLoop，消除自引用环和 2 次堆分配。这一步还是 per-connection 一个 timer 协程，只是实现更干净了。 第二步：发现即便使用协程，per-connection timer 仍然意味着每次 timer 到期时要走 scheduler 调度 + epoll_ctl。最终演化为"TcpServer 统一扫描"的设计——整个 server 只需要一个扫描协程，连接侧只写一个 atomic 值。 ...

Hical v2.6.0：移除 Boost.Beast，自研 HTTP/WebSocket 栈全记录 Hical v2.6.0 完成了一次关键架构升级——彻底移除 Boost.Beast 依赖，HTTP 解析/序列化和 WebSocket 全部替换为自研实现。本文从动机、架构设计、关键技术细节、性能数据四个维度，完整记录这次"去 Beast"的工程实践。 目录 Hical v2.6.0：移除 Boost.Beast，自研 HTTP/WebSocket 栈全记录 目录 1. 为什么移除 Boost.Beast 2. 新架构总览 3. 自研 HTTP 解析栈 3.1 picohttpparser：极致轻量的 C 解析器 3.2 零拷贝 NativeRequest 3.3 HeaderMap：L1 友好的头部容器 4. 自研 HTTP 响应序列化 4.1 栈缓冲 + Scatter-Gather I/O 4.2 状态行预计算 5. 自研 WebSocket 栈（RFC 6455） 5.1 帧解析器：WsFrame 5.2 握手协议：WsHandshake 5.3 Permessage-Deflate 压缩 5.4 消息分片重组 5.5 协议安全校验 6. 编译防火墙与工程化 7. 性能对比数据 火焰图逐项对比 QPS 端到端对比 与同类框架对比 8. 迁移影响与 Breaking Changes 对框架使用者 对框架使用者透明的改动 9. 新增依赖 picohttpparser zlib 10. 总结 1. 为什么移除 Boost.Beast Beast 是一个优秀的 HTTP/WebSocket 库，但在 Hical 的高性能场景中，它成了主要瓶颈： ...

Hical 踩坑实录五部曲（五）：Boost.MySQL 协程集成的 5 个坑 引言 Hical 的数据库模块（src/db/）是一个基于协程的连接池 + 中间件系统，后端使用 Boost.MySQL 的 any_connection。从 “能跑” 到 “能在生产环境跑”，中间踩了不少坑。 这篇文章记录了 Boost.MySQL 协程集成过程中遇到的 5 个真实问题，每个都附带完整的解决方案代码。 目录 Hical 踩坑实录五部曲（五）：Boost.MySQL 协程集成的 5 个坑 引言 目录 坑 1：any_connection vs 强类型连接的取舍 坑 2：PreparedStatement 失效与自动重试 坑 3：SET NAMES 注入风险——validateCharset 白名单 坑 4：连接池 acquire 超时的竞争窗口 坑 5：事务忘记 commit/rollback 的自动回滚设计 第一道防线：DbMiddleware 洋葱模型 第二道防线：连接池 release 兜底回滚 附：StmtCache LRU 缓存设计 总结：Boost.MySQL 集成检查清单 坑 1：any_connection vs 强类型连接的取舍 现象：第一版连接池用 Boost.MySQL 的强类型连接（tcp_ssl_connection），结果泛型代码全部被迫模板化——编译时间爆炸，且无法在运行时根据配置切换 TCP/SSL。 强类型方式的问题： 1 2 3 4 5 6 7 8 9 10 11 // ❌ 强类型——泛型代码必须模板化 template <typename Connection> class DbPool { std::vector<std::unique_ptr<Connection>> idle_; // Connection 是 tcp_connection 还是 tcp_ssl_connection？ // 中间件也要模板化、查询日志也要模板化... }; // 编译时决定，运行时无法切换 using Pool = DbPool<boost::mysql::tcp_ssl_connection>; 解决方案：any_connection——类型擦除，运行时决定传输层： ...

Hical 踩坑实录五部曲（四）：PMR 三层内存池——从理论完美到实战翻车 引言 Hical 的内存管理采用 C++20 PMR（Polymorphic Memory Resource）三层池架构：全局同步池 → 线程本地无锁池 → 请求级单调缓冲。理论上完美——每一层解决一个特定的性能瓶颈。 但理论和实战之间，隔着一堆坑。 这篇记录了三层 PMR 池在开发和压测过程中遇到的 7 个真实问题——从跨线程 UAF 到 GC 永远不触发、从 CAS 自旋到缓冲区膨胀，每个都是排查半天以上的教训。 目录 Hical 踩坑实录五部曲（四）：PMR 三层内存池——从理论完美到实战翻车 引言 目录 坑 1：configure() 原地重建的 use-after-free 坑 2：generation 缓存失效的竞争窗口 坑 3：GC 标记了但永远不回收——死线程的内存泄漏 坑 4：CAS 峰值更新的缓存行风暴 坑 5：请求级单调池的 upstream 选错 坑 6：PmrBuffer 缩容不及时导致内存膨胀 坑 7：allocator 传播链断裂——PMR 白忙一场 总结：PMR 三层池的使用清单 坑 1：configure() 原地重建的 use-after-free 现象：在服务启动流程中调用 MemoryPool::configure() 后，偶发崩溃，堆栈指向 synchronized_pool_resource 的内部结构。 根因：configure() 使用 placement new 原地重建全局池——先析构旧池，再构造新池： ...