granian,一个强悍的 Python 库

大家好，我是木木。

今天给大家分享一个【强悍】的 Python 库，granian。

granian 是一个用 Rust 编写的 Python HTTP 服务器，基于 Hyper 和 Tokio 构建。它用单一依赖替代了传统的 Gunicorn + Uvicorn + http-tools 组合，同时支持 ASGI、RSGI、WSGI 三种应用接口，并原生支持 HTTP/2 和 WebSocket。

对于追求高性能和高并发的 Python Web 应用来说，granian 是一个值得关注的部署选择。

项目地址：https://github.com/emmett-framework/granian

特点一：三位一体的接口支持

granian 最大的亮点是同时支持 ASGI、RSGI 和 WSGI 三种协议，开发者无需更换应用层代码，只需切换启动参数即可切换协议。以下示例展示同一个简单应用如何分别以 ASGI 和 RSGI 接口启动：

# app.pyasyncdefapp(scope,receive,send):assertscope['type']=='http'awaitsend({'type':'http.response.start','status':200,'headers':[[b'content-type',b'text/plain']],})awaitsend({'type':'http.response.body','body':b'Hello from granian!',})

ASGI 接口启动命令如下，RSGI 接口只需换参数即可无缝切换：

granian--interfaceasgiapp:app--host0.0.0.0--port8000

WSGI 应用（同步 Flask/Django）同样一行切换，无需额外中间件组合：

granian--interfacewsgimyflaskapp:app

这种灵活性在迁移或对比测试不同协议时非常有用，不需要拆掉一套服务器再搭另一套。

特点二：Rust 引擎带来的性能优势

granian 的核心 HTTP 处理全部在 Rust 层完成，利用 Tokio 异步运行时处理高并发 I/O。granian 的并发控制通过 backpressure 机制实现，在 accept loop 层面限制每个 worker 的最大并发连接数，防止后端过载：

granian--backpressure512myapp:app

backpressure 值需要根据应用特性调优：I/O 密集型应用（如调用外部 API、数据库查询）可以设置较高值；而 CPU 密集型应用由于 GIL 限制，高并发反而可能降低吞吐量，应设置较低值以获得更好的实际吞吐。

特点三：开箱即用的 HTTP/2 和 WebSocket

granian 原生支持 HTTP/2，启用方式极为简单：

granian--http2myasgiapp:app

对于需要长连接和双向通信的场景，WebSocket 支持也已内置，默认开启。HTTP/2 的多路复用特性特别适合微服务架构中的内部通信场景，相比 HTTP/1.1 的序列化管理可以显著降低连接开销。

最佳实践

安装方式

pipinstallgranian

根据需要安装额外依赖：

pipinstallgranian[pname]# 支持进程命名pipinstallgranian[reload]# 开发环境自动重载pipinstallgranian[uvloop]# Linux/macOS 加速

基础 ASGI 服务

以下示例展示用 FastAPI 构建一个简单的 REST 接口，并通过 granian 高性能部署：

# main.pyfromfastapiimportFastAPIapp=FastAPI()@app.get("/hello/{name}")defhello(name:str):return{"message":f"Hello, {name}!"}@app.get("/health")defhealth():return{"status":"ok"}

granian--interfaceasgimain:app--host0.0.0.0--port8000--workers4

静态文件服务

granian 支持直接托管静态文件，无需额外中间件：

granian\--static-path-route/static\--static-path-mount./assets/static\--static-path-expires3600\myapp:app

高级功能：Prometheus 监控指标

granian 内置 Prometheus 格式的运行时指标导出，方便接入现有监控体系：

granian--metrics--metrics-port9090myapp:app

主要可用指标包括：

• granian_workers_spawns：worker 启动次数
• granian_connections_active：当前活跃连接数
• granian_connections_handled：已处理的连接总数
• granian_blocking_threads：当前阻塞线程池大小
• granian_py_wait_cumulative：Python GIL 等待累计时间（free-threaded 构建恒为 0）

通过 Grafana 配合 Prometheus 抓取这些指标，可以直观掌握服务吞吐瓶颈和资源使用情况。

环境与版本信息

• Python：3.8 及以上
• Granian：2.7.2（当前安装版本）
• 操作系统：Linux（推荐）、macOS、Windows
• Rust：granian 内置 Rust 运行时，无需单独安装
• 关键依赖：Hyper（Rust HTTP 库）、Tokio（Rust 异步运行时）

适用

• 需要高性能 HTTP/2 服务的 Python Web 应用
• 想用单一依赖替代 Gunicorn + Uvicorn + http-tools 组合
• 对并发连接数有精确控制需求的生产环境
• 微服务架构中需要统一通信层的企业场景

不适用

• 需要纯 Python 实现的场景（granian 核心为 Rust）
• 依赖 trio 或 gevent 的异步框架
• 需要高级调试工具（如 Django Debug Toolbar）的开发阶段
• ASGI 扩展尚未完全覆盖的高级功能场景

上线检查

1. 确认应用在目标协议（ASGI/WSGI/RSGI）下通过功能测试
2. 使用 ab 或 wrk 进行基准压测，验证 backpressure 值是否需要调优
3. 确认 Prometheus 指标能正常抓取，核心指标无异常峰值