FastAPI 入门指南：用 Python 极速构建 APIPython

写 Web 接口，Flask 轻量但得自己拼很多；Django 全家桶又偏重。FastAPI 出自 2018 年，凭借异步支持、自动文档、类型校验三大杀器，迅速成为 Python API 开发的首选。本文从零带你跑通第一个 FastAPI 服务。

一、环境准备

pip install "fastapi[standard]"

[standard] 会一并装上 uvicorn（ASGI 服务器）、pydantic 等依赖。要求 Python 3.8+，推荐 3.10+。

二、最小可运行示例

创建 main.py：

from fastapi import FastAPI

app = FastAPI()

@app.get("/")
def read_root():
    return {"msg": "Hello FastAPI"}

@app.get("/items/{item_id}")
def read_item(item_id: int, q: str = None):
    return {"item_id": item_id, "q": q}

启动：

uvicorn main:app --reload

访问 http://127.0.0.1:8000/ 返回 JSON；访问 http://127.0.0.1:8000/docs 即可看到自动生成的交互式 Swagger 文档——这是 FastAPI 最让人惊艳的特性之一。

三、核心概念

• 路径操作装饰器：@app.get / @app.post 等映射 HTTP 方法。
• 类型注解即校验：函数参数写 item_id: int，FastAPI 自动做类型转换与校验，非法请求返回 422。
• Pydantic 模型：用 BaseModel 定义请求体，自动校验 + 生成文档。

四、进阶用法：请求体与校验

定义注册接口，演示 Pydantic 模型：

from pydantic import BaseModel, EmailStr

class User(BaseModel):
    name: str
    email: EmailStr
    age: int = 18   # 默认值

@app.post("/users")
def create_user(u: User):
    return {"created": u.name, "email": u.email}

EmailStr 需 pip install email-validator。传入非法邮箱会被自动拦截并返回清晰错误。

五、实战场景：带查询过滤的列表接口

模拟一个分页查询用户列表：

users = [{"id": i, "name": f"user{i}"} for i in range(1, 101)]

@app.get("/users")
def list_users(skip: int = 0, limit: int = 10):
    return users[skip : skip + limit]

访问 /users?skip=10&limit=5 即可翻页。真实项目中把 users 换成数据库查询即可。

六、常见坑 / 报错

1. ModuleNotFoundError: No module named 'uvicorn'
只装了 fastapi 没装服务器。解决：pip install "fastapi[standard]" 或直接 pip install uvicorn。

2. 改了代码不生效
忘了加 --reload，或用了错误的启动命令。正确：uvicorn main:app --reload，其中 main 是文件名（不含 .py），app 是实例名。

3. 422 Unprocessable Entity
请求体字段类型/必填不符。检查 Pydantic 模型字段是否必填、类型是否匹配（如字符串传成数字）。

七、总结与下一步

FastAPI 用类型注解把“写接口 + 校验 + 文档”三件事一次搞定，开发体验远超传统框架。下一步建议：

• 用 fastapi.SQLAlchemy 或 databases 接数据库；
• 用 OAuth2PasswordBearer 做登录鉴权；
• 用 BackgroundTasks 处理异步任务（发邮件等）。

从今天起，把你的 Python 函数变成 API 只需几分钟。