一、数据库层设计

1.1 ORM模型定义

class SysUser(Base):
    __table_args__ = {
        "mysql_engine": "InnoDB",
        "comment": "用户表"
    }

    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True, comment="用户ID")
    username: Mapped[str] = mapped_column(String(50), unique=True, nullable=False, comment="用户名")
    password: Mapped[str] = mapped_column(String(100), nullable=False, comment="密码")
    nickname: Mapped[str | None] = mapped_column(String(50), comment="昵称")
    avatar: Mapped[str | None] = mapped_column(String(255), comment="头像")
    email: Mapped[str | None] = mapped_column(String(100), comment="邮箱")
    phone: Mapped[str | None] = mapped_column(String(20), comment="手机号")
    ding_token: Mapped[str | None] = mapped_column(String(255), comment="钉钉Token")
    ding_key: Mapped[str | None] = mapped_column(String(255), comment="钉钉key")
    status: Mapped[bool] = mapped_column(Boolean, default=True, comment="状态(0:禁用,1:启用)")
    dept_id: Mapped[int | None] = mapped_column(Integer, comment="部门ID")
    remark: Mapped[str | None] = mapped_column(String(255), comment="备注")
    create_time: Mapped[datetime] = mapped_column(
        DateTime,
        nullable=False,
        server_default=text("CURRENT_TIMESTAMP"),
        comment="创建时间"
    )
    update_time: Mapped[datetime] = mapped_column(
        DateTime,
        nullable=False,
        server_default=text("CURRENT_TIMESTAMP"),
        onupdate=text("CURRENT_TIMESTAMP"),
        comment="更新时间"
    )

    def __repr__(self):
        return f"<User(id={self.id}, username={self.username})>"

二、数据传输层设计

2.1 输入DTO规范

基础校验DTO

class UserBaseDTO(BaseModel):
    username: str = Field(
        ...,
        min_length=3,
        max_length=50,
        alias="userName",
        pattern=r"^[a-zA-Z0-9_]+$",
        description="用户名需包含3-50个字符（字母/数字/下划线）"
    )
    password: str = Field(..., min_length=6, description="密码")
    nickname: Optional[str] = Field(None, alias="nickName", max_length=50, description="昵称")
    avatar: Optional[str] = Field(None, max_length=255, description="头像")
    email: Optional[str] = Field(None, max_length=100, description="邮箱")
    phone: Optional[str] = Field(None, max_length=20, description="手机号")
    ding_token: Optional[str] = Field(None, alias="dingToken", max_length=255, description="钉钉Token")
    ding_key: Optional[str] = Field(None, alias="dingKey", max_length=255, description="钉钉Key")
    status: Optional[int] = Field(1, description="状态(0:禁用,1:启用)")
    dept_id: Optional[int] = Field(None, alias="deptId", description="部门ID")
    remark: Optional[str] = Field(None, max_length=255, description="备注")
    create_time: Optional[datetime] = Field(None, alias="createTime", description="创建时间")

    class Config:
        extra = "ignore"  # 禁止额外字段(默认)
        from_attributes = True  # 允许ORM对象转换(旧版alias: orm_mode)
        allow_population_by_field_name = True  # 允许别名/字段名双模式

其他专用DTO

class UserUpdateDTO(UserBaseDTO):
    id: Optional[int] = Field(...)
    update_time: Optional[datetime] = Field(None, alias="updateTime")
    role_ids: Optional[List[int]] = Field(None, alias="roleIds", description="角色ID")
    password: Optional[str] = Field(None, exclude=True)  # 改为可选

    class Config:
        extra = "ignore"
        from_attributes = True
        allow_population_by_field_name = True


class UserConditionDTO(PageDTO):
    username: Optional[str] = Field(None, alias="userName")
    nickname: Optional[str] = Field(None, alias="nickName")
    status: Optional[int] = None
    dept_id: Optional[int] = Field(None, alias="deptId")

    class Config:
        extra = "ignore"
        from_attributes = True
        allow_population_by_field_name = True

2.2 输出VO规范

基础VO模型

class SysUserBase(BaseModel):
    userName: str = Field(None, alias="username")
    nickName: str | None = Field(None, alias="nickname")
    email: str | None = None
    phone: str | None = None
    dingToken: str | None = Field(None, alias="ding_token")
    dingKey: str | None = Field(None, alias="ding_key")
    status: int = 1
    remark: str | None = None
    deptId: int | None = Field(None, alias="dept_id")

    class Config:
        from_attributes = True
        populate_by_name = True  # 启动别名

列表扩展VO

class UserCreate(SysUserBase):
    password: str


class UserUpdate(SysUserBase):
    password: str | None = None


class UserVO(SysUserBase):
    id: int
    avatar: str | None = None
    createTime: datetime | None = Field(None, alias="create_time")
    updateTime: datetime | None = Field(None, alias="update_time")

    class Config:
        from_attributes = True
        populate_by_name = True  # 添加这个配置


class UserListVo(UserVO):
    deptName: str | None = Field(None, alias="dept_name")
    roleNames: str | None = Field(None, alias="role_names")

    class Config:
        from_attributes = True
        populate_by_name = True  # 添加这个配置

三、转换关系矩阵

流程图构思

1. ‌数据库层‌

   • ‌InnoDB存储引擎‌：显示InnoDB图标，表示数据表do是使用InnoDB存储的。
   • ‌数据表do‌：显示一个表格图标，旁边标注表名do，并列出主要字段（如id, username, password, create_time等）。

2. ‌数据访问层（DAL）‌

   • ‌ORM框架‌：显示一个ORM框架的图标（如SQLAlchemy、Django ORM等），表示使用ORM来抽象数据库操作。
   • ‌数据模型‌：显示一个类图，代表与数据表do对应的ORM模型（如SysUser类）。

3. ‌业务逻辑层（BLL）‌

   • ‌服务/业务方法‌：显示一个方法或服务的图标，表示在这里进行数据转换和业务逻辑处理。
   • ‌DTO/VO转换‌：显示数据在DTO（数据传输对象）和VO（视图对象）之间的转换过程。

4. ‌表示层（UI/API）‌

   • ‌前端/API接口‌：显示一个前端页面或API接口的图标，表示数据最终展示给用户或通过API提供给其他服务。

四、config扩展一级pydantic V2.0建议

在Pydantic 2.0+版本中，配置方式已从传统的class Config迁移至model_config = ConfigDict()形式，以下是核心配置参数及使用规范：

示例：

class UserModel(BaseModel):
    name: str
    age: int

    model_config = ConfigDict(
        extra='forbid',
        frozen=True
    )

‌ 核心配置参数分类‌

‌字段处理控制‌

参数	作用	示例值
extra	控制额外字段处理策略	'forbid' '禁止额外字段' 'allow' '允许保留额外字段' 'ignore'‘静默忽略额外字段’
populate_by_name	允许通过字段名或别名填充数据	True/False
alias_generator	全局字段别名生成函数	lambda x: x.upper()

‌类型验证配置‌

参数	作用
arbitrary_types_allowed	是否允许非Pydantic原生类型（如自定义类）
strict	启用严格模式（禁用类型自动转换）
revalidate_instances	每次访问字段时重新验证数据

‌序列化与文档‌

参数	作用
json_encoders	自定义类型的JSON序列化方法（如{datetime: lambda v: v.timestamp()}）
json_schema_extra	扩展OpenAPI Schema（如添加example字段）

‌ORM集成‌

参数	作用
from_attributes	允许从ORM对象属性加载数据（旧版orm_mode的替代）