跳到主要内容

FastAPI 笔记

原 旧稿 + 旧稿 的合并重新整理版本,精炼为 4 章节:速查总览 / 常用模式速查表 / 实战代码片段(指向 example demo)/ 常见坑 + 官方文档链接。旧稿目录已清理,当前以本文为准。 演示代码统一放在 example/python/fastapi/,本笔记通过 git 远程链接引用。

1. 速查总览​

1.1 是什么​

FastAPI 是基于 Starlette(Web 框架)+ Pydantic(数据校验)+ Uvicorn(ASGI 服务器)的现代 Python Web 框架,主打:

  • 高性能(接近 Node.js / Go)
  • 类型驱动:编辑器自动补全、参数类型检查
  • 自动生成 Swagger UI(/docs)和 ReDoc(/redoc)

1.2 安装​

# 用 uv(推荐)
uv add fastapi "uvicorn[standard]"

# 鉴权 + 密码哈希(用得到就装)
uv add "python-jose[cryptography]" "passlib[bcrypt]" "python-multipart"

# 测试
uv add --dev pytest httpx

1.3 最小 hello world​

from fastapi import FastAPI

app = FastAPI()


@app.get("/")
def root():
return {"hello": "world"}

启动:

uv run uvicorn main:app --reload
# 访问 http://127.0.0.1:8000/
# Swagger: http://127.0.0.1:8000/docs

完整 hello world(带路径/查询/请求体识别):hello_world.py


2. 常用模式速查表​

# ===== 路由装饰器 =====
@app.get("/") # GET
@app.post("/items") # POST
@app.put("/items/{id}") # PUT
@app.delete("/items/{id}") # DELETE
@app.patch("/items/{id}") # PATCH
@app.get("/items", response_model=Item) # 响应模型(自动序列化 + 过滤字段)
@app.post("/items", status_code=201) # 默认状态码

# ===== 参数识别规则(核心)=====
@app.get("/items/{item_id}")
def read(item_id: int, q: str = ""): # 路径里的 int → 路径参数;其他单类型 → 查询
...

class Item(BaseModel):
name: str
price: float

@app.post("/items")
def create(item: Item): # Pydantic 模型 → 请求体
...

# ===== 数据校验 =====
item_id: int = Path(..., gt=0, le=1000) # 路径参数校验
q: str = Query(None, min_length=1, max_length=50, pattern="^[a-z]+$") # 查询参数校验
item: Item = Body(...) # 显式声明请求体
importance: int = Body(..., ge=1, le=5, embed=True) # 单值 Body 强制包成 {"importance": ...}
class Item(BaseModel):
name: str = Field(..., min_length=1, max_length=100)
price: float = Field(..., gt=0) # Pydantic v2 字段校验

# ===== 依赖注入 =====
def get_db():
db = ...
try:
yield db # yield 依赖用于资源清理(DB / 文件 / session)
finally:
db.close()

@app.get("/items")
def read(db = Depends(get_db)): # Depends(fn) 把 fn 返回值注入
...

# ===== 错误与异常 =====
raise HTTPException(404, "not found", headers={"X-Err": "x"}) # 标准错误
@app.exception_handler(MyError) # 自定义异常处理

# ===== 请求上下文 =====
from fastapi import Request, Cookie, Header, Form, File, UploadFile
request: Request # 拿原始请求(IP、headers、url)
session_id: str = Cookie(None) # Cookie 参数
x_token: str = Header(...) # Header 参数
username: str = Form(...) # application/x-www-form-urlencoded
file: UploadFile = File(...) # multipart/form-data 文件

# ===== 响应 =====
@app.get("/x", response_model=Item) # 自动按 Item 序列化
@app.post("/x", status_code=201) # 自定义状态码
from fastapi.responses import JSONResponse, FileResponse, RedirectResponse, HTMLResponse

# ===== 中间件 / CORS =====
from fastapi.middleware.cors import CORSMiddleware
app.add_middleware(CORSMiddleware, allow_origins=["http://localhost:3000"], allow_credentials=True, allow_methods=["*"], allow_headers=["*"])
app.add_middleware(GZipMiddleware, minimum_size=1000)

@app.middleware("http") # 自定义函数式中间件
async def add_time(request, call_next):
...

# ===== 后台任务 =====
from fastapi import BackgroundTasks
@app.post("/send")
def send(bg: BackgroundTasks):
bg.add_task(send_email, "user@example.com")
return {"queued": True}

# ===== 鉴权 =====
from fastapi.security import OAuth2PasswordBearer
oauth2_scheme = OAuth2PasswordBearer(tokenUrl="token")
async def get_user(token: str = Depends(oauth2_scheme)): ...

# ===== 测试 =====
from fastapi.testclient import TestClient
client = TestClient(app)
client.get("/") / client.post("/x", json={...}) # in-process 测,免启服务

3. 实战代码片段​

以下 demo 全部放在 example/python/fastapi/,可独立运行:

Demo涵盖链接
hello_world.py路径/查询/请求体识别规则查看
params_demo.pyPath/Query/Body 校验 + 多请求体 + Field查看
depends_and_exception.pyDepends 基础、yield 依赖、HTTPException、自定义 handler查看
middleware_cors.py自定义 HTTP 中间件、CORS、GZip查看
jwt_auth.pyOAuth2PasswordBearer + JWT 签发/校验 + bcrypt 哈希查看
test_client.pyTestClient 单元测试(含 pytest)查看
full_app/main.py完整小型 API(注册/登录/items CRUD + curl 测试用例)查看

3.1 跑起来看效果​

# 跑最小 demo
uv run uvicorn example.python.fastapi.hello_world:app --reload

# 跑完整 API(带鉴权)
uv run uvicorn example.python.fastapi.full_app.main:app --reload

# 跑测试
uv run pytest example/python/fastapi/test_client.py -v

3.2 完整 API 的 curl 流程​

# 1. 注册
curl -X POST http://127.0.0.1:8000/register \
-H "Content-Type: application/json" \
-d '{"username":"alice","full_name":"Alice","password":"alice123"}'

# 2. 登录拿 token
TOKEN=$(curl -s -X POST http://127.0.0.1:8000/token \
-d "username=alice&password=alice123" \
| python -c "import sys,json;print(json.load(sys.stdin)['access_token'])")

# 3. 创建 item(带 token)
curl -X POST http://127.0.0.1:8000/items \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"name":"book","price":12.5}'

# 4. 列出
curl http://127.0.0.1:8000/items

4. 常见坑 + 官方文档链接​

4.1 必传 vs 可选字段(Pydantic v2)​

class Auth(BaseModel):
username: str
password: str | None # 类型允许 None,但客户端必须传 key(值可为 null)
class Auth(BaseModel):
username: str
password: str | None = None # 有默认值,可不传
写法是否必须传 key
password: str | None✅ 必须传,传 null 也算
password: str | None = None❌ 可不传,默认 None

同样规则适用于 FastAPI 的 Query、Body、Header 等。

4.2 同步 vs 异步路由​

@app.get("/sync")
def sync_route(): # 同步函数:FastAPI 放线程池跑,不阻塞事件循环
time.sleep(1)
return {"ok": True}

@app.get("/async")
async def async_route(): # 异步函数:直接在事件循环跑
await asyncio.sleep(1)
return {"ok": True}
  • IO 密集用 async def + 异步客户端(httpx、asyncpg、aiomysql)
  • CPU 密集或调阻塞库(requests、psycopg2、time.sleep)用 def(自动线程池)
  • ❌ 不要在 async def 里调阻塞 IO,会卡死整个事件循环

4.3 Depends 嵌套与性能​

  • 每层 Depends 都会在每次请求里重新调用
  • 同请求内多次用同一个依赖,默认会缓存结果(use_cache=True)
  • 想要强一致:传 use_cache=False
  • 想要真缓存:自己用 functools.lru_cache 或 Redis

4.4 Pydantic v2 常见迁移注意​

  • class Config: + orm_mode = True → model_config = ConfigDict(from_attributes=True)
  • @validator("x") → @field_validator("x")
  • @root_validator → @model_validator(mode="before"/"after")
  • .dict() → .model_dump()
  • .json() → .model_dump_json()

4.5 CORS 预检失败​

开发时典型报错:No 'Access-Control-Allow-Origin' header is present

app.add_middleware(
CORSMiddleware,
allow_origins=["http://localhost:3000"], # 生产环境写具体域名,不要用 ["*"]
allow_credentials=True, # 想带 cookie 时必须 True
allow_methods=["*"],
allow_headers=["*"],
)

⚠️ allow_origins=["*"] + allow_credentials=True 是非法组合(浏览器拒绝),二选一。

4.6 uvicorn --reload 与多 worker 不兼容​

# 开发
uvicorn main:app --reload

# 生产:多 worker(不要带 --reload)
uvicorn main:app --host 0.0.0.0 --workers 4

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

4.7 启动后 422​

请求体字段名/类型不对,FastAPI 自动返回 422 + 详细错误列表。打开 /docs 在 Swagger UI 里直接调,能看到正确格式。

4.8 Swagger 看不到新接口​

/docs 是动态生成的,不需要重启;--reload 时改了代码自动生效。

4.9 官方文档链接​