数据模型（Model）

数据模型是模块开发的第一步，用于定义数据库表结构。项目使用 SQLAlchemy ORM，模型类通过继承 BaseModel 自动获得通用字段和方法。

文件位置

src/modules/link/models.py

完整代码

# +======================================================================
# | 模块: 友链数据模型层
# | 说明: 定义友链表结构，继承 BaseModel 获得通用字段与序列化能力
# +======================================================================
"""友链数据模型。"""

from sqlalchemy import Column, Integer, String, text

from config.database import DB_PREFIX
from core.base_model import BaseModel


class Link(BaseModel):
    """友情链接模型"""
    __tablename__ = DB_PREFIX + "link"
    __table_args__ = {"comment": "友情链接表"}

    # 链接名称
    name = Column(String(255), nullable=False, index=True, comment="链接名称")
    # 链接类型
    type = Column(String(50), default="", comment="链接类型")
    # 链接来源
    form = Column(String(50), default="", comment="链接来源")
    # 链接图片
    image = Column(String(500), default="", comment="链接图片")
    # 链接地址
    url = Column(String(500), default="", comment="链接地址")
    # 状态：0-正常 1-停用
    status = Column(Integer, default=0, server_default=text("0"), comment="状态")
    # 排序
    sort = Column(Integer, default=0, server_default=text("0"), comment="排序")

代码解析

基类继承

class Link(BaseModel):

基类	来源	提供能力
`BaseModel`	`core/base_model.py`	通用字段：id、create_user、create_time、update_user、update_time、is_delete；`to_dict()` 序列化方法（自动排除 password/salt/is_delete）

:::tip BaseModel 说明 BaseModel 是所有业务模型的基类，提供6个通用审计字段和 to_dict() 序列化方法。模型实例不暴露 save()/delete() 方法，数据操作通过 Repository 层进行。 :::

表名配置

__tablename__ = DB_PREFIX + "link"

DB_PREFIX 从 .env 读取（默认 tornado_），最终表名为 tornado_link。所有业务表都使用此前缀，便于区分不同应用的同库表。

表注释

__table_args__ = {"comment": "友情链接表"}

使用 __table_args 字典设置表注释，同步到数据库元数据。

字段定义

name = Column(String(255), nullable=False, index=True, comment="链接名称")

参数	说明
`String(255)`	字段类型，VARCHAR(255)
`nullable=False`	非空约束
`index=True`	创建索引，加速查询
`comment`	字段注释，同步到数据库

status = Column(Integer, default=0, server_default=text("0"), comment="状态")

default=0 是 Python 端默认值，server_default=text("0") 是数据库端默认值。两者都设置可确保无论通过 ORM 还是直接 SQL 插入，都能正确赋默认值。

枚举值约定

状态字段使用 0 和 1 而非 1 和 2：

字段	值	含义
`status`	`0`	正常
`status`	`1`	停用
`is_delete`	`0`	未删除
`is_delete`	`1`	已删除

开发要点

所有模型继承 BaseModel：自动获得通用字段和序列化能力
表名必须加 DB_PREFIX 前缀：DB_PREFIX + "表名"
使用 __table_args__ 设置表注释：字典格式 {"comment": "表注释"}
查询频繁的字段设置索引：index=True
同时设置 default 和 server_default：ORM 和直 SQL 都能正确赋默认值
模型不暴露 save/delete 方法：数据操作通过 Repository 层进行

总结

数据模型通过继承 BaseModel 获得通用审计字段和序列化能力。表名使用 DB_PREFIX 前缀，字段定义同时设置 Python 端和数据库端默认值。模型只定义表结构，不包含业务逻辑。

4.0 KiB Raw Blame History Unescape Escape