FastAPI：(7)路劲操作配置与JSON编码兼容

概述

文章内容

graph TD
    A[路径装饰器] --> B[HTTP方法]
    A --> C[元数据]
    A --> D[文档生成]
    B --> E[GET/POST/PUT/DELETE]
    C --> F[summary/description/tags]
    D --> G[OpenAPI/Swagger]
    H[JSON编码] --> I[jsonable_encoder]
    I --> J[模型转dict]
    I --> K[时间转str]

1.路劲操作装饰器配置

路劲装饰器配置

路径操作装饰器配置是FastAPI中定义API接口路径与请求方法（如GET、POST等） 之间映射关系的机制。开发者通过在「路劲操作函数」前添加装饰器（如@app.get()、@app.post()）来绑定URL路径与处理逻辑。这一配置不仅决定了请求的访问方式，还能绑定请求参数、文档信息、标签和响应模型等元数据，使得API行为更清晰、易管理、自动文档化。

重要特征：

特征1：明确的请求方法绑定：每个装饰器绑定一个或多个HTTP请求方法（GET/POST/PUT/DELETE等），体现操作语义。
特征2：路径与逻辑强关联：装饰器配置将路径（URL）和业务逻辑函数精确绑定，提升可读性与维护性。
特征3：可绑定元数据：路径操作装饰器可配合参数如summary、description、tags、response_model，增强文档生成和可维护性。
特征4：自动文档集成：基于装饰器配置，FastAPI可自动生成OpenAPI规范与Swagger UI界面，无需额外书写文档。

电商查询接口的配置

现象：
电商平台需要为用户提供一个商品查询接口，使用GET方法访问/items/{item_id}，函数逻辑为从数据库中查询商品信息。此接口使用路径参数item_id绑定，并带有描述元数据和响应模型。

特征对比：

✔ 特征1（请求方法明确）：使用GET方法，体现查询操作，符合REST语义；
✔ 特征2（路径-逻辑绑定）：路径/items/{item_id}与商品查询函数一一对应；
✔ 特征3（元数据）：附带summary、description，支持自动文档；
✔ 特征4（自动文档）：FastAPI自动将此接口展示在Swagger UI中，结构清晰。

from fastapi import FastAPI, UploadFile, File
from pydantic import BaseModel

app = FastAPI()

# 正例1：商品查询接口
class Item(BaseModel):
    id: int
    name: str
    price: float

@app.get("/items/{item_id}", summary="获取商品信息", description="根据商品ID查询商品详细信息", response_model=Item)
def read_item(item_id: int):
    return {"id": item_id, "name": "Example Product", "price": 99.99}

status_code

status_code 用于定义_路径操作_响应中的 HTTP 状态码。可以直接传递 int 代码，比如 404。如果记不住数字码的涵义，也可以用 status 的快捷常量。

from typing import Set, Union

from fastapi import FastAPI, status
from pydantic import BaseModel

app = FastAPI()

class Item(BaseModel):
    name: str
    description: Union[str, None] = None
    price: float
    tax: Union[float, None] = None
    tags: Set[str] = set()


@app.post("/items/", response_model=Item, status_code=status.HTTP_201_CREATED)
async def create_item(item: Item):
    return item

tags参数

tags 参数的值是由 str 组成的 list （一般只有一个 str ），tags 用于为_路径操作_添加标签：

from typing import Set, Union

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()


class Item(BaseModel):
    name: str
    description: Union[str, None] = None
    price: float
    tax: Union[float, None] = None
    tags: Set[str] = set()

@app.post("/items/", response_model=Item, tags=["items"])
async def create_item(item: Item):
    return item

@app.get("/items/", tags=["items"])
async def read_items():
    return [{"name": "Foo", "price": 42}]

@app.get("/users/", tags=["users"])
async def read_users():
    return [{"username": "johndoe"}]

摘要与描述参数

from typing import Set, Union
from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

class Item(BaseModel):
    name: str
    description: Union[str, None] = None
    price: float
    tax: Union[float, None] = None
    tags: Set[str] = set()

@app.post(
    "/items/",
    response_model=Item,
    summary="Create an item",
    description="Create an item with all the information, name, description, price, tax and a set of unique tags",
)
async def create_item(item: Item):
    return item

文档字符串

描述内容比较长且占用多行时，可以在函数的 docstring 中声明_路径操作_的描述，FastAPI 支持从文档字符串中读取描述内容。

文档字符串支持 Markdown，能正确解析和显示 Markdown 的内容，但要注意文档字符串的缩进

from typing import Set, Union

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()


class Item(BaseModel):
    name: str
    description: Union[str, None] = None
    price: float
    tax: Union[float, None] = None
    tags: Set[str] = set()


@app.post("/items/", response_model=Item, summary="Create an item")
async def create_item(item: Item):
    """
    Create an item with all the information:

    - **name**: each item must have a name
    - **description**: a long description
    - **price**: required
    - **tax**: if the item doesn't have tax, you can omit this
    - **tags**: a set of unique tag strings for this item
    """
    return item

下图为 Markdown 文本在 API 文档中的显示效果：

响应描述

response_description 参数用于定义响应的描述说明。

注意，response_description 只用于描述响应，description 一般则用于描述_路径操作_。

OpenAPI 规定每个_路径操作_都要有响应描述。如果没有定义响应描述，FastAPI 则自动生成内容为 “Successful response” 的响应描述。

from typing import Set, Union

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()


class Item(BaseModel):
    name: str
    description: Union[str, None] = None
    price: float
    tax: Union[float, None] = None
    tags: Set[str] = set()


@app.post(
    "/items/",
    response_model=Item,
    summary="Create an item",
    response_description="The created item",
)
async def create_item(item: Item):
    """
    Create an item with all the information:

    - **name**: each item must have a name
    - **description**: a long description
    - **price**: required
    - **tax**: if the item doesn't have tax, you can omit this
    - **tags**: a set of unique tag strings for this item
    """
    return item

弃用路劲操作

deprecated 参数可以把_路径操作_标记为弃用，无需直接删除：

from fastapi import FastAPI

app = FastAPI()

@app.get("/items/", tags=["items"])
async def read_items():
    return [{"name": "Foo", "price": 42}]

@app.get("/users/", tags=["users"])
async def read_users():
    return [{"username": "johndoe"}]

@app.get("/elements/", tags=["items"], deprecated=True)
async def read_elements():
    return [{"item_id": "Foo"}]

2.JSON编码兼容

场景

编码兼容

在某些情况下，可能需要将数据类型（如Pydantic模型）转换为与JSON兼容的数据类型（如dict、list等）。比如，如果需要将其存储在数据库中。对于这种要求， FastAPI提供了jsonable_encoder()函数。

jsonable_encoder

假设有一个数据库名为fake_db，它只能接收与JSON兼容的数据。例如，它不接收datetime这类的对象，因为这些对象与JSON不兼容。因此，datetime对象必须将转换为包含ISO格式化的str类型对象。

同样，这个数据库也不会接收Pydantic模型（带有属性的对象），而只接收dict。对此可以使用jsonable_encoder。它接收一个对象，比如Pydantic模型，并会返回一个JSON兼容的版本。

from datetime import datetime

from fastapi import FastAPI
from fastapi.encoders import jsonable_encoder
from pydantic import BaseModel

fake_db = {}

class Item(BaseModel):
    title: str
    timestamp: datetime
    description: str | None = None

app = FastAPI()

@app.put("/items/{id}")
def update_item(id: str, item: Item):
    json_compatible_item_data = jsonable_encoder(item)
    fake_db[id] = json_compatible_item_data