Python怎么开发RESTful API_Flask-RESTful或FastAPI实战

新项目首选 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。但那是另一层问题了。