在 Pydantic v2 中，可通过 Annotated 结合 Field 和自定义类型别名，高效复用带约束的 Decimal | None 字段定义，避免重复声明 max_digits、decimal_places、json_schema_extra 等参数，同时灵活注入 description。
在 pydantic v2 中，可通过 `annotated` 结合 `field` 和自定义类型别名，高效复用带约束的 `decimal | none` 字段定义，避免重复声明 `max_digits`、`decimal_places`、`json_schema_extra` 等参数，同时灵活注入 `description`。
在构建多个结构相似的模型时（如金融、计量类业务中大量共享精度与格式要求的数值字段），硬编码重复的 Field(..., max_digits=80, decimal_places=5, json_schema_extra={"type": "display"}) 不仅冗余，更易引发维护不一致风险。Pydantic v2 原生支持通过 typing.Annotated 实现字段定义的模块化封装——它允许你将类型注解与元数据（如 Field 配置）解耦组合，从而实现真正意义上的“可复用字段类型”。
✅ 推荐方案：Annotated + 预设 Field + WithJsonSchema
最清晰、可读性高且语义明确的方式是定义一个带固定约束的可空 Decimal 类型别名，再按需叠加描述信息：
from decimal import Decimal
from typing import Annotated, Any
from pydantic import BaseModel, Field, WithJsonSchema
# 共享基础约束与 JSON Schema 扩展
DECIMAL_CONFIG = {"max_digits": 80, "decimal_places": 5}
DISPLAY_SCHEMA = WithJsonSchema({"type": "display"})
# 复用类型：NullableDecimal = Decimal | None + 公共约束 + display schema
NullableDecimal = Annotated[
Decimal | None,
Field(**DECIMAL_CONFIG),
DISPLAY_SCHEMA
]
# 使用示例：仅需为每个字段指定 description（通过 Annotated 第二参数）
class ModelA(BaseModel):
benchmark2: Annotated[NullableDecimal, "Benchmark 2"] = None
benchmark3: Annotated[NullableDecimal, "Benchmark 3"] = None
benchmark4: Annotated[NullableDecimal, "Benchmark 4"] = None⚠️ 注意：
Annotated[T, ...]中的字符串字面量（如"Benchmark 2"）会被 Pydantic 自动识别为Field(description=...)，这是 v2 的隐式约定（详见文档）。若需显式控制，也可直接写Field(description="...")。
? 替代方案：函数式字段工厂（适用于动态描述）
当 description 来源于变量或需运行时生成时，可封装为字段工厂函数（注意：返回的是 Field 实例，不是类型）：
def BenchmarkField(description: str) -> Field:
return Field(
default=None,
max_digits=80,
decimal_places=5,
description=description,
json_schema_extra={"type": "display"},
)
class ModelB(BaseModel):
benchmark2: Decimal | None = BenchmarkField("Benchmark 2")
benchmark3: Decimal | None = BenchmarkField("Benchmark 3")
benchmark4: Decimal | None = BenchmarkField("Benchmark 4")✅ 优势：逻辑集中、易于单元测试；
❌ 局限：无法复用 Decimal | None 类型本身（仍需重复写类型注解）。
? 进阶技巧：组合 Annotated 支持多级复用
你还可以进一步抽象出「带描述的基准字段」类型，实现零重复：
def BenchmarkField(description: str) -> Any:
return Annotated[
Decimal | None,
Field(default=None, **DECIMAL_CONFIG),
WithJsonSchema({"type": "display"}),
Field(description=description), # 显式覆盖 description
]
class ModelC(BaseModel):
benchmark2: BenchmarkField("Benchmark 2") = None
benchmark3: BenchmarkField("Benchmark 3") = None
benchmark4: BenchmarkField("Benchmark 4") = None✅ 验证与最佳实践
- 所有方案均生成符合预期的 JSON Schema（
"type": "display"出现在properties.xxx.type）； -
model_dump()行为完全一致，支持None、字符串/数字输入自动转换； -
强烈建议避免使用
Field(...)作为类型别名的值（如原答案中NullableDecimal = Annotated[..., Field(...)]是合法的，但Field本身不是类型，仅用于元数据注入）； - 若项目中存在大量同类字段，推荐将
DECIMAL_CONFIG和DISPLAY_SCHEMA提取至配置模块统一管理。
通过 Annotated，你不仅消除了代码重复，更将领域语义（如“这是一个展示用的高精度基准值”）提升为类型系统的一部分——这才是 Pydantic v2 强大类型表达力的核心体现。
