新项目首选fastapi：原生异步、自动openapi文档、强类型校验；已有flask项目可先用flask-restx过渡；务必使用response_model声明响应结构，路径参数须用path(...)标注，开发时uvicorn需加--reload等参数。
用 FastAPI 还是 Flask-RESTful？看这三点就定下来
FastAPI 是当前 Python 开发 RESTful API 的事实首选，除非你正在维护一个老 Flask 项目且不打算升级。Flask-RESTful 已基本停止更新，官方文档都标记为“legacy”，而 FastAPI 原生支持异步、自动 OpenAPI 文档、强类型校验——这些不是“锦上添花”，而是省掉大量手动写验证逻辑和文档同步的刚需。
常见错误现象：TypeError: object of type 'dict' is not JSON serializable 在 Flask-RESTful 里常因返回非标准类型（如 datetime）触发；FastAPI 遇到同样情况会直接报错并提示具体字段，定位更快。
- 新项目无脑选
FastAPI：开发效率高、出错反馈准、异步支持开箱即用 - 已有 Flask 项目想渐进改造：先用
flask-restx（比 Flask-RESTful 更现代），再逐步迁移到 FastAPI - 团队对 asyncio 完全没经验且接口全是同步 DB 查询：可暂缓用 FastAPI 的
async def，改用普通def路由，它依然能跑
FastAPI 路由定义时，response_model 不是可选项
很多人只写 @app.get("/users") 就返回 dict，结果前端收到字段名拼错、多出调试字段、时间格式混乱——根本原因是没声明响应结构。FastAPI 的 response_model 不只是生成文档，它真会做序列化裁剪和类型转换。
使用场景：返回用户列表时，数据库模型含 password_hash、created_at（datetime 类型），但 API 只该暴露 id、name、joined_date（ISO 格式字符串）。
立即学习“Python免费学习笔记（深入）”；
- 必须用 Pydantic 模型定义
response_model，不能用 dict 或 dataclass（除非显式配置pydantic_config） -
datetime字段在模型中声明为datetime类型，FastAPI 自动转成 ISO 格式字符串；若声明为str，它反而会拒绝接收datetime实例 - 漏写
response_model导致返回数据包含内部字段（比如 SQLAlchemy 的_sa_instance_state），这是线上最常被前端吐槽的“字段污染”问题
from pydantic import BaseModel from datetime import datetime <p>class UserOut(BaseModel): id: int name: str joined_date: datetime # 自动转成 "2024-05-20T08:30:00"
路径参数、查询参数、请求体混用时，顺序和类型注解决定行为
FastAPI 不靠装饰器参数顺序或关键字来区分参数来源，而是完全依赖函数签名里的类型注解 + 特殊类（如 Path、Query、Body）。写错一个注解，参数就进错地方，且可能静默失败。
常见错误现象：user_id 明明是 URL 路径参数，却在函数里写成 def read_user(user_id: int) ——FastAPI 默认把它当查询参数，导致 /users/123 返回 404，而 /users?user_id=123 才生效。
- 路径参数必须用
Path(...)显式标注（...表示必填），哪怕类型已写int - 多个查询参数想设默认值？别写
q: str = None，改用q: str = Query(None)，否则 FastAPI 无法识别它是查询参数 - POST 请求带 JSON body 又要收查询参数？函数签名顺序无所谓，但 body 参数必须是最后一个，且类型不能是基础类型（如
str、int），否则 FastAPI 会把它当查询参数解析
本地调试时，别信 uvicorn.run() 的默认配置
直接写 uvicorn.run("main:app") 启动，代码改了不会热重载，端口冲突也不报具体错，连 Ctrl+C 有时都杀不干净进程——这不是 FastAPI 的问题，是 Uvicorn 默认配置太“生产向”。
性能影响：默认单 worker，压测时吞吐卡在 1k QPS 下；开发期却要反复手动重启，实际拖慢的是人效。
- 开发务必加
--reload和--reload-dir（指定监控目录，避免扫描整个虚拟环境） - 端口被占？加
--port 8001，别等报错后去查哪个进程占着 8000 - 想看每条请求的耗时和状态码？加
--log-level debug，比自己写中间件快得多 - 命令示例：
uvicorn main:app --reload --reload-dir ./app --port 8001 --log-level debug
复杂点在于：reload 机制依赖文件系统事件，在 Docker for Mac 或某些 NFS 卷上可能失效，这时得换 --reload-delay 或改用 watchfiles。但那是另一层问题了。
