120 lines
3.8 KiB
Markdown
120 lines
3.8 KiB
Markdown
# Pydantic Schema
|
||
|
||
Schema 层负责请求数据的校验。项目使用 Pydantic v2 的 `BaseModel` 定义表单类，通过 `Field` 约束字段格式，FastAPI 在接收请求体时自动执行校验。
|
||
|
||
## 文件位置
|
||
|
||
```
|
||
src/modules/system/position/schemas.py
|
||
```
|
||
|
||
## 完整代码
|
||
|
||
```python
|
||
from typing import Optional
|
||
|
||
from pydantic import BaseModel, Field
|
||
from core.base_schemas import BaseForm
|
||
|
||
|
||
# ============================================================
|
||
# 岗位表单类
|
||
# ============================================================
|
||
class PositionForm(BaseForm):
|
||
"""岗位创建/编辑表单"""
|
||
name: str = Field(..., min_length=1, max_length=150, description="岗位名称")
|
||
status: int = Field(..., ge=1, le=2, description="岗位状态：1-在用 2-停用")
|
||
sort: int = Field(..., ge=0, le=99999, description="岗位排序")
|
||
|
||
|
||
# ============================================================
|
||
# 设置状态表单类
|
||
# ============================================================
|
||
class PositionStatusForm(BaseModel):
|
||
"""岗位状态更新表单"""
|
||
id: int = Field(..., gt=0, description="岗位ID")
|
||
status: int = Field(..., ge=1, le=2, description="岗位状态：1-在用 2-停用")
|
||
```
|
||
|
||
## 代码解析
|
||
|
||
### 基类选择
|
||
|
||
| 基类 | 用途 | 包含字段 |
|
||
|:----|:----|:----|
|
||
| `BaseForm` | 创建/编辑通用表单 | 自带可选 `id` 字段（`Optional[int]`），编辑时传入 |
|
||
| `BaseModel` | 特定操作表单 | 无额外字段，按需定义 |
|
||
|
||
创建和编辑共用 `PositionForm`：创建时不传 `id`，编辑时传入 `id`。`BaseForm` 的 `id` 字段定义为 `Optional[int] = Field(None, gt=0)`，创建时可省略。
|
||
|
||
### Field 约束
|
||
|
||
```python
|
||
name: str = Field(..., min_length=1, max_length=150, description="岗位名称")
|
||
```
|
||
|
||
| 参数 | 含义 |
|
||
|:----|:----|
|
||
| `...` | 必填（Ellipsis） |
|
||
| `min_length=1` | 最小长度 1，不允许空字符串 |
|
||
| `max_length=150` | 最大长度 150 |
|
||
| `description` | Swagger 文档中的字段说明 |
|
||
|
||
```python
|
||
status: int = Field(..., ge=1, le=2, description="岗位状态：1-在用 2-停用")
|
||
```
|
||
|
||
| 参数 | 含义 |
|
||
|:----|:----|
|
||
| `ge=1` | 大于等于（Greater Equal） |
|
||
| `le=2` | 小于等于（Less Equal） |
|
||
|
||
```python
|
||
sort: int = Field(..., ge=0, le=99999, description="岗位排序")
|
||
```
|
||
|
||
排序字段允许 0 到 99999 的范围。
|
||
|
||
### 状态更新单独建类
|
||
|
||
```python
|
||
# ============================================================
|
||
# 设置状态表单类
|
||
# ============================================================
|
||
class PositionStatusForm(BaseModel):
|
||
"""岗位状态更新表单"""
|
||
id: int = Field(..., gt=0, description="岗位ID")
|
||
status: int = Field(..., ge=1, le=2, description="岗位状态：1-在用 2-停用")
|
||
```
|
||
|
||
状态更新接口只需要 `id` 和 `status` 两个字段，与创建/编辑表单分开定义，接口语义更清晰。
|
||
|
||
## 如何在端点中使用
|
||
|
||
```python
|
||
@router.post('/add')
|
||
def add(request: Request, data: PositionForm):
|
||
return position_service.add(request, data)
|
||
```
|
||
|
||
FastAPI 自动将请求体 JSON 解析为 `PositionForm` 实例。校验失败时，框架自动返回标准错误响应：
|
||
|
||
```json
|
||
{
|
||
"code": 1,
|
||
"data": null,
|
||
"msg": "name: String should have at least 1 character"
|
||
}
|
||
```
|
||
|
||
## 开发要点
|
||
|
||
1. **创建/编辑共用一个表单类**：继承 `BaseForm`，利用其内置的可选 `id` 字段
|
||
2. **特殊操作单独建类**：如状态更新、排序调整等，只包含必要的字段
|
||
3. **合理设置约束**：`min_length` / `max_length` / `ge` / `le` / `gt` 等，让框架自动校验
|
||
4. **description 必填**：用于 Swagger 文档展示，方便调试
|
||
|
||
## 总结
|
||
|
||
Pydantic Schema 通过 `BaseForm` 继承公共字段（id、create_user 等），使用 `Field(...)` 声明约束，`@field_validator` 实现自定义校验。特殊操作单独建类，`description` 必填用于 Swagger 文档展示。
|