签入版本
This commit is contained in:
@@ -1,103 +1,150 @@
|
||||
# 3.3 模型层开发
|
||||
|
||||
:::tip 概述
|
||||
模型层负责定义数据库表的映射关系，继承 BaseModel 后自动获得软删除和审计字段能力。
|
||||
模型层负责定义数据库表的映射关系。通过组合两个模型 Trait（`SoftDeletesByFlag`、`HasAuditColumns`），自动获得软删除和审计字段能力。
|
||||
:::
|
||||
|
||||
## 模型文件位置
|
||||
|
||||
```text
|
||||
app/model/Example.php
|
||||
app/Models/Example.php
|
||||
```
|
||||
|
||||
## 完整代码（来自项目实际代码）
|
||||
|
||||
```php
|
||||
<?php
|
||||
declare(strict_types=1);
|
||||
|
||||
namespace app\model;
|
||||
namespace App\Models;
|
||||
|
||||
use app\BaseModel;
|
||||
use App\Models\Concerns\HasAuditColumns;
|
||||
use App\Models\Concerns\SoftDeletesByFlag;
|
||||
use Illuminate\Database\Eloquent\Model;
|
||||
|
||||
/**
|
||||
* 案例演示模型
|
||||
*
|
||||
* 对应数据表 example，继承 BaseModel 获得通用模型能力
|
||||
* （软删除与审计字段自动写入）。
|
||||
* 对应数据表 example，继承 Eloquent Model 获得通用模型能力。
|
||||
*
|
||||
* 说明：本模型只有表映射，未定义关联或辅助方法；
|
||||
* 案例演示的查询过滤、排序、唯一校验等均由 ExampleLogic 配置。
|
||||
* 说明：
|
||||
* - 通过 HasAuditColumns 自动维护审计字段（如 created_by、updated_by 等）。
|
||||
* - 通过 SoftDeletesByFlag 实现基于标志位的软删除（如 is_deleted 字段）。
|
||||
* - type 类型：1=类型1，2=类型2，3=类型3，4=类型4。
|
||||
* - status 状态：1=在用，2=停用。
|
||||
* - 本模型通常作为开发示例/模板使用，不承载具体业务逻辑。
|
||||
*/
|
||||
class Example extends BaseModel
|
||||
class Example extends Model
|
||||
{
|
||||
use HasAuditColumns, SoftDeletesByFlag;
|
||||
|
||||
/**
|
||||
* 数据表名
|
||||
*
|
||||
* 显式指定表名，覆盖默认的类名推导规则。
|
||||
* ThinkPHP 默认使用类名的小写下划线形式作为表名，
|
||||
* Example → think_example。如果表名与类名不对应，
|
||||
* 可通过 $name 属性显式指定。
|
||||
* 显式指定表名为 example，覆盖默认的类名推导规则。
|
||||
*
|
||||
* @var string
|
||||
*/
|
||||
protected $name = 'example';
|
||||
protected $table = 'example';
|
||||
|
||||
/**
|
||||
* 允许批量赋值的字段列表
|
||||
*
|
||||
* 白名单中的字段可通过 create()、update()、fill() 等方式批量赋值。
|
||||
*
|
||||
* @var array<int, string>
|
||||
*/
|
||||
protected $fillable = [
|
||||
'name', // 名称
|
||||
'avatar', // 头像/图片地址
|
||||
'type', // 类型：1=类型1，2=类型2，3=类型3，4=类型4
|
||||
'status', // 状态：1=在用，2=停用
|
||||
'sort', // 排序值，数值越小越靠前（视业务而定）
|
||||
];
|
||||
}
|
||||
```
|
||||
|
||||
## 继承 BaseModel 后获得的能力
|
||||
:::tip 表名与前缀
|
||||
`$table = 'example'` 不含前缀，实际查询时由 `DB_PREFIX=laravel_` 自动拼接为 `laravel_example`。
|
||||
:::
|
||||
|
||||
| 能力 | 说明 | 代码示例 |
|
||||
## 组合 Trait 后获得的能力
|
||||
|
||||
| Trait | 能力 | 代码示例 |
|
||||
|------|------|----------|
|
||||
| 软删除 | 全局查询自动过滤 `is_delete=1` | `$list = Example::select();` 自动排除已删除 |
|
||||
| 软删除操作 | 设置 `is_delete=1` | `$model->softDelete();` |
|
||||
| 批量软删除 | 批量设置 `is_delete=1` | `Example::batchSoftDelete([1,2,3]);` |
|
||||
| 审计字段-创建 | 自动填充 `create_user` 和 `create_time` | `Example::create([...])` 时自动填充 |
|
||||
| 审计字段-更新 | 自动填充 `update_user` 和 `update_time` | `$model->save([...])` 时自动填充 |
|
||||
| `SoftDeletesByFlag` | 注册 `SoftDeleteFlagScope` 全局范围，查询自动过滤 `is_delete=1` | `Example::query()` 自动排除已删除 |
|
||||
| `SoftDeletesByFlag` | 标记删除单条 | `$model->softDelete();`（置 `is_delete=1`） |
|
||||
| `SoftDeletesByFlag` | 批量标记删除 | `Example::batchSoftDelete([1,2,3]);` |
|
||||
| `HasAuditColumns` | `creating` 事件自动填充 `create_user`（当前登录人）和 `create_time` | `Example::create([...])` 时自动填充 |
|
||||
| `HasAuditColumns` | `updating` 事件自动填充 `update_user`、`update_time`（每次强制覆盖） | `$model->update([...])` 时自动填充 |
|
||||
|
||||
:::tip 审计字段说明
|
||||
`create_user` 取自 `Auth::username()`（当前登录用户）；`create_*` 采用 `??` 逻辑——已显式赋值则保留原值，`update_*` 每次强制覆盖。表结构不含 Laravel 默认的 `created_at` / `updated_at`。
|
||||
:::
|
||||
|
||||
## 查询已删除数据
|
||||
|
||||
```php
|
||||
// 查询单条（包括已删除）
|
||||
$example = Example::withoutGlobalScope(['soft_delete'])->find($id);
|
||||
// 查询单条（包括已删除）—— 移除全局软删除范围
|
||||
$example = Example::withoutGlobalScope(SoftDeleteFlagScope::class)->find($id);
|
||||
|
||||
// 查询所有（包括已删除）
|
||||
$all = Example::withoutGlobalScope(['soft_delete'])->select();
|
||||
$all = Example::withoutGlobalScope(SoftDeleteFlagScope::class)->get();
|
||||
|
||||
// 恢复（软删除字段归零）
|
||||
$example->update(['is_delete' => 0]);
|
||||
```
|
||||
|
||||
## 简单模型 vs 复杂模型
|
||||
|
||||
:::tip 模型层职责
|
||||
模型层只负责表映射和关联关系，不包含业务逻辑。所有查询条件、排序、唯一性校验等都由 Logic 层配置。
|
||||
模型层只负责表映射和关联关系，不包含业务逻辑。所有查询条件、排序、唯一性校验等都由 Service 层配置。
|
||||
:::
|
||||
|
||||
### 简单模型（如 Example）
|
||||
|
||||
只需声明表名，所有逻辑由 Logic 层配置：
|
||||
只需声明表名与批量赋值白名单，所有逻辑由 Service 层配置：
|
||||
|
||||
```php
|
||||
class Example extends BaseModel
|
||||
class Example extends Model
|
||||
{
|
||||
protected $name = 'example';
|
||||
use HasAuditColumns, SoftDeletesByFlag;
|
||||
|
||||
protected $table = 'example';
|
||||
protected $fillable = ['name', 'avatar', 'type', 'status', 'sort'];
|
||||
}
|
||||
```
|
||||
|
||||
### 复杂模型（如 Role）
|
||||
|
||||
包含关联关系：
|
||||
包含关联关系（以项目实际代码为例）：
|
||||
|
||||
```php
|
||||
class Role extends BaseModel
|
||||
class Role extends Model
|
||||
{
|
||||
protected $name = 'role';
|
||||
use HasAuditColumns, SoftDeletesByFlag;
|
||||
|
||||
protected $table = 'role';
|
||||
protected $fillable = [...];
|
||||
|
||||
/**
|
||||
* 关联菜单（多对多）
|
||||
* 通过 role_menu 中间表关联
|
||||
* 角色关联的菜单（多对多，经 role_menu 中间表）
|
||||
*/
|
||||
public function menus()
|
||||
public function menus(): BelongsToMany
|
||||
{
|
||||
return $this->belongsToMany(Menu::class, 'role_menu', 'menu_id', 'role_id');
|
||||
return $this->belongsToMany(Menu::class, 'role_menu', 'role_id', 'menu_id')
|
||||
->wherePivot('is_delete', 0);
|
||||
}
|
||||
}
|
||||
```
|
||||
```
|
||||
|
||||
## 模型相关文件
|
||||
|
||||
```text
|
||||
app/Models/
|
||||
├── Concerns/
|
||||
│ ├── SoftDeletesByFlag.php # is_delete 软删除（注册全局 Scope + softDelete 方法）
|
||||
│ ├── SoftDeleteFlagScope.php # 全局查询范围（WHERE is_delete = 0）
|
||||
│ └── HasAuditColumns.php # 审计字段（creating/updating 事件填充）
|
||||
├── Example.php # 案例模型
|
||||
└── ...
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user