Python 高性能 ASGI 服务器 Uvicorn 库使用指南

Python Uvicorn库使用指南

Uvicorn是一个基于Python的高性能ASGI(Asynchronous Server Gateway Interface)服务器，专为异步Web框架(如FastAPI、Starlette等)设计。以下是Uvicorn的详细介绍和使用方法：

1. Uvicorn简介

Uvicorn是一个轻量级、高性能的ASGI服务器，由Starlette框架的作者编写。它基于asyncio库实现异步I/O操作，支持HTTP和WebSocket协议。Uvicorn使用uvloop作为事件循环和httptools进行HTTP解析，因此比传统的Python服务器更快。

主要特点：

• 高性能：基于uvloop和httptools构建，支持高吞吐量和低延迟
• 支持HTTP/1.1和WebSockets
• 热重载：开发模式下支持代码热重载
• 灵活的配置：通过命令行参数或Python代码自定义运行选项

2. 安装Uvicorn

可以使用pip安装Uvicorn：

pip install uvicorn

为了获得最佳性能，可以安装带Cython优化的版本：

pip install "uvicorn[standard]"

安装完成后，可以通过以下命令验证安装是否成功：

uvicorn –version

3. 基本使用

3.1 运行简单的ASGI应用

创建一个简单的ASGI应用示例：

async def app(scope, receive, send):
assert scope['type'] == 'http'
response = b"Hello, Uvicorn!"
await send({
'type': 'http.response.start',
'status': 200,
'headers': [(b'content-type', b'text/plain')],
})
await send({
'type': 'http.response.body',
'body': response,
})

使用Uvicorn运行该应用：

uvicorn app:app –host 127.0.0.1 –port 8000

3.2 与FastAPI集成

Uvicorn常与FastAPI一起使用：

from fastapi import FastAPI

app = FastAPI()

@app.get("/")
async def read_root():
return {"message": "Welcome to Uvicorn with FastAPI!"}

运行该应用：

uvicorn main:app –reload

–reload参数启用代码热重载功能，每次修改代码后服务器将自动重启

4. 配置选项

Uvicorn提供了丰富的配置选项：

5. 高级功能

5.1 SSL支持

Uvicorn支持通过SSL加密来提供安全的通信：

uvicorn main:app –ssl-keyfile key.pem –ssl-certfile cert.pem

5.2 WebSocket支持

Uvicorn支持处理WebSocket连接：

from fastapi import FastAPI, WebSocket

app = FastAPI()

@app.websocket("/ws")
async def websocket_endpoint(websocket: WebSocket):
await websocket.accept()
while True:
data = await websocket.receive_text()
await websocket.send_text(f"Message text was: {data}")

5.3 中间件

Uvicorn支持使用中间件来修改请求和响应：

from uvicorn.middleware.proxy_headers import ProxyHeadersMiddleware
from uvicorn.middleware.debug import DebugMiddleware
from fastapi import FastAPI

app = FastAPI()

app.add_middleware(ProxyHeadersMiddleware, trusted_hosts=["10.0.0.1"])
app.add_middleware(DebugMiddleware)

5.4 异步任务

Uvicorn支持在异步Web服务中执行异步任务：

from fastapi import FastAPI
import asyncio

app = FastAPI()

async def background_task():
while True:
print("Background task is running…")
await asyncio.sleep(5)

@app.on_event("startup")
async def startup_event():
asyncio.create_task(background_task())

6. 生产环境部署

在生产环境中，通常会将Uvicorn与Gunicorn结合使用：

gunicorn -w 4 -k uvicorn.workers.UvicornWorker main:app

此命令会启动4个工作进程，并使用UvicornWorker管理ASGI应用的多进程环境。

7. 日志配置

Uvicorn提供了灵活的日志配置选项：

import logging
import uvicorn

if __name__ == "__main__":
logging.basicConfig(level=logging.INFO, format="%(asctime)s – %(message)s")
uvicorn.run("main:app", log_level="info")

8. 实际应用场景

8.1 异步API服务

from fastapi import FastAPI

app = FastAPI()

@app.get("/items/{item_id}")
async def read_item(item_id: int):
return {"item_id": item_id}

8.2 实时聊天应用

from fastapi import FastAPI, WebSocket

app = FastAPI()

@app.websocket("/chat")
async def websocket_chat(websocket: WebSocket):
await websocket.accept()
while True:
data = await websocket.receive_text()
await websocket.send_text(f"Message: {data}")

9. 工作原理

Uvicorn运行时分为两大部分：

Uvicorn支持多种HTTP协议实现：

• “auto”: 自动选择(默认)
• “h11”: 基于h11协议的实现
• “httptools”: 基于httptools的实现(性能更高)

10. 与WSGI服务器的区别

总结

Uvicorn是一个功能强大、配置灵活且易于使用的异步Web服务器，非常适合现代Python异步框架的开发和部署。通过合理配置和结合Gunicorn，可以充分利用其高性能和稳定性来处理各种Web请求。