如何在FastAPI中自定义JSON编码器_处理Python中的UUID与日期格式-Python教程-PHP中文网

将一个或多个视频上传至YouTube。当用户想“上传到YouTube”“发YouTube”“批量上传”“upload to YouTube”“post videos to YouTube”或发布到YouTube时使用此技能。

fastapi默认json编码器不支持uuid和datetime，需通过basemodel的json_encoders或jsonable_encoder的custom_encoder统一处理。推荐uuid转str、datetime用isoformat()并注意时区与精度。

如何在fastapi中自定义json编码器_处理python中的uuid与日期格式

FastAPI默认JSON编码器不支持UUID和datetime

FastAPI底层用的是json.dumps()，而Python标准库的json模块原生不识别uuid.UUID和datetime对象，直接返回TypeError: Object of type UUID is not JSON serializable或类似错误。这不是FastAPI的bug，而是Python JSON序列化的固有限制。

你不需要重写整个响应流程，也不必在每个路由里手动str()或.isoformat()——FastAPI提供了统一接管点。

用`json_encoders`在`BaseModel`中声明字段级编码规则

这是最常用、最安全的方式，适用于Pydantic v1（FastAPI 0.104.x及更早）或v2中仍使用BaseModel定义响应模型的场景。它只影响该模型的序列化行为，不影响全局或其他模型。

json_encoders是BaseModel.Config（v1）或model_config（v2）里的字典，键为类型，值为转换函数
对UUID，推荐直接转str；对datetime，建议用.isoformat()而非strftime，避免时区丢失
注意：v2中需写成model_config = {"json_encoders": {...}}，且json_encoders仅对model_dump(mode="json")生效（FastAPI自动调用）

from pydantic import BaseModel
from uuid import UUID
from datetime import datetime
<p>class Item(BaseModel):
id: UUID
created_at: datetime</p><pre class="brush:python;toolbar:false;"># Pydantic v2 写法
model_config = {
    "json_encoders": {
        UUID: str,
        datetime: lambda dt: dt.isoformat(),
    }
}

全局替换`jsonable_encoder`的`custom_encoder`参数

当你无法修改模型定义（比如用第三方库的BaseModel子类），或需要统一处理所有响应中的日期/UUID，可以用FastAPI内置的jsonable_encoder增强逻辑。它在JSONResponse、Response和依赖注入的BackgroundTasks等场景下都会被调用。

在路由函数中显式调用jsonable_encoder(..., custom_encoder={...})是最可控的方式
若想全局生效，可封装一个自定义JSONResponse子类，在render()里预置custom_encoder
不要覆盖fastapi.encoders.jsonable_encoder本身——它被多处内部调用，改了可能破坏OpenAPI文档生成

from fastapi import FastAPI
from fastapi.responses import JSONResponse
from fastapi.encoders import jsonable_encoder
from uuid import UUID
from datetime import datetime
<p>app = FastAPI()</p><p>@app.get("/item")
def get_item():
data = {"id": UUID("a1b2c3d4-5678-90ab-cdef-1234567890ab"), "created_at": datetime.now()}
encoded = jsonable_encoder(
data,
custom_encoder={
UUID: str,
datetime: lambda dt: dt.replace(microsecond=0).isoformat() + "Z",
}
)
return JSONResponse(content=encoded)
</p>

注意时区与精度陷阱

很多人忽略datetime序列化后是否保留时区信息，以及微秒精度是否必要。FastAPI默认不处理时区，.isoformat()对naive datetime不带Z或+00:00，前端解析容易出错。

后端存datetime建议统一用datetime.timezone.utc，输出时强制.astimezone(timezone.utc)
UUID转str没问题，但别用repr()或hex——前者带UUID('...')前缀，后者丢掉分隔符
如果API要兼容旧系统，日期格式必须严格匹配（如"2024-01-01T12:00:00+00:00"），就别依赖lambda dt: dt.isoformat()，改用dt.strftime("%Y-%m-%dT%H:%M:%S%z")并手动补冒号