FastAPI应用处理PUT请求时遭遇UnicodeEncodeError问题求助

错误原因 #

UnicodeEncodeError: 'ascii' codec can't encode character '\xf1' 是因为系统或应用默认使用ASCII编码处理文本，无法识别非ASCII字符（比如西班牙语的ñ），导致编码失败。

具体解决步骤 #

1. 强制Python环境使用UTF-8编码 #

在项目入口文件（如main.py）顶部添加以下代码，确保Python默认编码为UTF-8：

import sys
import locale

# 设置系统区域编码
locale.setlocale(locale.LC_ALL, 'en_US.UTF-8')

或者在启动应用前设置环境变量：

export PYTHONIOENCODING=utf-8

2. 配置Pydantic Schema的JSON序列化规则 #

修改你的BaseSchema，添加JSON序列化配置，确保非ASCII字符不被转义：

from pydantic import BaseModel
import json

class BaseSchema(BaseModel):
    class Config:
        # 确保JSON序列化时保留UTF-8字符
        json_dumps = lambda obj, **kwargs: json.dumps(obj, ensure_ascii=False, **kwargs)
        anystr_strip_whitespace = True

这样Pydantic在转换数据为JSON时，会直接输出原UTF-8字符，而非转义后的ASCII格式。

3. 检查数据库连接的编码设置 #

如果ProductService.update涉及数据库操作，确保数据库连接URL指定UTF-8编码：

• MySQL/MariaDB：

  SQLALCHEMY_DATABASE_URL = "mysql+pymysql://username:password@localhost/db_name?charset=utf8mb4"
  

• PostgreSQL：确认数据库编码为UTF8，默认配置即可，无需额外修改。

4. 显式指定FastAPI响应的编码 #

在路由中返回响应时，显式指定UTF-8编码：

from fastapi.responses import JSONResponse

@product_router.put("/{id}", response_model=ProductUpdateResponseSchema)
@authenticated(validate=[Validation.IS_ADMIN])
def update_product(id: str, payload: ProductUpdateSchema):
    product = ProductService.update(id, payload.dict(exclude_none=True))
    return JSONResponse(
        content=product,
        media_type="application/json; charset=utf-8"
    )

也可以全局配置FastAPI的默认响应编码：

from fastapi import FastAPI
from fastapi.responses import JSONResponse

app = FastAPI(
    default_response_class=lambda content: JSONResponse(
        content, 
        media_type="application/json; charset=utf-8"
    )
)

5. 验证枚举字段的编码 #

检查LineCreditLegalPerson枚举类的value是否包含非ASCII字符，确保枚举值为UTF-8编码的字符串：

from enum import Enum

class LineCreditLegalPerson(Enum):
    EXAMPLE_OPTION = "包含ñ的示例值"  # 确保枚举值编码正确

内容的提问来源于stack exchange，提问作者Pablo Cimato