127 lines
4.6 KiB
Markdown
127 lines
4.6 KiB
Markdown
# 数据模型（Model）
|
||
|
||
数据模型是模块开发的第一步，用于定义数据库表结构。项目使用 `SQLAlchemy ORM`，模型类通过继承基类自动获得通用字段和方法。
|
||
|
||
## 文件位置
|
||
|
||
```
|
||
src/modules/system/position/models.py
|
||
```
|
||
|
||
## 完整代码
|
||
|
||
```python
|
||
from sqlalchemy import Column, String, Integer, text
|
||
|
||
from core.base_db import base_db
|
||
from core.base_model import base_model
|
||
from core.config import DB_PREFIX
|
||
|
||
|
||
class Position(base_model, base_db):
|
||
"""岗位模型类"""
|
||
# 表名配置
|
||
__tablename__ = DB_PREFIX + "position"
|
||
__table_comment__ = "岗位表"
|
||
|
||
# 业务字段定义
|
||
# 岗位名称
|
||
name = Column(String(255), nullable=False, index=True, comment="岗位名称")
|
||
# 岗位状态：1-在用 2-停用
|
||
status = Column(Integer, default=0, server_default=text('0'), index=True, comment="岗位状态：1-在用 2-停用")
|
||
# 岗位排序
|
||
sort = Column(Integer, default=0, server_default=text('0'), comment="岗位排序")
|
||
|
||
def __repr__(self):
|
||
"""返回岗位名称作为字符串表示"""
|
||
return '岗位：{}'.format(self.name)
|
||
```
|
||
|
||
## 代码解析
|
||
|
||
### 基类继承
|
||
|
||
```python
|
||
class Position(base_model, base_db):
|
||
```
|
||
|
||
| 基类 | 来源 | 提供能力 |
|
||
|:----|:----|:----|
|
||
| `base_model` | `core/base_model.py` | 通用字段：id、create_user、create_time、update_user、update_time、is_delete |
|
||
| `base_db` | `core/base_db.py` | `save()` 持久化方法、`delete()` 删除方法、`to_dict()` 序列化方法 |
|
||
|
||
### 表名配置
|
||
|
||
```python
|
||
__tablename__ = DB_PREFIX + "position"
|
||
```
|
||
|
||
`DB_PREFIX` 从 `.env` 读取（默认 `fastapi_`），最终表名为 `fastapi_position`。所有业务表都使用此前缀，便于区分框架表与业务表。
|
||
|
||
### 字段定义
|
||
|
||
```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'), index=True, comment="岗位状态：1-在用 2-停用")
|
||
```
|
||
|
||
`default=0` 是 Python 端默认值，`server_default=text('0')` 是数据库端默认值。两者都设置可确保无论通过 ORM 还是直接 SQL 插入，都能正确赋默认值。
|
||
|
||
### 枚举值约定
|
||
|
||
项目中状态字段统一使用整数枚举：
|
||
|
||
| 值 | 含义 |
|
||
|:----|:----|
|
||
| 1 | 启用 / 在用 |
|
||
| 2 | 停用 / 禁用 |
|
||
|
||
软删除字段 `is_delete` 由基类提供：`0` = 正常，`1` = 已删除。
|
||
|
||
## 数据表 DDL（参考）
|
||
|
||
模型定义对应的 MySQL 建表语句：
|
||
|
||
```sql
|
||
CREATE TABLE `fastapi_position` (
|
||
`name` varchar(255) CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci NOT NULL COMMENT '岗位名称',
|
||
`status` int DEFAULT '0' COMMENT '岗位状态：1-在用 2-停用',
|
||
`sort` int DEFAULT '0' COMMENT '岗位排序',
|
||
`id` int NOT NULL AUTO_INCREMENT COMMENT '主键ID',
|
||
`create_user` varchar(50) CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci DEFAULT NULL COMMENT '创建人',
|
||
`create_time` datetime DEFAULT (now()) COMMENT '创建时间',
|
||
`update_user` varchar(50) CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci DEFAULT NULL COMMENT '更新人',
|
||
`update_time` datetime DEFAULT (now()) COMMENT '更新时间',
|
||
`is_delete` int DEFAULT '0' COMMENT '删除标识：0-正常 1-已删除',
|
||
PRIMARY KEY (`id`) USING BTREE,
|
||
KEY `idx_fastapi_position_name` (`name`) USING BTREE,
|
||
KEY `idx_fastapi_position_status` (`status`) USING BTREE,
|
||
KEY `idx_fastapi_position_is_delete` (`is_delete`) USING BTREE
|
||
) ENGINE=InnoDB AUTO_INCREMENT=0 DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci ROW_FORMAT=DYNAMIC COMMENT='岗位表';
|
||
```
|
||
|
||
:::tip 温馨提示
|
||
实际开发中不需要手写 DDL。模型定义完成后，框架会通过 `Base.metadata.create_all()` 自动建表，或通过 `alembic revision --autogenerate` 生成迁移脚本。
|
||
:::
|
||
|
||
## 开发要点
|
||
|
||
1. **业务字段仅定义差异部分**：通用字段（id、时间、软删除等）由基类自动提供
|
||
2. **表名必须加 `DB_PREFIX` 前缀**：保持命名一致性
|
||
3. **合理使用索引**：查询频繁的字段（如 name、status）设置 `index=True`
|
||
4. **同时设置 `default` 和 `server_default`**：确保 ORM 和直 SQL 两种场景都能正确赋默认值
|
||
|
||
## 总结
|
||
|
||
数据模型继承 `base_model`（公共字段）和 `base_db`（save/delete 方法），表名必须加 `DB_PREFIX` 前缀。查询频繁的字段设置索引，同时设置 `default` 和 `server_default` 确保 ORM 和直 SQL 两种场景都能正确赋默认值。
|