3. 数据模型设计基础：Pydantic 模型定义、字段类型与校验、数据模型与数据库表映射

在运维数据移交接口开发中，数据模型是连接业务逻辑与持久化存储的核心桥梁。本章将系统讲解如何使用 Pydantic 定义接口数据模型、配置字段类型与校验规则，并建立与数据库表的映射关系，确保数据在传输与存储过程中的完整性与一致性。

3.1 Pydantic 模型定义基础

Pydantic 是 Python 生态中最流行的数据验证库，通过声明式类定义实现数据模型。在 FastAPI 框架中，Pydantic 模型同时承担请求体、响应体与数据校验的职责。

3.1.1 基础模型定义示例

from pydantic import BaseModel, Field
from typing import Optional, List
from datetime import datetime

class DeviceBase(BaseModel):
    """设备基础模型"""
    device_code: str = Field(..., description="设备编码，全局唯一")
    device_name: str = Field(..., max_length=128, description="设备名称")
    device_type: str = Field(..., description="设备类型：server/network/storage")
    rack_position: Optional[str] = Field(None, max_length=64, description="机柜位置")
    status: int = Field(default=1, ge=0, le=1, description="状态：0-停用，1-启用")

class DeviceCreate(DeviceBase):
    """创建设备请求模型"""
    pass

class DeviceResponse(DeviceBase):
    """设备响应模型，包含数据库生成的字段"""
    id: int
    created_at: datetime
    updated_at: datetime

    class Config:
        from_attributes = True  # 支持 ORM 模式

3.2 字段类型与校验规则

Pydantic 提供丰富的字段类型和校验器，能够覆盖运维数据移交中的绝大多数场景。下表列出常用字段类型及其适用场景：

3.2.1 高级校验器应用

当内置校验无法满足业务规则时，使用 @validator 或 @field_validator 实现自定义逻辑：

from pydantic import BaseModel, field_validator
import re

class DeviceTransferModel(BaseModel):
    device_code: str
    ip_address: str
    transfer_date: str

    @field_validator('device_code')
    @classmethod
    def validate_device_code(cls, v):
        """设备编码格式：DC-{机房}-{楼层}-{机柜}-{序号}"""
        pattern = r'^DC-[A-Z]{2,4}-\d{2}-[A-Z]\d{2}-\d{3}$'
        if not re.match(pattern, v):
            raise ValueError('设备编码格式不正确，示例：DC-BJ01-03-A12-001')
        return v

    @field_validator('ip_address')
    @classmethod
    def validate_ip(cls, v):
        parts = v.split('.')
        if len(parts) != 4 or not all(0 <= int(p) <= 255 for p in parts):
            raise ValueError('IP 地址格式无效')
        return v

3.3 数据模型与数据库表映射

在 FastAPI + SQLAlchemy 架构中，Pydantic 模型负责 API 层数据交换，ORM 模型负责数据库持久化。两者通过 映射配置 实现双向转换。

3.3.1 ORM 模型定义

from sqlalchemy import Column, Integer, String, DateTime, SmallInteger
from sqlalchemy.ext.declarative import declarative_base
from datetime import datetime

Base = declarative_base()

class DeviceORM(Base):
    __tablename__ = 'devices'

    id = Column(Integer, primary_key=True, autoincrement=True)
    device_code = Column(String(64), unique=True, nullable=False, index=True)
    device_name = Column(String(128), nullable=False)
    device_type = Column(String(32), nullable=False)
    rack_position = Column(String(64), nullable=True)
    status = Column(SmallInteger, default=1)
    created_at = Column(DateTime, default=datetime.utcnow)
    updated_at = Column(DateTime, default=datetime.utcnow, onupdate=datetime.utcnow)

3.3.2 映射关系对照表

3.3.3 模型转换与响应序列化

from sqlalchemy.orm import Session

def create_device(db: Session, device_in: DeviceCreate) -> DeviceResponse:
    """将 Pydantic 模型转换为 ORM 模型并写入数据库"""
    device_orm = DeviceORM(**device_in.model_dump())
    db.add(device_orm)
    db.commit()
    db.refresh(device_orm)
    # ORM 模型自动转换为 Pydantic 响应模型
    return DeviceResponse.model_validate(device_orm)

3.4 数据模型设计流程

下图展示了从业务需求到数据库表映射的完整设计流程：

3.5 模型设计避坑指南

• 字段类型不匹配： Pydantic 的 int 与数据库的 SmallInteger 或 BigInteger 需显式对应，避免溢出或精度丢失。
• 忽略时区处理： 运维数据涉及多地机房，建议统一使用 UTC 时间存储，API 层按需转换时区。
• 过度校验： 数据库层已有唯一约束和默认值，API 层无需重复实现相同逻辑，只需做业务语义校验。
• 模型复用混乱： 创建、更新、响应模型应分开定义，避免使用同一个模型导致字段暴露或校验冲突。
• 忽略索引设计： 设备编码、文档 ID 等高频查询字段必须在 ORM 模型中显式声明索引。