签入版本
This commit is contained in:
@@ -1,23 +1,27 @@
|
||||
# 4.7 横切机制
|
||||
|
||||
:::tip 概述
|
||||
横切机制是 BaseLogic/BaseModel 内置的自动处理能力，开发者通过属性配置启用，无需手动编写处理代码。项目共有 9 种横切机制，覆盖数据转换、文件处理、校验、权限、隔离等维度。
|
||||
横切机制是 `BaseService` / 模型 Trait 内置的自动处理能力，开发者通过属性配置启用，无需手动编写处理代码。项目共有 9 种横切机制，覆盖数据转换、文件处理、校验、权限、隔离等维度；参数格式校验则由 HTTP 入口的 FormRequest 承担。
|
||||
:::
|
||||
|
||||
## 横切机制总览
|
||||
|
||||
| 机制 | 配置位置 | 配置属性 | 触发时机 |
|
||||
|------|---------|---------|---------|
|
||||
| 驼峰/下划线转换 | `config/api.php` | `camel_snake_convert` | 请求入、响应出 |
|
||||
| 文件字段处理 | Logic | `fileFields` + `fileSaveDir` | add/update 写入，detail/page 读取 |
|
||||
| 多文件字段处理 | Logic | `multiFileFields` + `fileSaveDir` | add/update 写入，detail/page 读取 |
|
||||
| 富文本占位符 | Logic | `contentFields` | add/update 写入，detail/page 读取 |
|
||||
| 枚举显示名翻译 | Logic | `serializeMaps` | detail/page 查询后 |
|
||||
| 自动参数校验 | Logic | `validateClass` | add/update 前 |
|
||||
| 唯一性校验 | Logic | `uniqueFields` | add/update 时 |
|
||||
| 数据权限过滤 | Logic | `dataScopeUserField` / `dataScopeDeptField` | 查询时 |
|
||||
| 租户隔离 | Logic（继承 BaseTenantLogic） | `tenantScopeField` | 查询时 + 新增时 |
|
||||
| 审计字段 + 软删除 | BaseModel | 自动生效 | 所有 CRUD |
|
||||
| 驼峰/下划线转换 | `config/api.php` | `camel_snake_convert` | 查询参数入、响应出 |
|
||||
| 文件字段处理 | Service（需 `use HasFileProcessing`） | `fileFields` + `fileSaveDir` | add/update 写入，detail/page 读取 |
|
||||
| 多文件字段处理 | Service（需 `use HasFileProcessing`） | `multiFileFields` + `fileSaveDir` | add/update 写入，detail/page 读取 |
|
||||
| 富文本占位符 | Service（需 `use HasFileProcessing`） | `contentFields` | add/update 写入，detail/page 读取 |
|
||||
| 配置值类型化处理 | Service（需 `use HasConfigValueProcessing`） | 记录的 `type` + `fileSaveDir` | add/update 写入，detail/webIndex 读取 |
|
||||
| 字典显示名翻译 | Service（需 `use HasSerializeMaps`） | `serializeMaps` | detail/page 查询后 |
|
||||
| 唯一性校验 | Service（需 `use HasUniqueCheck`） | `uniqueFields` | add/update 时 |
|
||||
| 数据权限过滤 | Service（需 `use HasDataScope`） | `dataScopeUserField` / `dataScopeDeptField` | 查询时 |
|
||||
| 租户隔离 | `BaseTenantService`（自动 use HasDataScope） | `tenantScopeField` | 查询时 + 新增时 |
|
||||
| 审计字段 + 软删除 | 模型 Trait | 自动生效 | 所有 CRUD |
|
||||
|
||||
:::tip 参数格式校验在哪里？
|
||||
不在上表——Laravel 将其前置到 HTTP 入口：控制器方法**类型注入 FormRequest** 即自动校验（见 [3.4 FormRequest 验证器](/zh/guide/validator.html)）。Service 只做业务规则（唯一性、状态依赖）。
|
||||
:::
|
||||
|
||||
## 1. 驼峰/下划线自动转换
|
||||
|
||||
@@ -29,52 +33,61 @@
|
||||
请求方向（前端 → 数据库）：
|
||||
前端传参：{ userName: "admin", createTime: "2026-01-01" }
|
||||
│
|
||||
▼ BaseLogic::convertQueryParams()
|
||||
│ array_camel_to_snake($params, $except)
|
||||
▼ HasQueryScopes::convertQueryParams()
|
||||
│ camel_to_snake() 逐键转换（排除分页/排序参数）
|
||||
▼
|
||||
数据库操作：WHERE user_name = 'admin' AND create_time = '2026-01-01'
|
||||
|
||||
表单入参（add/update 写入）：
|
||||
$request->validated() ← 格式校验，原样传递（camelCase 键名）
|
||||
│
|
||||
▼ HasCrudOperations::doAdd / doUpdate 入口
|
||||
│ array_camel_to_snake() 统一转换
|
||||
▼
|
||||
入库数据：snake_case 键名（非表字段由 filterTableFields 过滤）
|
||||
|
||||
响应方向（数据库 → 前端）：
|
||||
数据库数据：{ user_name: "admin", create_time: "2026-01-01" }
|
||||
│
|
||||
▼ Result::convertData()
|
||||
│ array_snake_to_camel($data)
|
||||
▼ Result::success() / page()
|
||||
│ convert_to_camel() / convert_list_to_camel()
|
||||
▼
|
||||
前端接收：{ userName: "admin", createTime: "2026-01-01" }
|
||||
```
|
||||
|
||||
### 排除项（不参与转换）
|
||||
### 排除项（不参与请求方向转换）
|
||||
|
||||
以下参数保持 camelCase，不转为 snake_case：
|
||||
以下参数保持 camelCase，不转为 snake_case（`config('api.convert_except_params')`）：
|
||||
|
||||
- `pageNo`、`pageSize` — 分页参数
|
||||
- `orderField`、`orderType` — 排序参数
|
||||
- `fields` — 字段过滤参数
|
||||
|
||||
### 配置开关
|
||||
|
||||
```php
|
||||
// config/api.php
|
||||
'camel_snake_convert' => env('api.camel_snake_convert', true),
|
||||
'camel_snake_convert' => env('API_CAMEL_SNAKE_CONVERT', true),
|
||||
```
|
||||
|
||||
```ini
|
||||
# .env
|
||||
API.CAMEL_SNAKE_CONVERT = true # 开启（默认）
|
||||
API.CAMEL_SNAKE_CONVERT = false # 关闭（请求保持驼峰，响应保持下划线）
|
||||
API_CAMEL_SNAKE_CONVERT=true # 开启（默认）
|
||||
API_CAMEL_SNAKE_CONVERT=false # 关闭（请求保持驼峰，响应保持下划线）
|
||||
```
|
||||
|
||||
:::tip 开发者无需手动处理
|
||||
驼峰/下划线转换完全自动，开发者只需在前端用 camelCase，在数据库用 snake_case，框架自动处理双向转换。
|
||||
驼峰/下划线转换完全自动，开发者只需在前端用 camelCase，在数据库用 snake_case，框架自动处理双向转换。需要原样返回时用 `Result::success($data, $msg, true)`（`$raw=true`）。
|
||||
:::
|
||||
|
||||
## 2. 文件字段自动处理
|
||||
|
||||
**配置方式**：Logic 中设置 `fileFields` 和 `fileSaveDir`
|
||||
**配置方式**：Service 中 `use HasFileProcessing` 并设置 `fileFields` 和 `fileSaveDir`
|
||||
|
||||
```php
|
||||
class ArticleLogic extends BaseTenantLogic
|
||||
class ArticleService extends BaseTenantService
|
||||
{
|
||||
use HasFileProcessing, /* 其它 Trait */;
|
||||
|
||||
protected array $fileFields = ['cover', 'attachment'];
|
||||
protected string $fileSaveDir = 'article';
|
||||
}
|
||||
@@ -87,21 +100,21 @@ class ArticleLogic extends BaseTenantLogic
|
||||
│
|
||||
▼ processFileFieldsOnSave()
|
||||
│ 1. 检测字段值是否为临时文件 URL
|
||||
│ 2. 调用 save_file() 将临时文件迁移到正式目录
|
||||
│ 2. 将临时文件迁移到正式目录（fileSaveDir）
|
||||
│ 3. 去掉域名，只存储相对路径
|
||||
▼
|
||||
入库存储：cover = "/uploads/article/20260922/abc123.jpg"
|
||||
入库存储：cover = "article/20261002/abc123.jpg"
|
||||
```
|
||||
|
||||
### 读取时（detail/pageList/allList）
|
||||
|
||||
```text
|
||||
数据库读取：cover = "/uploads/article/20260922/abc123.jpg"
|
||||
数据库读取：cover = "article/20261002/abc123.jpg"
|
||||
│
|
||||
▼ processFileFieldsOnRead()
|
||||
│ 调用 get_file_url() 补全域名
|
||||
│ 补全完整访问 URL（config/file.php 的 domain_url）
|
||||
▼
|
||||
前端接收：cover = "https://cdn.example.com/uploads/article/20260922/abc123.jpg"
|
||||
前端接收：cover = "https://cdn.example.com/uploads/article/20261002/abc123.jpg"
|
||||
```
|
||||
|
||||
### 多个单文件字段
|
||||
@@ -111,18 +124,19 @@ protected array $fileFields = ['cover', 'avatar', 'attachment'];
|
||||
// 三个字段都会自动处理
|
||||
```
|
||||
|
||||
:::warning 未 use Trait 时为空操作
|
||||
`BaseService` 中对应方法是**占位实现**（直接 `return $data`）。未 `use HasFileProcessing` 时文件字段不会被处理——这是刻意设计（见 [4.6 核心基类体系](/zh/architecture/base-classes.html)「占位覆盖机制」）。
|
||||
:::
|
||||
|
||||
## 3. 多文件字段自动处理
|
||||
|
||||
当一个字段存储多个文件URL（逗号分隔）时，使用 `multiFileFields`：
|
||||
当一个字段存储多个文件 URL（逗号分隔）时，使用 `multiFileFields`：
|
||||
|
||||
**配置方式**：Logic 中设置 `multiFileFields`（复用 `fileSaveDir`）
|
||||
**配置方式**：Service 中设置 `multiFileFields`（复用 `fileSaveDir`）
|
||||
|
||||
```php
|
||||
class ArticleLogic extends BaseTenantLogic
|
||||
{
|
||||
protected array $multiFileFields = ['images', 'attachments'];
|
||||
protected string $fileSaveDir = 'article';
|
||||
}
|
||||
protected array $multiFileFields = ['images', 'attachments'];
|
||||
protected string $fileSaveDir = 'article';
|
||||
```
|
||||
|
||||
**写入时（add/update）**
|
||||
@@ -132,34 +146,29 @@ class ArticleLogic extends BaseTenantLogic
|
||||
│
|
||||
▼ processMultiFileFieldsOnSave()
|
||||
│ 1. 按逗号拆分为数组
|
||||
│ 2. 逐个调用 save_file() 迁移临时文件并去掉域名
|
||||
│ 2. 逐个迁移临时文件并去掉域名
|
||||
│ 3. 重新用逗号拼接
|
||||
▼
|
||||
入库存储：images = "article/20260922/a.png,article/20260922/b.png"
|
||||
入库存储：images = "article/20261002/a.png,article/20261002/b.png"
|
||||
```
|
||||
|
||||
**读取时（detail/pageList/allList）**
|
||||
|
||||
```text
|
||||
数据库读取：images = "article/20260922/a.png,article/20260922/b.png"
|
||||
数据库读取：images = "article/20261002/a.png,article/20261002/b.png"
|
||||
│
|
||||
▼ processMultiFileFieldsOnRead()
|
||||
│ 1. 按逗号拆分为数组
|
||||
│ 2. 逐个调用 get_file_url() 补全域名
|
||||
│ 3. 重新用逗号拼接
|
||||
│ 按逗号拆分 → 逐个补全域名 → 重新拼接
|
||||
▼
|
||||
前端接收：images = "http://cdn.example.com/article/20260922/a.png,http://cdn.example.com/article/20260922/b.png"
|
||||
前端接收：images = "https://cdn.example.com/.../a.png,https://cdn.example.com/.../b.png"
|
||||
```
|
||||
|
||||
## 4. 富文本占位符机制
|
||||
|
||||
**配置方式**：Logic 中设置 `contentFields`
|
||||
**配置方式**：Service 中设置 `contentFields`
|
||||
|
||||
```php
|
||||
class ArticleLogic extends BaseTenantLogic
|
||||
{
|
||||
protected array $contentFields = ['content'];
|
||||
}
|
||||
protected array $contentFields = ['content'];
|
||||
```
|
||||
|
||||
### 写入时
|
||||
@@ -178,35 +187,32 @@ class ArticleLogic extends BaseTenantLogic
|
||||
### 读取时
|
||||
|
||||
```text
|
||||
数据库读取：content = '<p>文章内容</p><img src="[IMG_URL]/uploads/article/img001.jpg">'
|
||||
数据库读取：content 中含 [IMG_URL] 占位符
|
||||
│
|
||||
▼ processContentFieldsOnRead()
|
||||
│ 将 [IMG_URL] 替换为配置的实际域名
|
||||
▼
|
||||
前端接收：content = '<p>文章内容</p><img src="https://cdn.example.com/uploads/article/img001.jpg">'
|
||||
前端接收：content 中 img src 为完整域名 URL
|
||||
```
|
||||
|
||||
### 好处
|
||||
|
||||
域名变更时只需修改 `config/file.php` 中的 `domain_url`，已存储的内容无需逐条更新。
|
||||
域名变更时只需修改 `.env` 中的 `FILE_DOMAIN_URL`，已存储的内容无需逐条更新。
|
||||
|
||||
## 5. 枚举显示名翻译
|
||||
## 5. 字典显示名翻译
|
||||
|
||||
**配置方式**：Logic 中设置 `serializeMaps`
|
||||
**配置方式**：Service 中 `use HasSerializeMaps` 并设置 `serializeMaps`
|
||||
|
||||
```php
|
||||
class ArticleLogic extends BaseTenantLogic
|
||||
{
|
||||
/**
|
||||
* 枚举显示名映射
|
||||
*
|
||||
* @var array
|
||||
*/
|
||||
protected array $serializeMaps = [
|
||||
'status' => 'article_status',
|
||||
'type' => 'article_type',
|
||||
];
|
||||
}
|
||||
/**
|
||||
* 字典翻译配置：[字段 => 字典编码]
|
||||
*
|
||||
* @var array<string, string>
|
||||
*/
|
||||
protected array $serializeMaps = [
|
||||
'status' => 'article_status',
|
||||
'type' => 'article_type',
|
||||
];
|
||||
```
|
||||
|
||||
### 工作原理
|
||||
@@ -214,84 +220,34 @@ class ArticleLogic extends BaseTenantLogic
|
||||
```text
|
||||
数据库查询：{ status: 1, type: 0 }
|
||||
│
|
||||
▼ processSerializeMaps()
|
||||
│ DictService::getText('article_status', 1) → '已发布'
|
||||
│ DictService::getText('article_type', 0) → '原创'
|
||||
▼ processSerializeMapsList()
|
||||
│ DictCacheService 批量取词（两级缓存，同一请求只查一次）
|
||||
│ getText('article_status', 1) → '已发布'
|
||||
│ getText('article_type', 0) → '原创'
|
||||
▼
|
||||
前端接收：{ status: 1, statusText: '已发布', type: 0, typeText: '原创' }
|
||||
```
|
||||
|
||||
### 字段名映射
|
||||
|
||||
当字典编码与字段名不同时，可指定映射：
|
||||
当字典编码与字段名不同时，直接在映射中指定：
|
||||
|
||||
```php
|
||||
/**
|
||||
* 枚举显示名映射
|
||||
*
|
||||
* @var array
|
||||
*/
|
||||
protected array $serializeMaps = [
|
||||
'gender' => 'gender',
|
||||
'status' => 'user_status',
|
||||
];
|
||||
```
|
||||
|
||||
## 6. 自动参数校验
|
||||
字典数据变更时 `DictItemObserver` 自动清除对应缓存，保证翻译不过期。
|
||||
|
||||
**配置方式**：Logic 中设置 `validateClass`
|
||||
## 6. 唯一性校验
|
||||
|
||||
**配置方式**：Service 中 `use HasUniqueCheck` 并设置 `uniqueFields`
|
||||
|
||||
```php
|
||||
class ArticleLogic extends BaseTenantLogic
|
||||
{
|
||||
protected string $validateClass = \app\validate\ArticleValidate::class;
|
||||
}
|
||||
```
|
||||
|
||||
### 工作原理
|
||||
|
||||
```text
|
||||
add() 流程：
|
||||
beforeAdd($data) → validateData($data, 'add') → 后续入库
|
||||
|
||||
update() 流程：
|
||||
beforeUpdate($id, $data) → validateData($data, 'update', $id) → 后续入库
|
||||
```
|
||||
|
||||
### 验证器示例
|
||||
|
||||
```php
|
||||
class ArticleValidate extends Validate
|
||||
{
|
||||
protected $rule = [
|
||||
'title' => 'require|max:200',
|
||||
];
|
||||
protected $message = [
|
||||
'title.require' => '文章标题不能为空',
|
||||
];
|
||||
protected $scene = [
|
||||
'add' => ['title'],
|
||||
'update' => ['title'],
|
||||
];
|
||||
}
|
||||
```
|
||||
|
||||
校验失败抛出 `ValidateException`，由 `ExceptionHandle` 统一返回 `{"code":1, "msg":"参数验证失败", "data":"文章标题不能为空"}`。
|
||||
|
||||
### 覆盖范围
|
||||
|
||||
无论是 Controller 通过 `_add`/`_edit` 调用，还是 `import` 等内部调用都会触发校验。
|
||||
|
||||
## 7. 唯一性校验
|
||||
|
||||
**配置方式**：Logic 中设置 `uniqueFields`
|
||||
|
||||
```php
|
||||
class UserLogic extends BaseTenantLogic
|
||||
{
|
||||
// 全局唯一
|
||||
protected array $uniqueFields = ['username', 'mobile'];
|
||||
}
|
||||
// 全局唯一
|
||||
protected array $uniqueFields = ['username', 'mobile'];
|
||||
```
|
||||
|
||||
### 两种规则
|
||||
@@ -300,7 +256,7 @@ class UserLogic extends BaseTenantLogic
|
||||
// 字符串 — 全局唯一
|
||||
protected array $uniqueFields = ['username', 'mobile'];
|
||||
|
||||
// 数组 — 分组内唯一
|
||||
// 数组 — 分组内唯一：[唯一字段, 分组字段]
|
||||
protected array $uniqueFields = [
|
||||
'username', // username 全局唯一
|
||||
['code', 'pid'], // code 在同一 pid 下唯一
|
||||
@@ -312,57 +268,45 @@ protected array $uniqueFields = [
|
||||
```text
|
||||
add() 时：
|
||||
checkUnique($data)
|
||||
→ SELECT * FROM think_user WHERE username = 'admin'
|
||||
→ 存在 → throw new \Exception('用户名已存在')
|
||||
→ SELECT * FROM laravel_user WHERE username = 'admin'
|
||||
→ 存在 → throw new BizException('用户名已存在')
|
||||
|
||||
update() 时：
|
||||
checkUnique($data, $excludeId)
|
||||
→ SELECT * FROM think_user WHERE username = 'admin' AND id <> 42
|
||||
→ 存在 → throw new \Exception('用户名已存在')
|
||||
→ SELECT * FROM laravel_user WHERE username = 'admin' AND id <> 42
|
||||
→ 存在 → throw new BizException('用户名已存在')
|
||||
```
|
||||
|
||||
- 值为空时跳过（FormRequest 的 `required` 规则兜底）
|
||||
- `BizException` 中断 `DB::transaction` 事务并回滚，由 Handler 转为 `code=1` 响应
|
||||
|
||||
### 错误提示自定义
|
||||
|
||||
默认提示格式："字段中文名 + 已存在"。可通过重写 `getFieldLabel()` 自定义：
|
||||
默认提示格式："字段中文名 + 已存在"。中文名查找顺序：`$fieldLabels` 属性 → Trait 内置映射 → 字段名本身：
|
||||
|
||||
```php
|
||||
protected function getFieldLabel(string $field): string
|
||||
class RoleService extends BaseTenantService
|
||||
{
|
||||
$map = [
|
||||
'username' => '用户名',
|
||||
'mobile' => '手机号',
|
||||
'code' => '编码',
|
||||
// 自定义字段中文名映射
|
||||
protected array $fieldLabels = [
|
||||
'code' => '角色编码',
|
||||
'name' => '角色名称',
|
||||
];
|
||||
return $map[$field] ?? $field;
|
||||
}
|
||||
```
|
||||
|
||||
## 8. 数据权限过滤
|
||||
## 7. 数据权限过滤
|
||||
|
||||
**配置方式**：Logic 中设置 `dataScopeUserField` 和/或 `dataScopeDeptField`
|
||||
**配置方式**：Service 中设置 `dataScopeUserField` 和/或 `dataScopeDeptField`（需 `use HasDataScope`）
|
||||
|
||||
```php
|
||||
class ArticleLogic extends BaseTenantLogic
|
||||
{
|
||||
/**
|
||||
* 数据权限：归属字段名（用于按创建人过滤）
|
||||
*
|
||||
* @var string
|
||||
*/
|
||||
protected string $dataScopeUserField = 'create_user';
|
||||
|
||||
/**
|
||||
* 数据权限：部门关联字段名（用于按部门过滤）
|
||||
*
|
||||
* @var string
|
||||
*/
|
||||
protected string $dataScopeDeptField = 'dept_id';
|
||||
}
|
||||
protected string $dataScopeUserField = 'create_user'; // 按创建人过滤
|
||||
protected string $dataScopeDeptField = 'dept_id'; // 按部门过滤
|
||||
```
|
||||
|
||||
### 三种权限范围
|
||||
|
||||
由角色表 `think_role` 的 `data_scope` 字段决定：
|
||||
数据范围由 `HasDataScope::getRoleDataScope()` 按角色解析。当前 `laravel_role` 表不含 `data_scope` 字段，读取缺省为 1——所有角色按全部数据处理：
|
||||
|
||||
```text
|
||||
┌─────────────────────────────────────────────────────────┐
|
||||
@@ -376,7 +320,7 @@ class ArticleLogic extends BaseTenantLogic
|
||||
│ │ A │ │ B │ │███│ │ D │ │ E │ ← 只看到本部门数据 │
|
||||
│ └───┘ └───┘ └───┘ └───┘ └───┘ │
|
||||
├─────────────────────────────────────────────────────────┤
|
||||
│ data_scope = 3 → 仅本人数据 │
|
||||
│ data_scope = 3 → 仅本人数据（无角色用户默认） │
|
||||
│ ┌───┐ ┌───┐ ┌───┐ ┌───┐ ┌───┐ │
|
||||
│ │ A │ │ B │ │███│ │ D │ │ E │ ← 只看到自己创建的数据 │
|
||||
│ └───┘ └───┘ └───┘ └───┘ └───┘ │
|
||||
@@ -387,25 +331,25 @@ class ArticleLogic extends BaseTenantLogic
|
||||
|
||||
```text
|
||||
查询时 applyDataScope()：
|
||||
1. 获取当前用户角色 ID
|
||||
2. 查询角色的 data_scope
|
||||
1. 获取当前用户角色 ID（无角色 → 按 3 仅本人）
|
||||
2. 读取角色数据范围（当前无该字段 → 按 1 全部）
|
||||
3. scope=1 → 不过滤
|
||||
4. scope=2 → WHERE dept_id = 当前用户部门ID
|
||||
5. scope=3 → WHERE create_user = 当前用户名
|
||||
4. scope=2 → WHERE dept_id = 当前用户部门ID（需声明 dataScopeDeptField）
|
||||
5. scope=3 → WHERE create_user = 当前用户名（需声明 dataScopeUserField）
|
||||
```
|
||||
|
||||
:::warning 无角色用户
|
||||
无角色时默认按"仅本人"（scope=3）处理。
|
||||
:::
|
||||
|
||||
## 9. 租户隔离
|
||||
## 8. 租户隔离
|
||||
|
||||
**配置方式**：继承 `BaseTenantLogic`（自动设置 `tenantScopeField = 'tenant_id'`）
|
||||
**配置方式**：继承 `BaseTenantService`（自动 `use HasDataScope` 并设置 `tenantScopeField = 'tenant_id'`）
|
||||
|
||||
```php
|
||||
class ArticleLogic extends BaseTenantLogic // 继承 BaseTenantLogic 即启用
|
||||
class ArticleService extends BaseTenantService
|
||||
{
|
||||
// tenantScopeField 已由基类设为 'tenant_id'，无需再声明
|
||||
// tenantScopeField 基类默认即为 'tenant_id'，无需再声明
|
||||
}
|
||||
```
|
||||
|
||||
@@ -415,48 +359,48 @@ class ArticleLogic extends BaseTenantLogic // 继承 BaseTenantLogic 即启用
|
||||
|------|------|---------|
|
||||
| **查询时** | 自动叠加 `WHERE tenant_id = 当前租户ID` | `applyTenantScope()` |
|
||||
| **新增时** | 自动填充 `tenant_id` 字段 | `processTenantId()` |
|
||||
| **超级管理员**（tenantId=0） | 查询不过滤，可跨租户查看 | 条件判断跳过 |
|
||||
| **超级管理员新增** | 自动代入默认租户（tenant_id=1） | 读取配置 `tenant.default_tenant_id` |
|
||||
| **平台用户**（tenantId=0） | 查询不过滤，可跨租户查看 | 条件判断跳过 |
|
||||
| **平台用户新增** | 自动代入默认租户（DEFAULT_TENANT_ID） | 读取 `config/tenant.php` |
|
||||
|
||||
### 租户上下文来源
|
||||
|
||||
`TenantMiddleware` 解析 JWT 中的租户信息，注入 `$request->tenantId`。
|
||||
`ResolveTenant` 中间件解析并注入 `request->attributes['tenantId']`，并校验租户状态与有效期（详见 [4.2 请求处理链路](/zh/architecture/request-flow.html)）。
|
||||
|
||||
### 适用范围
|
||||
|
||||
- 需要租户隔离的模块：继承 `BaseTenantLogic`（User、Article、Dept、Level 等）
|
||||
- 系统共享数据：继承 `BaseLogic`（Menu、Role、Dict、Config 等）
|
||||
- 需要租户隔离的模块：继承 `BaseTenantService`（User、Article、Dept、Level 等）
|
||||
- 系统共享数据：继承 `BaseService`（Menu、Dict、Config 等）
|
||||
|
||||
## 10. 审计字段 + 软删除（BaseModel）
|
||||
## 9. 审计字段 + 软删除（模型 Trait）
|
||||
|
||||
**配置方式**：继承 `BaseModel` 即自动生效，无需额外配置。
|
||||
**配置方式**：模型 `use HasAuditColumns, SoftDeletesByFlag` 即自动生效，无需额外配置。
|
||||
|
||||
### 软删除
|
||||
|
||||
```text
|
||||
全局查询范围 soft_delete：
|
||||
全局查询范围 SoftDeleteFlagScope：
|
||||
所有查询自动叠加 WHERE is_delete = 0
|
||||
→ 已删除数据默认不可见
|
||||
|
||||
软删除操作：
|
||||
$model->softDelete() → UPDATE SET is_delete = 1
|
||||
BaseModel::batchSoftDelete($ids) → 批量软删除
|
||||
Model::batchSoftDelete($ids) → 批量软删除
|
||||
|
||||
查询已删除数据：
|
||||
Model::withoutGlobalScope(['soft_delete'])->...
|
||||
Model::withoutGlobalScope(SoftDeleteFlagScope::class)->...
|
||||
```
|
||||
|
||||
### 审计字段自动写入
|
||||
|
||||
| 事件 | 自动填充字段 | 数据来源 |
|
||||
|------|------------|---------|
|
||||
| `onBeforeInsert`（创建前） | `create_user` | `$request->userInfo->username` |
|
||||
| `onBeforeInsert`（创建前） | `create_time` | `date('Y-m-d H:i:s')` |
|
||||
| `onBeforeUpdate`（更新前） | `update_user` | `$request->userInfo->username` |
|
||||
| `onBeforeUpdate`（更新前） | `update_time` | `date('Y-m-d H:i:s')`（始终覆盖） |
|
||||
| `creating`（创建前） | `create_user` | `Auth::username()`（当前登录用户） |
|
||||
| `creating`（创建前） | `create_time` | `now()`（已赋值则保留） |
|
||||
| `updating`（更新前） | `update_user` | `Auth::username()` |
|
||||
| `updating`（更新前） | `update_time` | `now()`（始终覆盖） |
|
||||
|
||||
:::tip 无用户场景
|
||||
控制台任务、定时任务等无登录用户的场景下，跳过用户字段，时间字段仍写入。
|
||||
控制台任务、定时任务等无登录用户的场景下，用户字段保留空值（可显式赋值跳过），时间字段仍写入。
|
||||
:::
|
||||
|
||||
### 数据库公共字段
|
||||
@@ -477,14 +421,14 @@ update_time DATETIME COMMENT '更新时间'
|
||||
一个模块可以同时启用多种横切机制，它们互不干扰：
|
||||
|
||||
```php
|
||||
class ArticleLogic extends BaseTenantLogic
|
||||
class ArticleService extends BaseTenantService
|
||||
{
|
||||
// 租户隔离（继承自动启用：use HasDataScope + tenantScopeField）
|
||||
use HasCrudOperations, HasQueryScopes, HasFileProcessing, HasSerializeMaps, HasUniqueCheck;
|
||||
|
||||
protected string $modelClass = Article::class;
|
||||
|
||||
// 自动参数校验
|
||||
protected string $validateClass = ArticleValidate::class;
|
||||
|
||||
// 文件字段处理
|
||||
// 文件字段处理（需 HasFileProcessing）
|
||||
protected array $fileFields = ['cover'];
|
||||
protected string $fileSaveDir = 'article';
|
||||
|
||||
@@ -494,18 +438,16 @@ class ArticleLogic extends BaseTenantLogic
|
||||
// 富文本占位符
|
||||
protected array $contentFields = ['content'];
|
||||
|
||||
// 枚举显示名翻译
|
||||
// 字典显示名翻译（需 HasSerializeMaps）
|
||||
protected array $serializeMaps = ['status' => 'article_status'];
|
||||
|
||||
// 唯一性校验
|
||||
// 唯一性校验（需 HasUniqueCheck）
|
||||
protected array $uniqueFields = ['title'];
|
||||
|
||||
// 数据权限
|
||||
// 数据权限（需 HasDataScope，租户版基类已 use）
|
||||
protected string $dataScopeUserField = 'create_user';
|
||||
|
||||
// 租户隔离（继承 BaseTenantLogic 自动启用）
|
||||
|
||||
// 审计字段 + 软删除（继承 BaseModel 自动生效）
|
||||
// 审计字段 + 软删除（模型 Trait 自动生效）
|
||||
}
|
||||
```
|
||||
|
||||
@@ -514,23 +456,20 @@ class ArticleLogic extends BaseTenantLogic
|
||||
```text
|
||||
beforeAdd ← 钩子
|
||||
▼
|
||||
validateData ← 自动参数校验
|
||||
(入口) FormRequest ← 参数格式校验（rules）
|
||||
▼
|
||||
camel_to_snake ← 驼峰转下划线
|
||||
checkUnique ← 唯一性校验（BizException 拦截）
|
||||
▼
|
||||
processTenantId ← 租户ID填充
|
||||
▼
|
||||
processFileFields ← 文件字段处理（单值）
|
||||
▼
|
||||
processMultiFileFields ← 多文件字段处理（逗号分隔多值）
|
||||
▼
|
||||
processContentFields ← 富文本处理
|
||||
▼
|
||||
filterTableFields ← 过滤非数据库字段
|
||||
▼
|
||||
checkUnique ← 唯一性校验
|
||||
▼
|
||||
Model::create ← 审计字段自动填充
|
||||
▼
|
||||
afterAdd ← 钩子
|
||||
DB::transaction {
|
||||
processTenantId ← 租户ID填充（HasDataScope 启用时）
|
||||
processFileFields ← 文件字段处理（单值）
|
||||
processMultiFileFields ← 多文件字段处理（逗号分隔多值）
|
||||
processContentFields ← 富文本处理
|
||||
Model::create ← 审计字段自动填充（creating 事件）
|
||||
afterAdd ← 钩子
|
||||
}
|
||||
```
|
||||
|
||||
:::tip 设计价值
|
||||
开发者只需声明"这个字段是文件"（`fileFields`）、"这个字段要唯一"（`uniqueFields`），全部处理逻辑由基类与 Trait 统一完成——改动一处，全模块受益。
|
||||
:::
|
||||
|
||||
Reference in New Issue
Block a user