103 lines
4.8 KiB
Markdown
103 lines
4.8 KiB
Markdown
# 3.2 数据库建表
|
||
|
||
:::tip 概述
|
||
建表是模块开发的第一步。所有表必须包含公共字段（id、软删除、审计字段），这是模型 Trait 自动处理的基础。
|
||
:::
|
||
|
||
## 公共字段规范
|
||
|
||
所有业务表必须包含以下公共字段：
|
||
|
||
```sql
|
||
-- 公共字段（每个表都必须包含）
|
||
id INT PRIMARY KEY AUTO_INCREMENT COMMENT '主键',
|
||
is_delete TINYINT(1) DEFAULT 0 COMMENT '软删除 0=正常 1=已删除',
|
||
create_user VARCHAR(50) DEFAULT '' COMMENT '创建人',
|
||
create_time DATETIME COMMENT '创建时间',
|
||
update_user VARCHAR(50) DEFAULT '' COMMENT '更新人',
|
||
update_time DATETIME COMMENT '更新时间'
|
||
```
|
||
|
||
:::warning 为什么必须包含这些字段？
|
||
- `is_delete`：`SoftDeleteFlagScope` 全局查询范围会自动过滤 `is_delete=1` 的数据（`SoftDeletesByFlag` Trait 注册）
|
||
- `create_user` / `create_time`：`HasAuditColumns` Trait 的 `creating` 事件自动填充
|
||
- `update_user` / `update_time`：`HasAuditColumns` Trait 的 `updating` 事件自动填充
|
||
- 表结构**不含** Laravel 默认的 `created_at` / `updated_at` 列，统一使用本项目的审计字段命名
|
||
:::
|
||
|
||
## 建表 SQL 示例（example 模块，摘自 `document/mysql/` 实际脚本）
|
||
|
||
```sql
|
||
CREATE TABLE laravel_example (
|
||
-- 主键
|
||
id INT NOT NULL AUTO_INCREMENT COMMENT '主键ID',
|
||
|
||
-- 业务字段
|
||
name VARCHAR(255) NOT NULL COMMENT '案例名称',
|
||
avatar VARCHAR(255) NULL DEFAULT NULL COMMENT '案例图片',
|
||
type INT NULL DEFAULT 0 COMMENT '案例类型：1-类型1 2-类型2 3-类型3 4-类型4',
|
||
status INT NULL DEFAULT 0 COMMENT '案例状态：1-在用 2-停用',
|
||
sort INT NULL DEFAULT 0 COMMENT '案例排序',
|
||
|
||
-- 公共字段（必须）
|
||
create_user VARCHAR(50) NULL DEFAULT NULL COMMENT '创建人',
|
||
create_time DATETIME NULL DEFAULT (now()) COMMENT '创建时间',
|
||
update_user VARCHAR(50) NULL DEFAULT NULL COMMENT '更新人',
|
||
update_time DATETIME NULL DEFAULT (now()) COMMENT '更新时间',
|
||
is_delete INT NULL DEFAULT 0 COMMENT '删除标识：0-正常 1-已删除',
|
||
|
||
-- 索引
|
||
PRIMARY KEY (id),
|
||
INDEX idx_think_level_is_delete (is_delete),
|
||
INDEX idx_think_level_name (name),
|
||
INDEX idx_think_level_status (status)
|
||
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci COMMENT='案例演示表';
|
||
```
|
||
|
||
:::tip 枚举注释写法
|
||
枚举字段的注释直接写成 `1-在用 2-停用` 格式，代码生成器据此自动解析选项（见 [10.4 表结构解析引擎](/zh/generator/parser.html)）。
|
||
:::
|
||
|
||
:::tip 表前缀
|
||
建表 SQL 中的表名**含** `laravel_` 前缀（与 `.env` 中 `DB_PREFIX` 一致）；模型层的 `$table` 只写不含前缀的 `example`，查询时由 Laravel 自动拼接前缀。
|
||
:::
|
||
|
||
## 字段与 Service 属性对应关系
|
||
|
||
（对照 `app/Services/ExampleService.php` 实际声明）
|
||
|
||
| 数据库字段 | 类型 | Service 属性 | 说明 |
|
||
|-----------|------|-----------|------|
|
||
| `name` | VARCHAR(255) | `pageLikeFields` + `uniqueFields` | LIKE 模糊搜索 + 名称唯一校验 |
|
||
| `status` | INT | `pageEqFields` + `serializeMaps` | 精确匹配 + 字典翻译（`example_status` → 补 `statusText`） |
|
||
| `type` | INT | —（普通表单/列表字段） | 注释含选项，前端按 `columns.ts` 渲染 |
|
||
| `sort` | INT | —（默认排序用基类 `pageOrderBy`） | 排序值 |
|
||
| `avatar` | VARCHAR(255) | —（前端 `UploadImg` 直传） | 图片路径字段 |
|
||
|
||
## 设计检查清单
|
||
|
||
| 检查项 | 说明 |
|
||
|--------|------|
|
||
| 公共字段齐全 | `id` / `is_delete` / 四个审计字段 |
|
||
| 字段小写下划线 | `category_id`、`create_time` |
|
||
| 枚举字段配字典 | 字段注释写明字典编码，便于生成器提取 |
|
||
| 模糊搜索字段建索引 | LIKE 查询字段建议加索引 |
|
||
| 需要唯一性的字段 | 在 Service 配置 `uniqueFields`（不是数据库唯一索引，软删除场景更安全） |
|
||
|
||
## 常见字段类型参考
|
||
|
||
| 用途 | 推荐类型 | 示例 |
|
||
|------|----------|------|
|
||
| 主键 | `INT AUTO_INCREMENT` | `id INT PRIMARY KEY AUTO_INCREMENT` |
|
||
| 外键 | `INT DEFAULT 0` | `category_id INT DEFAULT 0` |
|
||
| 短文本 | `VARCHAR(n)` | `name VARCHAR(200)` |
|
||
| 长文本 | `TEXT` | `content TEXT` |
|
||
| 布尔值 | `TINYINT(1)` | `status TINYINT(1) DEFAULT 1` |
|
||
| 整数 | `INT` | `sort INT DEFAULT 0` |
|
||
| 日期时间 | `DATETIME` | `create_time DATETIME` |
|
||
| 文件路径 | `VARCHAR(500)` | `avatar VARCHAR(500)` |
|
||
|
||
:::tip
|
||
本项目 `database/migrations/` 为空，建表后**直接执行 SQL**（或在已有数据库上 `ALTER TABLE`），无需迁移。多数据库脚本见 [2.5 数据库初始化](/zh/quickstart/database-init.html)。
|
||
:::
|