HoRain云--FastAPI 从入门到生产：路由、依赖注入、异步与部署

1. 为什么选择 FastAPI

FastAPI 基于 Starlette 和 Pydantic，支持异步、自动生成 OpenAPI 文档、类型提示驱动开发。性能接近 Node.js 和 Go，开发效率极高。

安装：

bash

复制

下载

pip install fastapi uvicorn[standard]

2. 第一个接口

python

复制

下载

from fastapi import FastAPI app = FastAPI() @app.get("/") def read_root(): return {"message": "Hello FastAPI"}

启动：

bash

复制

下载

uvicorn main:app --reload

访问http://127.0.0.1:8000/docs即可看到 Swagger 文档。

3. 路径参数与查询参数

python

复制

下载

@app.get("/users/{user_id}") def get_user(user_id: int, q: str | None = None): return {"user_id": user_id, "q": q}

类型提示会自动校验，传错类型返回 422。

4. Pydantic 模型

python

复制

下载

from pydantic import BaseModel, EmailStr class UserCreate(BaseModel): name: str email: EmailStr age: int @app.post("/users") def create_user(user: UserCreate): return user

Pydantic v2 性能大幅提升，支持严格模式和自定义校验。

5. 依赖注入

python

复制

下载

from fastapi import Depends def get_db(): db = SessionLocal() try: yield db finally: db.close() @app.get("/items") def read_items(db=Depends(get_db)): return db.query(Item).all()

依赖注入可以复用数据库连接、认证逻辑、配置等。

6. 异步接口

python

复制

下载

@app.get("/async") async def async_endpoint(): await asyncio.sleep(1) return {"status": "ok"}

I/O 密集场景使用async def，CPU 密集仍用普通def，FastAPI 会自动放入线程池。

7. 数据库集成

推荐 SQLAlchemy 2.0 + Alembic：

python

复制

下载

from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column class Base(DeclarativeBase): pass class User(Base): __tablename__ = "users" id: Mapped[int] = mapped_column(primary_key=True) name: Mapped[str]

8. 认证与权限

使用 OAuth2 + JWT：

python

复制

下载

from fastapi.security import OAuth2PasswordBearer oauth2_scheme = OAuth2PasswordBearer(tokenUrl="token") @app.get("/me") def read_me(token: str = Depends(oauth2_scheme)): return decode_token(token)

9. 部署

Dockerfile：

dockerfile

复制

下载

FROM python:3.12-slim WORKDIR /app COPY requirements.txt . RUN pip install -r requirements.txt COPY . . CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

生产建议使用 Gunicorn + Uvicorn Worker：

bash

复制

下载

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

10. 常见坑

• 在 async 函数中使用阻塞库会拖慢整个事件循环。

• Pydantic v1 和 v2 语法不兼容。

• 数据库会话未正确关闭会导致连接泄漏。

• 生产环境不要开启--reload。

11. 总结

FastAPI 适合快速构建高性能 API。掌握 Pydantic、依赖注入和异步后，可以轻松应对中大型项目。