pydantic-models-py

Microsoft ｜ 架構與重構 ｜ 原文 ｜ MIT

用 Base/Create/Update/Response/InDB 多模型模式寫 Pydantic v2 模型

---
name: pydantic-models-py
description: 依照 Base、Create、Update、Response、InDB 多模型模式建立 Pydantic 模型。適用於在使用 Pydantic v2 的 Python 應用程式中定義 API request/response schema、資料庫模型或資料驗證。
license: MIT
metadata:
  author: Microsoft
  version: "1.0.0"
---

# Pydantic Models

依照多模型模式建立 Pydantic 模型，讓 API 契約乾淨清楚。

## 快速開始

從 [assets/template.py](assets/template.py) 複製範本，並替換 placeholder：
- `{{ResourceName}}` → PascalCase 名稱（例如 `Project`）
- `{{resource_name}}` → snake_case 名稱（例如 `project`）

## 多模型模式

| 模型 | 用途 |
|-------|---------|
| `Base` | 各模型共用的欄位 |
| `Create` | 建立用的 request body（必填欄位） |
| `Update` | 更新用的 request body（全部選填） |
| `Response` | 包含所有欄位的 API response |
| `InDB` | 帶有 `doc_type` 的資料庫文件 |

## camelCase 別名

```python
from datetime import datetime

from pydantic import BaseModel, ConfigDict, Field

class MyModel(BaseModel):
    model_config = ConfigDict(populate_by_name=True)

    workspace_id: str = Field(..., alias="workspaceId")
    created_at: datetime = Field(..., alias="createdAt")
```

## 選填的更新欄位

```python
class MyUpdate(BaseModel):
    model_config = ConfigDict(populate_by_name=True)

    name: Optional[str] = Field(None, min_length=1)
    description: Optional[str] = None
```

## 資料庫文件

```python
class MyInDB(MyResponse):
    doc_type: str = "my_resource"
```

## 整合步驟

1. 在 `src/backend/app/models/` 建立模型
2. 從 `src/backend/app/models/__init__.py` export
3. 加上對應的 TypeScript 型別

## 參考檔案

| 檔案 | 內容 |
|------|----------|
| [references/capabilities.md](references/capabilities.md) | 其他非主打的功能、各 operation group 的涵蓋範圍，以及正式環境檢查清單。 |

---
name: pydantic-models-py
description: Create Pydantic models following the multi-model pattern with Base, Create, Update, Response, and InDB variants. Use when defining API request/response schemas, database models, or data validation in Python applications using Pydantic v2.
license: MIT
metadata:
  author: Microsoft
  version: "1.0.0"
---

# Pydantic Models

Create Pydantic models following the multi-model pattern for clean API contracts.

## Quick Start

Copy the template from [assets/template.py](assets/template.py) and replace placeholders:
- `{{ResourceName}}` → PascalCase name (e.g., `Project`)
- `{{resource_name}}` → snake_case name (e.g., `project`)

## Multi-Model Pattern

| Model | Purpose |
|-------|---------|
| `Base` | Common fields shared across models |
| `Create` | Request body for creation (required fields) |
| `Update` | Request body for updates (all optional) |
| `Response` | API response with all fields |
| `InDB` | Database document with `doc_type` |

## camelCase Aliases

```python
from datetime import datetime

from pydantic import BaseModel, ConfigDict, Field

class MyModel(BaseModel):
    model_config = ConfigDict(populate_by_name=True)

    workspace_id: str = Field(..., alias="workspaceId")
    created_at: datetime = Field(..., alias="createdAt")
```

## Optional Update Fields

```python
class MyUpdate(BaseModel):
    model_config = ConfigDict(populate_by_name=True)

    name: Optional[str] = Field(None, min_length=1)
    description: Optional[str] = None
```

## Database Document

```python
class MyInDB(MyResponse):
    doc_type: str = "my_resource"
```

## Integration Steps

1. Create models in `src/backend/app/models/`
2. Export from `src/backend/app/models/__init__.py`
3. Add corresponding TypeScript types

## Reference Files

| File | Contents |
|------|----------|
| [references/capabilities.md](references/capabilities.md) | Additional non-hero capabilities, operation-group coverage, and production checklists. |