TurboAPI + TurboPG实战:打造零Python参与的Postgres路由,8万QPS端到端实测
TurboAPI + TurboPG实战:打造零Python参与的Postgres路由,8万QPS端到端实测
TurboAPI 是一个与 FastAPI 完全兼容的 Python 框架,底层由 Zig 编写的 HTTP 核心驱动;搭配其 TurboPG(基于 pg.zig 的 Zig 原生 Postgres 客户端),你可以用一行装饰器声明一条 Postgres 路由,让请求从 HTTP 解析、SQL 执行到 JSON 响应全程不经过 Python 解释器,在官方端到端实测中主键查询路由达到 80,791 req/s,比 FastAPI + asyncpg 快约 15 倍。本文带你走通配置步骤,并完整拆解 8 万 QPS 的实测数据。
什么是"零 Python 参与"的 Postgres 路由
传统 FastAPI 项目里,一次 GET /users/42 要经历:uvicorn 收包 → FastAPI 路由匹配 → 调用你的 Python 函数 → asyncpg 查询 → 行数据转 dict → JSON 序列化 → 写回 socket。每一步都在 Python 世界里发生,都要排队等 GIL。
TurboAPI 的思路是把"框架琐事"全部下沉到 Zig 层:
- HTTP 解析、路由匹配:由 Zig 的 radix trie 路由完成
- 参数校验:由 dhi 的 Zig 端 JSON Schema 校验完成,非法请求在拿 GIL 之前就被 422 拒绝
- SQL 执行:由 pg.zig 连接池直接执行,走 prepared statement 缓存
- 结果序列化:Zig 直接把查询结果写成 JSON 回写给 socket
你的业务函数甚至可以为空——路由声明完,数据就通了。这正是标题中"零 Python 参与"的含义:GIL 全程未被获取。
核心实现位于 zig/src/db.zig,开头注释写得很直白:HTTP request → dhi validate → pg.zig query → JSON response,No GIL acquired at any point。
三步配置:从 FastAPI 习惯到 TurboPG
对新手来说,最友好的部分是 API 几乎和 FastAPI 一样。以"按主键取一行"为例,只需三步:
from turboapi import TurboAPI
app = TurboAPI()
# 第 1 步:配置 Postgres 连接池(Zig 层,pool_size 建议 16~64)
app.configure_db("postgres://user:pass@localhost/mydb", pool_size=16)
# 第 2 步:声明一条 db 路由,指定表名和主键
@app.db_get("/users/{user_id}", table="users", pk="id")
def get_user(): pass
# 第 3 步:启动
app.run()
GET /users/42 进来后,Zig 会自己拼出 SELECT * FROM users WHERE id = 42,执行后把行数据原样以 JSON 返回——中间那个空的 Python 函数根本不会被调用。
除了 db_get,装饰器家族还覆盖了常见 CRUD 场景,定义见 python/turboapi/zig_integration.py:
| 装饰器 | 作用 | 典型用法 |
|---|---|---|
@app.db_get |
按主键 SELECT | db_get("/users/{user_id}", table="users") |
@app.db_list |
SELECT 列表,支持 ?limit=&offset= |
db_list("/users", table="users") |
@app.db_post |
由校验过的 JSON body 生成 INSERT | db_post("/users", table="users", model=User) |
@app.db_delete |
按主键 DELETE | db_delete("/users/{user_id}", table="users") |
@app.db_query |
自定义 SQL,支持 pgvector / JSONB / CTE | db_query("GET", "/similar/{id}", sql="...", params=[...]) |
需要复杂 SQL(比如向量相似度搜索)时,db_query 直接写原生 SQL 并用 $1、$2 占位参数,同样全程在 Zig 端执行。
💡 如果你想在不启动 HTTP 服务的场景(脚本、后台任务)中用数据库,
turbopg也可独立使用:pip install turbopg,Database(conn, pool_size=16)提供query / query_one / execute / execute_many四个方法,优先走 Zig 原生路径,详见 python/turbopg/client.py 和 python/turbopg/README.md。
8万QPS实测:端到端 HTTP + DB 基准数据
官方基准位于 benchmarks/postgres/ 目录,方法是三套技术栈跑完全相同的 HTTP 路由、同一个灌好数据的 Docker Postgres 18,用 wrk -t4 -c100 -d10s 压测,并显式关闭 TurboAPI 的响应缓存与 DB 缓存(TURBO_DISABLE_CACHE=1、TURBO_DISABLE_DB_CACHE=1),保证测的是真实数据库压力而非缓存。
完整数据与三次复跑区间记录在 benchmarks/postgres/BENCHMARKS.md:
| 路由 | TurboAPI + pg.zig | FastAPI + asyncpg | FastAPI + SQLAlchemy | 加速比(vs asyncpg) |
|---|---|---|---|---|
GET /health |
266,351/s | 9,161/s | 5,010/s | ~29x |
GET /users/{id}(1000 个不同 ID) |
80,791/s | 5,203/s | 1,983/s | ~15.5x |
GET /users?age_min=20 |
71,650/s | 3,162/s | 1,427/s | ~23x |
GET /search?q=user_42% |
13,245/s | 3,915/s | 1,742/s | ~3.4x |
几个值得注意的细节:
- 主键查询 80,791 req/s 就是标题里"8 万 QPS"的来源,三次复跑区间为 77,768 ~ 94,248 req/s,而 FastAPI + asyncpg 只有 4,973 ~ 5,464 req/s
- 模糊搜索(LIKE 全表扫描)相对加速比最低,因为该场景 CPU 花在 Postgres 扫描上,框架差异被稀释——但 TurboAPI 依然领先 3.4 倍
- 连接池规模可继续调:同一环境下池大小 16 → 32 → 64 时,
GET /users/{id}从 13.2k 提升到 25.7k req/s(该主机上对比池受连接数上限约束,公平基线取 32),说明瓶颈还在数据库并发侧,远未触顶
上图是纯 HTTP 层(无数据库)的 wrk 对比:在 Hello World、JSON 返回、路径参数等 5 类路由上,TurboAPI 稳定领先 FastAPI 1.8x~3.1x。数据库路由的高倍数(15x+)正是在这层基础上叠加"跳过 Python 做 CRUD"的收益。
延迟侧同样占优:平均延迟与 p99 均低于 FastAPI,模型校验类路由的 p99 差距尤其明显——因为 Zig 在进 GIL 之前就拒绝了非法请求,省掉了最慢的那一段 Python 校验路径。
为什么能这么快?四个关键点
- GIL 彻底出局:db 路由的整条链路(解析 → 校验 → 查询 → 序列化)都在 Zig 线程池里完成,Python 解释器只是"旁观者",不存在锁竞争
- prepared statement 自动缓存:
configure_db会为每条路由的 SQL 自动启用 prepared statement,首次执行后重复查询跳过 Parse 阶段,见 zig/src/db.zig - 零中间表示:查询结果不经过 dict、dataclass 或任何 Python 对象,二进制协议数据直接转 JSON 字节流写出,无
memcpy、无临时缓冲 - 可选的 DB 结果缓存:生产环境可开启(默认 30s TTL、1 万条上限、按表失效),缓存命中时走 Zig HashMap 而非 Postgres;对比测试中会显式关闭它以保证公平
如何复现这套基准
整个基准全部跑在 Docker 里,无需本地装任何依赖(约需 8GB 内存、5 分钟):
cd benchmarks/postgres
docker compose up --build --abort-on-container-exit bench
编排与说明见 benchmarks/postgres/README.md,压测编排逻辑在 benchmarks/postgres/bench.py(wrk 参数、池大小均可通过 BENCH_POOL_SIZE 等环境变量调整)。另有 benchmarks/pgbench/BENCHMARKS.md 提供了纯驱动(无 HTTP)的 Postgres 基准,可用来单独评估 turbopg 相对 asyncpg/psycopg3 的查询性能——注意两类数字不要混用。
新手注意事项
- 当前为 Alpha 阶段:官方建议生产环境前置 Caddy/nginx 等反向代理处理 TLS,并保留边缘鉴权;详见 SECURITY.md
- 运行环境要求 Python 3.14t(free-threaded)+ 官方指定的 Zig nightly,最省事的方式是
docker compose up - 混合使用:db 路由与普通
@app.get路由可共存,需要业务逻辑的接口照常写 Python handler,两者共享同一连接池 - 纯 HTTP 基准的详细文档见 docs/BENCHMARKS.md
总结
TurboAPI + TurboPG 的价值可以浓缩成一句话:把 FastAPI 的写法保留下来,把 8 万次/秒里 Python 该背的锅甩给 Zig。对已有 FastAPI 代码库的团队,这是 import 一行替换级别的升级;对新建的高并发读多写少服务,db_get/db_query 这类装饰器让"Postgres 路由"变得和声明一个静态路由一样轻。实测 80,791 req/s 的主键查询吞吐证明:Python 生态的业务能力与接近原生的数据库路由性能,现在可以兼得。



