什么是 Uvicorn？
Uvicorn 是一个轻量级、超快速的 ASGI (Asynchronous Server Gateway Interface) 服务器实现，基于 uvloop 和 httptools 构建。它主要用于运行异步 Python Web 应用，特别是 FastAPI 和 Starlette 框架。
核心特点
- 高性能: 使用 uvloop 作为事件循环，性能接近 Go 和 Node.js
- ASGI 标准: 支持异步 Python Web 框架
- WebSocket 支持: 原生支持 WebSocket 连接
- 自动重载: 开发模式下代码改动自动重启
- 生产就绪: 支持多进程部署
安装
# 基础安装
pip install uvicorn
# 推荐安装（包含额外性能依赖）
pip install uvicorn[standard]
# 使用 Poetry（你的项目使用的方式）
poetry add uvicorn
基础使用
1. 创建最简单的应用
创建一个 app.py 文件：
async def app(scope, receive, send):
"""最基础的 ASGI 应用"""
assert scope['type'] == 'http'
await send({
'type': 'http.response.start',
'status': 200,
'headers': [
[b'content-type', b'text/plain'],
],
})
await send({
'type': 'http.response.body',
'body': b'Hello, World!',
})
运行：
uvicorn app:app
访问 http://localhost:8000 即可看到 "Hello, World!"
2. 使用 FastAPI（更实用的例子）
创建 main.py：
from fastapi import FastAPI
app = FastAPI()
@app.get("/")
async def root():
return {"message": "Hello World"}
@app.get("/items/{item_id}")
async def read_item(item_id: int):
return {"item_id": item_id}
运行：
uvicorn main:app
常用命令行参数
基础参数
# 指定主机和端口
uvicorn app:app –host 0.0.0.0 –port 8080
# 开发模式（自动重载）
uvicorn app:app –reload
# 指定日志级别
uvicorn app:app –log-level debug
生产环境参数
# 多进程运行（workers 数量通常设为 CPU 核心数）
uvicorn app:app –workers 4
# 设置访问日志格式
uvicorn app:app –access-log
# 禁用访问日志（提升性能）
uvicorn app:app –no-access-log
你的项目中的用法
根据你选中的 Makefile 内容：
poetry run uvicorn app:ap
这表示：
- 使用 Poetry 环境运行
- 启动 app.py 文件中的 ap 对象（可能是 app 的笔误？）
配置文件方式
除了命令行参数，也可以使用配置文件 uvicorn_config.py：
import uvicorn
if __name__ == "__main__":
uvicorn.run(
"app:app",
host="0.0.0.0",
port=8000,
reload=True,
log_level="info",
access_log=True
)
运行：
python uvicorn_config.py
生命周期事件
FastAPI 中可以使用生命周期事件：
from fastapi import FastAPI
app = FastAPI()
@app.on_event("startup")
async def startup_event():
"""应用启动时执行"""
print("应用正在启动…")
# 初始化数据库连接、缓存等
@app.on_event("shutdown")
async def shutdown_event():
"""应用关闭时执行"""
print("应用正在关闭…")
# 清理资源、关闭连接等
@app.get("/")
async def root():
return {"message": "Hello"}
部署到生产环境
方式 1: 使用 Uvicorn + 进程管理器
# 使用 systemd
[Unit]
Description=Uvicorn instance
After=network.target
[Service]
User=www-data
WorkingDirectory=/path/to/project
ExecStart=/path/to/venv/bin/uvicorn app:app –workers 4 –host 0.0.0.0 –port 8000
[Install]
WantedBy=multi-user.target
方式 2: 使用 Gunicorn + Uvicorn Worker
pip install gunicorn
gunicorn app:app \\
–workers 4 \\
–worker-class uvicorn.workers.UvicornWorker \\
–bind 0.0.0.0:8000
方式 3: Docker 部署
FROM python:3.11-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY . .
CMD ["uvicorn", "app:app", "–host", "0.0.0.0", "–port", "8000"]
性能优化建议
常见问题
Q: 如何查看 Uvicorn 版本？
uvicorn –version
Q: 如何绑定多个地址？
Uvicorn 只能绑定一个地址，需要在前面加反向代理。
Q: 自动重载不工作？
确保使用了 –reload 参数，且修改的文件在工作目录内。
Q: 如何处理静态文件？
FastAPI 示例：
from fastapi.staticfiles import StaticFiles
app.mount("/static", StaticFiles(directory="static"), name="static")
下一步学习
参考资源
- 官方文档: https://www.uvicorn.org/
- FastAPI 文档: https://fastapi.tiangolo.com/
- ASGI 规范: https://asgi.readthedocs.io/
希望这个教程能帮助你快速上手 Uvicorn！如果你在使用项目时遇到具体问题，随时可以问我。
