FastAPI

ASGI 框架 FastAPI：路由与 Pydantic 校验、Depends、OpenAPI；应用对象与常用 API 速查；链回 uvicorn 与官方手册。

FastAPI 构建在 Starlette 之上，实现 ASGI 应用：用类型注解 + Pydantic 做请求校验，并自动生成 OpenAPI。监听端口、进程模型由 ASGI 服务器完成，常用 uvicorn；向外发 HTTP 可与 httpx 配合。WSGI/ASGI 心智见 Web 服务与常用框架。

pip install fastapi uvicorn

何时用 FastAPI

场景	建议
REST/JSON API + 要类型校验与交互文档	FastAPI 默认 `/docs`、`/redoc`
需要 WebSocket、长连接、流式响应	ASGI 栈（FastAPI / Starlette）
团队已深度绑定 Flask 同步、中间件生态	可继续 Flask + gunicorn；或渐进迁移
CPU 密集占满多核	API 层仍单进程事件循环；重算放任务队列或 multiprocessing

应用 vs 服务器：FastAPI() 只定义 app（可调用 ASGI 对象）；uvicorn main:app 负责套接字与 worker。二者勿混为一谈。

@app.get 从哪来？ app 是 FastAPI 实例；.get / .post 等是路由注册方法，返回装饰器，把下方函数登记为对应 HTTP 方法与路径的处理函数。

模块成员总览

`FastAPI(...)` 构造参数

名称	说明
`title` / `version` / `description`	写入 OpenAPI，出现在 `/docs`、`/redoc`
`docs_url` / `redoc_url` / `openapi_url`	文档路径；设为 `None` 关闭对应端点
`redirect_slashes`	路径尾 `/` 不一致时是否 307 重定向（默认 `True`）

`app` 实例方法

名称	说明
`get` / `post` / `put` / `delete` / `patch` / `head` / `options`	按 HTTP 方法注册路由；返回装饰器
`websocket(path)`	WebSocket 端点；处理函数一般为 `async def`
`include_router(router, prefix=, tags=)`	挂载 `APIRouter`，拆分大项目
`mount(path, app)`	子路径挂载另一 ASGI 应用
`middleware("http")(callable)`	HTTP 中间件；后注册者先执行（外层）

从 `fastapi` 导入的常用工具（非 `app` 方法）

名称	说明
`Query` / `Body` / `Path` / `Header` / `Cookie`	声明参数来源与约束，进入 OpenAPI
`Depends(callable)`	依赖注入
`HTTPException`	主动返回 4xx/5xx
`APIRouter`	子路由表，供 `include_router` 使用

类型注解与上述工具共同驱动校验与 schema 生成。

创建应用与最小路由

# main.py
from fastapi import FastAPI

app = FastAPI(title="Demo")


@app.get("/health")
def health():
    return {"status": "ok"}

uvicorn main:app --reload --host 127.0.0.1 --port 8000

main:app：模块 main、变量 app；启动参数见 uvicorn。
--reload：仅开发；生产关闭。

浏览器访问 http://127.0.0.1:8000/docs 为 Swagger UI。

路由：路径参数、查询字符串、请求体

from typing import Annotated

from fastapi import FastAPI, Query
from pydantic import BaseModel, Field

app = FastAPI()

class Item(BaseModel):
    name: str = Field(min_length=1)
    price: float = Field(gt=0)

@app.get("/items/{item_id}")
def read_item(
    item_id: int,
    q: Annotated[str | None, Query(max_length=50)] = None,
):
    return {"item_id": item_id, "q": q}

@app.post("/items")
def create_item(item: Item):
    return {"received": item.model_dump()}

参数来源	写法	说明
路径	`{item_id}` 与形参同名同类型	不匹配自动 422
查询	可选形参 + `Query(...)`	`Annotated` 可加长度、默认值说明
JSON Body	Pydantic `BaseModel`	字段校验由 `Field` 等定义

依赖注入：`Depends`

把分页、鉴权、DB 会话等横切逻辑抽成函数，路由只声明依赖。

from typing import Annotated

from fastapi import Depends, FastAPI

app = FastAPI()

def pagination(skip: int = 0, limit: int = 20) -> tuple[int, int]:
    return skip, limit

@app.get("/feed")
def feed(page: Annotated[tuple[int, int], Depends(pagination)]):
    skip, limit = page
    return {"skip": skip, "limit": limit}

依赖可以是 async def，与路由 async/sync 一起由框架调度。
依赖可嵌套 Depends；复杂生命周期见官方 Dependencies 章节。

`async def` 与阻塞代码

路由类型	适用	注意
`async def`	`await` 异步 I/O（`httpx`、`asyncio`）	体内勿长时间阻塞（`time.sleep`、同步 `requests`、重 CPU）
`def`	阻塞库、少量同步 IO	在线程池执行，勿大规模塞满线程池

向外 HTTP 在 async 路由中优先 httpx.AsyncClient（见 server-sdk）。

OpenAPI 与文档端点

路由上的类型、Field、Query 等进入 schema。默认端点：

路径	内容
`/docs`	Swagger UI
`/redoc`	ReDoc
`/openapi.json`	原始 OpenAPI JSON

生产若不想暴露文档，构造时设 docs_url=None 等，或由网关限制访问。

模块	关系
`uvicorn`	常用 ASGI 服务器，运行 `app`
`starlette`	FastAPI 底层路由、中间件、请求/响应
`pydantic`	模型校验与序列化
`httpx`	异步 HTTP 客户端
`asyncio`	事件循环；勿在 async 路由里阻塞循环

易错点（排错速记）

async 路由里 time.sleep / 同步 HTTP：卡住整个服务；改异步库或 def 路由。
把纯 WSGI Flask app 直接交给 uvicorn：需 ASGI 或适配层。
生产仍暴露 /docs：信息泄露；关闭 URL 或加鉴权。
redirect_slashes 与前端路径不一致：多余 307 或重复路由。
忘记 Depends 只写在注解里：普通默认参数不会走依赖注入。

资料：FastAPI 中文文档 · Starlette · uvicorn