Python怎么开发RESTful API_Flask-RESTful或FastAPI实战-Python教程-PHP中文网

新项目首选fastapi：原生异步、自动openapi文档、强类型校验；已有flask项目可先用flask-restx过渡；务必使用response_model声明响应结构，路径参数须用path(...)标注，开发时uvicorn需加--reload等参数。

python怎么开发restful api_flask-restful或fastapi实战

用 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 格式字符串）。

必须用 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"</p>

路径参数、查询参数、请求体混用时，顺序和类型注解决定行为

FastAPI 不靠装饰器参数顺序或关键字来区分参数来源，而是完全依赖函数签名里的类型注解 + 特殊类（如 Path、Query、Body）。写错一个注解，参数就进错地方，且可能静默失败。

python全能编程助手

SkillSub Pro - Python 题解与代码注释双功能技能功能概述SkillSub Pro - Python 题解与代码注释双功能技能是一项面向实际任务的技能，主要用于SkillSub Pro 是一个 Python 题解生成与代码注释的双功能合体技能，专为学生、算法学习者和开发者设计；✅ 一个技能，两种用途：；核心要点📝 题解模式：输入题目/题号，自动生成完整 Python 题解（含详细注释、解题思路、复杂度分析）；💬 注释模式：输入 Python 代码，自动添加详细中。它将相关步骤、

下载

常见错误现象：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。但那是另一层问题了。