fastapi项目中数据流转架构设计规范

一、数据库层设计

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 = Trueallow_population_by_field_name = Trueclass UserConditionDTO(PageDTO):username: Optional[str] = Field(None, alias="userName")nickname: Optional[str] = Field(None, alias="nickName")status: Optional[int] = Nonedept_id: Optional[int] = Field(None, alias="deptId")class Config:extra = "ignore"from_attributes = Trueallow_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 = Nonephone: str | None = NonedingToken: str | None = Field(None, alias="ding_token")dingKey: str | None = Field(None, alias="ding_key")status: int = 1remark: str | None = NonedeptId: int | None = Field(None, alias="dept_id")class Config:from_attributes = Truepopulate_by_name = True  # 启动别名

列表扩展VO

class UserCreate(SysUserBase):password: strclass UserUpdate(SysUserBase):password: str | None = Noneclass UserVO(SysUserBase):id: intavatar: str | None = NonecreateTime: datetime | None = Field(None, alias="create_time")updateTime: datetime | None = Field(None, alias="update_time")class Config:from_attributes = Truepopulate_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 = Truepopulate_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: strage: intmodel_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的替代）