schemas：两种定义方式的区别

material_records: dict = Field({}, description="物料记录")

和

material_records: dict = Field(default={}, examples=[{}], description="物料记录")

有什么区别？

这两个定义在 Pydantic 模型和 OpenAPI 文档生成中的行为有显著差异，具体分析如下：

---

1. `material_records: dict = Field({}, description="物料记录")

行为特点：

• 默认值：
  通过 Field({}, ...) 直接设置字段的默认值为空字典 {}。当用户不提供 material_records 字段时，模型会自动填充默认值。

• OpenAPI 文档：

  • 不会显式生成示例值（examples），但默认值 {} 会被自动推导为字段的示例。

  • 文档中会显示 description="物料记录" 的描述信息。

• 兼容性：
  兼容 Pydantic V1 和 V2，无潜在语法问题。

示例请求：

{
  "production_order_id": 1,
  "batch_number": "BATCH001",
  // 未传递 material_records 字段时，自动填充为 {}
}

---

2. material_records: dict = Field(default={}, examples=[{}], description="物料记录")

行为特点：

• 默认值：
  通过 default={} 显式设置默认值，效果与 Field({}, ...) 相同。

• OpenAPI 文档：

  • 显式定义 examples=[{}]，会在 OpenAPI 文档中展示一个 包含空字典的示例列表。

  • 文档会同时显示 description 和 examples。

• 潜在问题：
  如果运行环境是 Pydantic V1，会因不支持 examples 参数而报错（TypeError: Field() got an unexpected keyword argument 'examples'）。

示例请求：

{
  "production_order_id": 1,
  "batch_number": "BATCH001",
  "material_records": {},  // OpenAPI 文档会显示此示例值
}

---

关键区别总结

特性	Field({}, description=...)	Field(default={}, examples=[{}], description=...)
默认值	通过 Field({}) 隐式设置	通过 default={} 显式设置
示例值	无显式示例，OpenAPI 推导默认值 {} 为示例	显式定义 examples=[{}]，文档中显示指定示例
Pydantic V1 兼容性	完全兼容	不兼容（V1 不支持 examples 参数）
代码意图	仅设置默认值和描述，简化代码	明确控制示例值，增强文档可读性

---

如何选择？

1. 需要兼容 Pydantic V1：
   使用 Field({}, description=...)，避免 examples 参数导致的报错。

2. 需要 OpenAPI 文档精细化控制：
   使用 Field(default={}, examples=[{}], description=...)，确保文档中显示明确示例。

3. 使用 Pydantic V2：
   两种方式均合法，但推荐后者以提升文档可读性。

---

示例代码验证

from pydantic import BaseModel, Field

# 模型定义
class BatchRecordCreate(BaseModel):
    material_records: dict = Field(default={}, examples=[{}], description="物料记录")

# 请求验证（不传递 material_records）
data = {"production_order_id": 1, "batch_number": "BATCH001"}
model = BatchRecordCreate(**data)
print(model.material_records)  # 输出: {}

两种写法均可正确运行，但 examples 参数需要依赖 Pydantic V2 环境。