在FastAPI、Django Ninja等现代Python后端框架中，Pydantic已成为数据验证与序列化的标准工具。开发者经常面临一个两难问题：如何在导出数据时保留敏感字段的明文（例如将密码哈希写入数据库），同时在验证错误日志或用户反馈中彻底屏蔽这些信息，避免敏感数据泄露？近日，Pydantic社区流传的一项定制化方案，精准解决了这一痛点。

背景：敏感字段的双重诉求

Pydantic内置了SecretStr和SecretBytes类型，它们会在repr()、str()以及验证错误中自动掩码为'**********'，有效防止意外泄露。然而，当调用model_dump()或model_dump_json()时，这些字段默认也会被掩码——除非显式设置secret=True参数（Pydantic v2中通过model_serializer控制）。但许多实际场景要求model_dump()输出明文：比如需要将完整数据传递给下游服务，或存入数据库供后续比对。

换言之，开发者期望的行为是： - 在model_dump()中：显示实际值（明文）。 - 在任何验证错误（包括字段级、模型级）中：显示掩码值（如'***'）。

内置类型无法直接满足这一矛盾需求。社区曾广泛使用Field(..., repr=False)来禁止在repr中显示值，但repr=False会彻底隐藏字段，而不只是掩码；且验证错误中仍会暴露原始值。于是，定制方案应运而生。

解决方案：自定义类型与序列化器

核心思路是创建一个继承自str或自定义基础类型的“敏感字符串”类，重写其字符串表示方法（__repr__），并利用Pydantic的model_serializer或field_serializer来控制model_dump的行为。

以下是一个可用的实现（基于Pydantic v2）：

from pydantic import BaseModel, field_serializer
from typing import Any

class SecretPlaintext(str):
    """在字符串表示时掩码，在序列化时输出原始内容"""
    def __repr__(self) -> str:
        return '***'

class User(BaseModel):
    username: str
    password: SecretPlaintext

    @field_serializer('password')
    def serialize_password(self, value: SecretPlaintext, _info: Any) -> str:
        # 此处返回明文，覆盖默认的序列化行为
        return str(value)

# 使用示例
user = User(username='alice', password='s3cr3t')
print(user.model_dump())  
# 输出: {'username': 'alice', 'password': 's3cr3t'}  （明文）

try:
    User(username='bob', password=123)  # 类型错误
except Exception as e:
    print(e)
# 验证错误中 password 字段会显示 '***' 而不是原始值

核心要点： - SecretPlaintext继承自str，其__repr__返回掩码字符串，因此任何调用repr()的地方（包括Pydantic验证错误构建时的repr(validation_error.errors())）都会显示***。 - field_serializer强制在model_dump()时调用该序列化器返回明文（str(value)），从而绕过repr影响。

案例演示：日志安全与数据导出两不误

假设一个API接收用户注册请求，需要将密码哈希后存入数据库，同时返回给前端时隐藏密码。使用上述方案：

from pydantic import BaseModel, field_serializer, ValidationError
import bcrypt

class UserCreate(BaseModel):
    email: str
    password: SecretPlaintext

    @field_serializer('password')
    def dump_password(self, v, _info):
        # 实际应用中可返回哈希值
        return bcrypt.hashpw(v.encode(), bcrypt.gensalt()).decode()

try:
    data = UserCreate(email='user@example.com', password='myPass!')
    dumped = data.model_dump()
    print(dumped)  # 输出哈希值，而非明文
except ValidationError as e:
    # 错误信息中password字段显示'***'，不会泄露密码
    print(e)

注意：field_serializer中返回的值就是model_dump()的最终值，你可以在此处进行哈希、加密或其他处理，而__repr__始终返回掩码。这比内置SecretStr更灵活。

专家提醒：安全与性能平衡

尽管该方案有效，但开发者需注意以下几点： 1. 不要依赖__repr__作为唯一防线：Python的str()、%s格式化、f-string等可能暴露原始值，需确保所有输出路径都经过相同处理。 2. 日志配置：建议配合日志过滤器，在全局层面对敏感字段进行脱敏，形成纵深防御。 3. Pydantic版本兼容性：field_serializer是Pydantic v2特性，v1用户需要使用validator+__repr__重写，或升级版本。 4. 性能开销：每个字段的__repr__调用在大量错误构建时略有开销，但通常可忽略。

结语

Pydantic的灵活性允许开发者精确控制数据展示的每一个场景。通过自定义类型与序列化器的组合，既能满足业务对明文导出的需求，又能严守验证环节的安全底线。这一技巧已在多个生产项目中验证有效，尤其适合需要同时兼顾接口文档清晰与安全合规的微服务架构。未来，Pydantic官方是否会推出类似SecretButOnlyInErrors的内置类型？社区在等待答案的同时，不妨先用这一方案解燃眉之急。