121 lines
4.0 KiB
Markdown
121 lines
4.0 KiB
Markdown
# 数据模型（Model）
|
||
|
||
数据模型是模块开发的第一步，用于定义数据库表结构。项目使用 `SQLAlchemy ORM`，模型类通过继承 `BaseModel` 自动获得通用字段和方法。
|
||
|
||
## 文件位置
|
||
|
||
```
|
||
src/modules/link/models.py
|
||
```
|
||
|
||
## 完整代码
|
||
|
||
```python
|
||
# +======================================================================
|
||
# | 模块: 友链数据模型层
|
||
# | 说明: 定义友链表结构，继承 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="排序")
|
||
```
|
||
|
||
## 代码解析
|
||
|
||
### 基类继承
|
||
|
||
```python
|
||
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 层进行。
|
||
:::
|
||
|
||
### 表名配置
|
||
|
||
```python
|
||
__tablename__ = DB_PREFIX + "link"
|
||
```
|
||
|
||
`DB_PREFIX` 从 `.env` 读取（默认 `tornado_`），最终表名为 `tornado_link`。所有业务表都使用此前缀，便于区分不同应用的同库表。
|
||
|
||
### 表注释
|
||
|
||
```python
|
||
__table_args__ = {"comment": "友情链接表"}
|
||
```
|
||
|
||
使用 `__table_args` 字典设置表注释，同步到数据库元数据。
|
||
|
||
### 字段定义
|
||
|
||
```python
|
||
name = Column(String(255), nullable=False, index=True, comment="链接名称")
|
||
```
|
||
|
||
| 参数 | 说明 |
|
||
|:----|:----|
|
||
| `String(255)` | 字段类型，VARCHAR(255) |
|
||
| `nullable=False` | 非空约束 |
|
||
| `index=True` | 创建索引，加速查询 |
|
||
| `comment` | 字段注释，同步到数据库 |
|
||
|
||
```python
|
||
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 端和数据库端默认值。模型只定义表结构，不包含业务逻辑。
|