FastAPI 无需先理解异步等概念，写函数即可运行接口；类型注解自动实现校验、文档和错误提示；仅需 fastapi 和 uvicorn 两个包，三行代码即可启动带 Swagger 文档的最小服务。
直接上手就行，不需要先搞懂异步、ASGI、Pydantic这些词——FastAPI 的设计就是让你写完函数就能跑通接口，类型注解写对了，校验、文档、422 错误提示全都有。
安装和启动一个能跑的最小服务
你只需要两个包：fastapi 和 uvicorn。前者是框架本身，后者是推荐的 ASGI 服务器：
pip install fastapi uvicorn
新建 main.py，写三行路由就足够测试：
from fastapi import FastAPI
app = FastAPI()
<p>@app.get("/health")
def health_check():
return {"status": "ok"}终端里执行：
立即学习“Python免费学习笔记（深入）”；
uvicorn main:app --reload
服务起来后，访问 http://127.0.0.1:8000/health 就能拿到 JSON；访问 http://127.0.0.1:8000/docs 就能看到自动生成的 Swagger UI 文档。没配任何东西，文档已就位。
路径参数、查询参数、请求体怎么写才不报错
FastAPI 靠参数类型自动判断来源：路径里的变量必须声明类型（比如 item_id: int），否则会报 422 Unprocessable Entity；查询参数默认可选，但加了类型后仍需显式设默认值（q: str = None）；请求体必须用 Pydantic 模型封装，不能直接写 dict 或 str。
常见错误现象：
- 前端传
/items/abc，后端报value is not a valid integer—— 这不是 bug，是校验生效了 - POST 一个 JSON，但没定义
BaseModel，会提示body is required - 查询参数写了
q: str但没给默认值，调用时漏传q就直接 422
正确写法示例：
from pydantic import BaseModel
<p>class Item(BaseModel):
name: str
price: float
is_offer: bool = False</p><p>@app.get("/items/{item_id}")
def read_item(item_id: int, q: str = None): # 路径参数强类型，查询参数带默认值
return {"item_id": item_id, "q": q}</p><p>@app.post("/items")
def create_item(item: Item): # 请求体必须是 Pydantic 模型
return item为什么 response_model 不是可选项，而是关键开关
response_model 参数控制两件事：序列化字段过滤 + 返回体结构校验。不加它，返回的是原始 Python 对象（比如 datetime 会直接抛 TypeError）；加了它，Pydantic 会把对象转成 JSON 兼容格式，并剔除模型里没声明的字段。
典型场景：
- 数据库查出的 ORM 对象有
_sa_instance_state属性，不加response_model会直接 500 - 你想隐藏敏感字段（如
password_hash），只在模型里不声明它就行 - 返回列表时必须写
List[Item]，否则文档里显示不出数组结构
示例：
@app.get("/items", response_model=list[Item]) # Python 3.11+ 支持原生 list[Item]
async def list_items():
return [{"name": "foo", "price": 1.2, "is_offer": True}]开发阶段最该关掉的默认行为
FastAPI 默认开启 --reload（热重载）和详细错误页面，这在本地很爽，但上线前必须确认两点：
- 生产启动命令里不能带
--reload，否则uvicorn会拒绝启动（报Reload not available in production） - 不要依赖开发时看到的 traceback 页面——线上应关闭
debug=True，改用日志捕获异常
更关键的是：别让 response_model 和实际返回值类型不一致。比如函数返回 None，但 response_model=Item，就会触发 ValidationError，而且错误信息可能藏在日志里，前端只看到 500。
这类类型不匹配问题，在 FastAPI 里不会在启动时报错，而是在第一次请求时才暴露——最容易被忽略，也最难调试。
