第 3 章: FastApi中的路由

---

本章概述

在本章中，我们将深入学习： - 多文件间的路由组织 - 限制允许值（预定义数据） - 使用Query()的参数 - 使用Path()的路径参数 - 请求体（Body） - 使用Pydantic模型验证请求体 - 各种验证方法

---

3.1 多文件间的路由

在大型应用中，将所有路由放在一个文件中是不现实的。FastAPI允许我们使用APIRouter在多个文件中组织路由。

创建路由模块

users.py:

from fastapi import APIRouter

router = APIRouter()

@router.get("/users/")
def read_users():
    return [{"user_id": 1}, {"user_id": 2}]

main.py:

from fastapi import FastAPI
from users import router as users_router

app = FastAPI()
app.include_router(users_router)

---

3.2 限制允许值（预定义数据）

使用Enum限制参数只能取特定值：

from enum import Enum
from fastapi import FastAPI

class ModelName(str, Enum):
    alexnet = "alexnet"
    resnet = "resnet"
    lenet = "lenet"

app = FastAPI()

@app.get("/models/{model_name}")
def get_model(model_name: ModelName):
    return {"model_name": model_name}

---

3.3 使用Query()的参数

Query()用于定义查询参数（URL中?后面的参数）：

from fastapi import FastAPI, Query

app = FastAPI()

@app.get("/items/")
def read_items(q: str = Query(None, min_length=3, max_length=50)):
    results = {"items": [{"item_id": "Foo"}]}
    if q:
        results.update({"q": q})
    return results

访问： /items/?q=test

---

3.4 使用Path()的路径参数

Path()用于验证路径参数：

from fastapi import FastAPI, Path

app = FastAPI()

@app.get("/items/{item_id}")
def read_item(
    item_id: int = Path(..., title="The ID of the item to get", ge=1),
):
    return {"item_id": item_id}

• ... 表示必填参数
• ge=1 表示大于等于1

---

3.5 请求体（Body）

使用Body接收JSON请求体：

from fastapi import FastAPI, Body
from pydantic import BaseModel

class Item(BaseModel):
    name: str
    description: str = None
    price: float
    tax: float = None

app = FastAPI()

@app.post("/items/")
def create_item(item: Item = Body(..., embed=True)):
    return item

---

3.6 使用Pydantic模型验证请求体

Pydantic提供了强大的数据验证功能：

from pydantic import BaseModel, Field

class User(BaseModel):
    username: str = Field(..., min_length=3, max_length=50)
    email: str
    full_name: str = None
    age: int = Field(None, ge=18, le=100)

验证示例

@app.post("/users/")
def create_user(user: User):
    return user

如果请求数据不符合验证规则，FastAPI会自动返回详细的错误信息。

---

3.7 嵌套类

Pydantic模型可以嵌套：

class Address(BaseModel):
    street: str
    city: str
    country: str

class User(BaseModel):
    username: str
    address: Address  # 嵌套模型

---

3.8 继承

模型可以继承：

class UserBase(BaseModel):
    username: str
    email: str

class UserCreate(UserBase):
    password: str

class User(UserBase):
    id: int
    
    class Config:
        orm_mode = True

---

3.9 字段验证

使用Field添加验证和元数据：

from pydantic import Field

class Item(BaseModel):
    name: str = Field(..., title="Item Name", max_length=50)
    price: float = Field(..., gt=0, description="The price must be greater than zero")

---

3.10 可选值和默认值

from typing import Optional

class Item(BaseModel):
    name: str
    description: Optional[str] = None  # 可选
    price: float = 0.0  # 默认值
    tax: Optional[float] = None

---

3.11 FastAPI自动文档

FastAPI自动生成两种交互式文档：

Swagger UI

访问：http://127.0.0.1:8000/docs

功能： - 交互式API测试 - 查看所有路由 - 查看请求/响应模型

ReDoc

访问：http://127.0.0.1:8000/redoc

功能： - 更简洁的文档界面 - 适合阅读API规范

---

---

小结

在本章中，我们深入学习了FastAPI的路由系统： - ✅ 使用APIRouter组织多文件路由 - ✅ 使用Enum限制参数值 - ✅ 使用Query()和Path()验证参数 - ✅ 使用Body接收请求体 - ✅ 使用Pydantic模型进行数据验证 - ✅ 嵌套模型、继承和字段验证 - ✅ 自动生成的交互式API文档

在下一章中，我们将学习错误处理和状态码！