来源：网络
如果你还在用 Flask 写 API 接口，那你可能已经落后了。
2026 年的 Python Web 开发圈，FastAPI 已经成了事实上的主流选择——GitHub Star 突破 80k，增速超越 Flask 和 Django[reference:0]。微软、Netflix、滴滴等大厂都在用[reference:1]。
今天我就带你从零开始，30 分钟内搭建一套规范的 RESTful API 服务，包含：
-
✅ 自动生成 Swagger 接口文档 -
✅ 统一返回数据结构（code + msg + data） -
✅ 自动参数类型校验 -
✅ 全局异常处理
全部代码可直接复制运行，新手也能轻松上手。
一、为什么是 FastAPI？
FastAPI 凭什么能火成这样？三个核心优势[reference:2]：
|
|
|
|---|---|
|
|
|
|
|
/docs 自动生成 Swagger 文档，无需额外配置[reference:4] |
|
|
|
一句话总结：FastAPI 让你写更少的代码，做更多的事。
二、环境准备（3 分钟）
第一步：安装 FastAPI 和 Uvicorn
打开终端，执行以下命令[reference:6]：
pip install fastapi uvicorn[standard]第二步：创建项目文件
新建一个 main.py 文件，接下来的所有代码都写在这个文件里。
三、完整代码实现（可直接复制）
3.1 初始化项目pythonfrom fastapi import FastAPI, HTTPExceptionfrom pydantic import BaseModelfrom typing import Optionalimport uvicorn# 创建 FastAPI 实例app = FastAPI(title=”我的API服务”,version=”1.0.0”,description=”一个规范的 FastAPI 示例项目”)3.2 定义统一返回模型企业级 API 通常要求统一的返回格式，方便前端对接：python# 统一返回模型class ResponseModel(BaseModel):code: int# 状态码：200成功，其他失败msg: str# 提示信息data: Optional[dict] = None# 返回数据# 辅助函数：快速返回成功def success(data: dict = None, msg: str = ”请求成功”) -> dict:return ResponseModel(code=200, msg=msg, data=data).dict()# 辅助函数：快速返回失败def error(msg: str = ”请求失败”, code: int = 400) -> dict:return ResponseModel(code=code, msg=msg, data=None).dict()3.3 定义请求体模型（参数校验）FastAPI 会自动根据 Pydantic 模型校验请求参数：python# 用户注册请求体class UserRegisterRequest(BaseModel):username: str# 必填password: str# 必填email: Optional[str] = None# 选填# 自定义校验：用户名长度至少3位@validator('username')def username_length(cls, v):if len(v) < 3:raise ValueError('用户名长度不能少于3位')return v3.4 编写接口（RESTful 风格）python# ---------- GET 接口 ----------def root():”””根路径测试接口”””return success(data={”message”: ”Hello FastAPI!”})# ---------- GET 接口（带路径参数） ----------def get_user(user_id: int):”””根据用户ID获取用户信息”””# 模拟数据库查询if user_id == 1:return success(data={”id”: 1, ”name”: ”张三”, ”age”: 25})else:return error(msg=f”用户 {user_id} 不存在”, code=404)# ---------- POST 接口（带请求体） ----------def register_user(req: UserRegisterRequest):”””用户注册接口”””# 模拟注册逻辑return success(data={”username”: req.username, ”email”: req.email},msg=f”用户 {req.username} 注册成功”)3.5 全局异常处理防止程序崩溃，统一返回友好的错误信息：pythonfrom fastapi.exceptions import RequestValidationErrorfrom starlette.exceptions import HTTPException as StarletteHTTPException# 处理 HTTP 异常async def http_exception_handler(request, exc):return error(msg=str(exc.detail), code=exc.status_code)# 处理参数校验异常async def validation_exception_handler(request, exc):errors = [{”field”: e[”loc”][-1], ”msg”: e[”msg”]} for e in exc.errors()]return error(msg=f”参数校验失败: {errors}”, code=422)3.6 启动服务在文件末尾添加：pythonif __name__ == ”__main__”:uvicorn.run(app, host=”0.0.0.0”, port=8000)
四、运行与测试
启动服务：bashpython main.py
访问接口文档（不需要额外配置，FastAPI 自动生成）–13：
-
Swagger UI（交互式调试）：http://127.0.0.1:8000/docs
-
ReDoc（纯文档展示）：http://127.0.0.1:8000/redoc
测试接口：
用浏览器或 Postman 访问 http://127.0.0.1:8000/api/v1/user/1，你会看到：
{"code": 200,"msg": "请求成功","data": {"id": 1,"name": "张三","age": 25}}
五、进阶扩展
上面的 Demo 已经可以跑起来了。如果要用于生产环境，还可以继续扩展–13：
-
JWT 鉴权：给接口加上 Token 认证
-
跨域配置：解决前后端分离的跨域问题
-
分层架构：把路由、业务逻辑、数据库操作拆分到不同文件
-
数据库集成：接入 SQLAlchemy 或 Tortoise-ORM
在最后
FastAPI 上手简单、性能优异，兼顾开发效率和运行效率–13。对比传统的 Flask，它的类型校验和自动文档两大特性，能极大减少前后端联调成本–13。
📎 附录：完整源码（可直接运行）
pythonfrom fastapi import FastAPI, HTTPExceptionfrom pydantic import BaseModel, validatorfrom typing import Optionalimport uvicorn# ---------- 1. 初始化 ----------app = FastAPI(title="我的API服务", version="1.0.0", description="一个规范的 FastAPI 示例项目")# ---------- 2. 统一返回模型 ----------class ResponseModel(BaseModel):code:intmsg:strdata: Optional[dict]=Nonedef success(data:dict=None, msg:str="请求成功")->dict:return ResponseModel(code=200, msg=msg, data=data).dict()def error(msg:str="请求失败", code:int=400)->dict:return ResponseModel(code=code, msg=msg, data=None).dict()# ---------- 3. 请求体模型 ----------class UserRegisterRequest(BaseModel):username:strpassword:stremail: Optional[str]=Nonedef username_length(cls, v):if len(v)<3:raise ValueError('用户名长度不能少于3位')return v# ---------- 4. 接口 ----------def root():return success(data={"message":"Hello FastAPI!"})def get_user(user_id:int):if user_id ==1:return success(data={"id":1,"name":"张三","age":25})else:return error(msg=f"用户 {user_id} 不存在", code=404)def register_user(req: UserRegisterRequest):return success(data={"username" req.username,"email": req.email},msg=f"用户 {req.username} 注册成功")# ---------- 5. 启动 ----------if __name__ =="__main__":uvicorn.run(app, host="0.0.0.0", port=8000)本文所有代码均在 Python 3.9+ 环境下测试通过。
