数据模型（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）

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	已删除

开发要点

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

总结

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