---

name: pydantic-models-py description: "按照多模型模式创建 Pydantic 模型，实现清晰的 API 契约。" risk: unknown source: community date_added: "2026-02-27"

Pydantic 模型

按照多模型模式创建 Pydantic 模型，实现清晰的 API 契约。

快速开始

从 assets/template.py 复制模板并替换占位符：

• {{ResourceName}} → PascalCase 名称（例如 Project）
• {{resource_name}} → snake_case 名称（例如 project）

多模型模式

| 模型 | 用途 | |-------|---------| | Base | 跨模型共享的公共字段 | | Create | 创建请求体（必填字段） | | Update | 更新请求体（所有字段可选） | | Response | 包含所有字段的 API 响应 | | InDB | 带 doc_type 的数据库文档 |

camelCase 别名

class MyModel(BaseModel):
    workspace_id: str = Field(..., alias="workspaceId")
    created_at: datetime = Field(..., alias="createdAt")
    
    class Config:
        populate_by_name = True  # 同时接受 snake_case 和 camelCase

可选更新字段

class MyUpdate(BaseModel):
    """所有字段可选，用于 PATCH 请求。"""
    name: Optional[str] = Field(None, min_length=1)
    description: Optional[str] = None

数据库文档

class MyInDB(MyResponse):
    """添加 doc_type 用于 Cosmos DB 查询。"""
    doc_type: str = "my_resource"

集成步骤

1. 在 src/backend/app/models/ 中创建模型
2. 从 src/backend/app/models/__init__.py 导出
3. 添加对应的 TypeScript 类型

适用场景

当需要执行概述中描述的工作流或操作时，此技能适用。

限制

• 仅在任务明确匹配上述描述范围时使用此技能。
• 不要将输出视为环境特定验证、测试或专家审查的替代品。
• 如果缺少必要的输入、权限、安全边界或成功标准，请停下来寻求澄清。