Skip to content
项目

Hical61/Hical has 63 GitHub stars and 13 forks. GitHot measured 0 stars in 24 hours, +1 in 7 days, and +1 in 15 days. Last checked 2026-11-16 00:16 UTC. Last push 2026-11-03.

这些数字如何统计

可以做什么

  • Native network stack — picohttpparser zero-copy HTTP parsing + self-developed WebSocket (RFC 6455), zero heap allocation
  • C++26 Reflection — Automatic route registration + JSON serialization; seamless C++20 macro fallback
  • Coroutine async I/O — asio::awaitable<T> + co_await, sync fast path with zero coroutine frame overhead
  • PMR three-tier pool — Global synchronized / thread-local lock-free pool for connection-level allocations; request path uses ReadBufferPool + stack arrays + FixedBuffer for actual zero heap allocation

实测星标增长

24小时
0
7天
+1
15天
+1
1个月
正在收集历史

各周期内的星标净变化,周期相互重叠,并非每日新增。缺失的测量保持空白。星标代表关注度,不代表软件质量。

关于

Modern C++20 web framework with optional C++26 reflection and PMR memory pools — built on Boost.Asio, coroutines, high performance

网站与应用

README_CN.md

原文

hical

CI License: MIT C++ Standard Platform Boost GitHub release GitHub stars PRs Welcome HttpArena H/1.1 HttpArena WebSocket

📖 升级迁移指南请查阅 CHANGELOG
💬 问题或建议请开 Discussion

Hical 是一个基于 Boost.Asio 的现代 C++20/26 高性能 Web 框架,采用原生 HTTP/WebSocket 网络栈(picohttpparser + 自研 WebSocket),利用 C++26 反射和 PMR 内存池实现极致性能。

项目状态:Stable — 生产可用,遵循 语义化版本。

English | 简体中文

为什么选择 Hical?

下面所有数字都来自 HttpArena——一个把各家框架放在同一台机器、同一轮次、同一个压测工具下跑的独立榜单。不用自己的硬件,也不挑场景。

吞吐与并发 —— 全部 profile

分类 Profile 连接 吞吐 平均延迟 p99 CPU 内存
连接 baseline 4,096 3,202,325 req/s 1.28 ms 1.80 ms 6288.6% 133 MiB
pipelined 4,096 18,365,348 req/s 3.57 ms 5.72 ms 6626.4% 148 MiB
limited-conn 4,096 2,385,743 req/s 1.70 ms 25.00 ms 6185.3% 73 MiB
并发 async(等 10 ms) 32,000 1,920,543 req/s 16.52 ms 19.00 ms 6428.7% 900 MiB
负载 json-comp 4,096 395,704 req/s 10.18 ms 235.90 ms 6284.4% 78 MiB
json-comp 16,384 381,469 req/s 39.04 ms 997.90 ms 6530.0% 214 MiB
json-tls 4,096 895,583 req/s 4.56 ms 63.82 ms 6731.7% 518 MiB
8gbit(流式回显) 512 49,350 req/s 103.9 µs 147.0 µs 287.4% 107 MiB
WebSocket echo-ws 512 3,460,015 msg/s 147 µs 296 µs 6313.2% 47 MiB
echo-ws 4,096 3,503,912 msg/s 1.17 ms 1.75 ms 6608.7% 158 MiB
echo-ws 16,384 3,062,490 msg/s 5.31 ms 6.48 ms 6591.1% 533 MiB
echo-ws-pipeline 512 37,055,516 msg/s 220 µs 384 µs 6620.9% 47 MiB
echo-ws-pipeline 4,096 36,420,220 msg/s 1.80 ms 2.19 ms 6740.8% 159 MiB
echo-ws-pipeline 16,384 32,132,291 msg/s 8.12 ms 9.39 ms 6718.7% 533 MiB
echo-ws-limited 512 1,866,258 msg/s 185 µs 560 µs 5741.8% 81 MiB
echo-ws-limited 4,096 2,192,315 msg/s 540 µs 1.01 ms 6461.4% 168 MiB

延迟与 CPU 效率 —— 固定速率

和上面的峰值吞吐不同,这几个 profile 把供给速率钉死,能扛住的机器交付的 RPS 都一样,所以排名完全取决于每请求 CPU 成本(从 cgroup v2 的 cpu.stat 精确读出,不是采样):

Profile 钉住的速率 实际交付 CPU / 请求 CPU 平均延迟 p99
latency-1m 1,000,000 req/s 99.8% 22.55 µs 2460.8% 94.5 µs 175.0 µs
latency-10k 10,000 req/s 99.8% 29.78 µs 28.5% 80.9 µs 112.0 µs
latency-500k-8cpu 500,000 req/s,4 核 8 线程 86.1% 18.52 µs 796.2% 1.25 s 4.98 s

几个结论

  • 流水线 HTTP/1.1:1837 万 req/s。 一次读出来的多个请求共用一次写,而不是一个请求一趟系统调用。
  • 批量 WebSocket:3642 万 msg/s。 同样的思路用在帧上。
  • 内存是差异点。 4096 条并发连接只占 133 MiB;同一轮里 HTTP/1.1 复合分第一的那个框架要 4.3 GiB,差 30 倍以上。来源是三件事:PMR 三层内存池、连接级 ReadBufferPool,以及「空闲连接不持有任何读缓冲」。
  • 满载时也便宜。 扛住钉死的 100 万 req/s 时,一个请求在所有线程上合计只花 22.55 µs CPU 时间——直接从容器 cgroup 的 cpu.stat 读出来,不是采样。

自己复现

上面的数字来自 HttpArena 的受控环境,你自己的硬件跑出来会不一样。想在本地跑同类型的对比(含 Drogon / Cinatra / Crow / Gin / Actix):

cd benchmark && docker compose up

核心特性

  • 原生网络栈 — picohttpparser 零拷贝 HTTP 解析 + 自研 WebSocket (RFC 6455),零堆分配
  • C++26 反射 — 自动路由注册 + JSON 序列化;C++20 宏无缝回退
  • 协程异步 I/O — asio::awaitable<T> + co_await,同步快速路径零协程帧开销
  • PMR 三层内存池 — 全局同步池 / 线程本地无锁池(连接级分配);请求路径用 ReadBufferPool + 栈数组 + FixedBuffer 实现零堆分配
  • 全功能中间件 — 洋葱模型、CORS、Session、日志、OpenAPI 3.0 文档生成
  • WebSocket — permessage-deflate 压缩、Hub 广播、子协议协商、心跳
  • 数据库中间件 — 协程连接池 + 自动事务 + 慢查询检测(Boost.MySQL)
  • 生产就绪 — SSL/TLS、SO_REUSEPORT 多 acceptor、静态文件 ETag/304、Docker 部署

完整特性列表见 架构设计。

快速开始

#include "core/HttpServer.h"

using namespace hical;

int main()
{
    HttpServer server(8080);

    server.router().get("/", [](const HttpRequest&) -> HttpResponse {
        return HttpResponse::json({{"message", "Hello, Hical!"}});
    });

    server.router().get("/users/{id}",
        [](const HttpRequest& req) -> HttpResponse {
            return HttpResponse::json({{"userId", req.param("id")}});
        });

    server.start();
}
curl http://localhost:8080/
# {"message":"Hello, Hical!"}

完整教程见 快速上手,更多示例见 examples/。

依赖

依赖项 说明
C++20/26 C++26 可选(反射)
Boost >= 1.82 Asio, System, JSON;DB 中间件需 >= 1.85
OpenSSL 必需
zlib 必需(WebSocket 压缩)
CMake >= 3.28 构建系统
GCC 14+ / Clang 20+ / MSVC 2022+ 编译器

构建

# Linux / macOS
cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build -j$(nproc)
ctest --test-dir build --output-on-failure

# Windows (MSYS2 MINGW64)
cmake -B build -G Ninja -DCMAKE_BUILD_TYPE=Release
cmake --build build

# Windows (MSVC + vcpkg)
cmake -B build -DCMAKE_BUILD_TYPE=Release -DCMAKE_TOOLCHAIN_FILE=C:/vcpkg/scripts/buildsystems/vcpkg.cmake
cmake --build build --config Release

可选模块:

cmake -B build -DHICAL_WITH_DATABASE=ON ...    # 数据库中间件
cmake -B build -DHICAL_WITH_OPENAPI=OFF ...    # 禁用 OpenAPI
cmake -B build -DHICAL_ENABLE_REFLECTION=ON ...# C++26 反射

Docker

# 生产部署
docker compose -f docker/prod/docker-compose.yml up -d

安装

vcpkg(推荐)

vcpkg install hical61-hical
find_package(hical CONFIG REQUIRED)
target_link_libraries(my_app PRIVATE hical::hical_core)

Conan

从 GitHub Releases 下载 Conan 源码包并导入本地缓存:

# 下载并解压(将 VERSION 替换为实际版本号)
curl -LO https://github.com/Hical61/Hical/releases/download/vVERSION/hical-VERSION-conan-src.tar.gz
tar xzf hical-VERSION-conan-src.tar.gz

# 导出到本地 Conan 缓存
cd hical
conan export . --version=VERSION
conan install . --build=missing
find_package(hical REQUIRED)
target_link_libraries(my_app PRIVATE hical::hical_core)

国内用户如遇 GitHub 下载困难,可使用 GitHub Releases 镜像 或从 Release 附件手动下载。 详见 集成指南。

文档

参与贡献

欢迎贡献代码!基本流程:

  1. Fork 本仓库
  2. 创建特性分支 (git checkout -b feat/my-feature)
  3. 确保通过 clang-format 格式检查和测试
  4. 提交 Pull Request

详见 CONTRIBUTING.md。

联系方式

许可证

MIT