💾 更新助手

SaveHelper 是 ThinkAdmin 提供的数据更新助手，专注于简化数据状态的更新操作，如数据禁用、启用以及状态更改等。通过简洁的接口和直观的操作，快速实现数据状态的更新。

📚 基础概念

🤔 基本介绍

SaveHelper（更新助手）是 ThinkAdmin 框架提供的一个工具类，专门用于快速更新数据记录的状态或字段值。

简单理解：就像数据的"状态切换器"，帮你快速更新数据的状态，如启用/禁用、上架/下架等。

传统方式（不推荐）：

// ❌ 传统方式：需要手动处理更新逻辑
public function state()
{
    $ids = input('id');
    $status = input('status');
    
    // 1. 验证数据
    if (empty($ids)) {
        $this->error('ID 不能为空');
    }
    if (!in_array($status, [0, 1])) {
        $this->error('状态值范围异常');
    }
    
    // 2. 批量更新
    $ids = str2arr($ids);
    foreach ($ids as $id) {
        SystemUser::where('id', $id)->update(['status' => $status]);
    }
    
    $this->success('更新成功');
}

使用 SaveHelper（推荐）：

// ✅ 使用 SaveHelper：一行代码完成更新
public function state()
{
    SystemUser::mSave($this->_vali([
        'status.require' => '状态值不能为空！',
        'status.in:0,1' => '状态值范围异常！',
    ]));
}

🤔 使用优势

问题1：代码重复

不使用 SaveHelper 时，每个状态更新都需要重复编写相同的逻辑：

// ❌ 每个状态更新都要写这些代码
$ids = input('id');
$status = input('status');
// 验证、更新、返回结果... 大量重复代码

问题2：容易出错

手动处理更新逻辑容易出错：

// ❌ 容易出错：忘记验证、忘记处理条件等
$ids = input('id');
SystemUser::whereIn('id', $ids)->update(['status' => $status]);
// 没有验证，可能更新错误的数据

问题3：维护困难

当需要修改更新逻辑时，需要在多个地方修改：

// ❌ 需要在多个控制器中修改相同的逻辑
// UserController.php
SystemUser::whereIn('id', $ids)->update(['status' => $status]);

// OrderController.php
SystemOrder::whereIn('id', $ids)->update(['status' => $status]);
// 重复代码

使用 SaveHelper 的优势：

// ✅ 统一接口，代码简洁
SystemUser::mSave($this->_vali([...]));
SystemOrder::mSave($this->_vali([...]));

🎯 核心功能

功能1：快速更新

一行代码完成数据更新：

// 更新用户状态
SystemUser::mSave($this->_vali([
    'status.require' => '状态值不能为空！',
    'status.in:0,1' => '状态值范围异常！',
]));

功能2：批量操作

支持批量更新多条记录：

// 批量更新用户状态
// POST 数据：id=1,2,3&status=1
SystemUser::mSave($this->_vali([
    'status.require' => '状态值不能为空！',
]));
// 自动更新 id=1,2,3 的用户状态为 1

功能3：条件限制

支持设置更新条件，确保数据安全：

// 只更新未删除的记录
SystemUser::mSave(
    $this->_vali([...]),
    'id',
    ['is_deleted' => 0]  // 更新条件
);

功能4：回调处理

支持前置和后置回调，处理业务逻辑：

// 前置回调：更新前处理
protected function _save_filter($query, array &$data)
{
    // 验证和处理数据
}

// 后置回调：更新后处理
protected function _save_result(bool $result)
{
    // 处理更新结果
}

📖 相关概念

状态字段

用于标识数据状态的字段
例如：status（0=禁用，1=启用）

批量更新

一次性更新多条记录
例如：同时更新多个用户的状态

条件限制

设置更新条件，只更新符合条件的记录
例如：只更新未删除的记录

🎯 使用场景

场景1：用户管理

启用/禁用用户账号：

public function state()
{
    SystemUser::mSave($this->_vali([
        'status.require' => '状态值不能为空！',
        'status.in:0,1' => '状态值范围异常！',
    ]));
}

场景2：商品管理

上架/下架商品：

public function state()
{
    SystemGoods::mSave($this->_vali([
        'status.require' => '状态值不能为空！',
        'status.in:0,1' => '状态值范围异常！',
    ]), 'id', ['is_deleted' => 0]);
}

场景3：订单管理

审核通过/拒绝订单：

public function audit()
{
    SystemOrder::mSave($this->_vali([
        'audit_status.require' => '审核状态不能为空！',
        'audit_status.in:1,2' => '审核状态范围异常！',
    ]));
}

场景4：内容管理

发布/隐藏文章：

public function publish()
{
    SystemArticle::mSave($this->_vali([
        'status.require' => '状态值不能为空！',
        'status.in:0,1' => '状态值范围异常！',
    ]));
}

🚀 主要功能

状态更新: 快速更新数据状态（启用/禁用等）
批量处理: 支持批量更新多条数据记录
安全验证: 完善的数据验证和权限控制
错误处理: 详细的错误处理和日志记录
事务支持: 支持数据库事务操作

📋 使用场景

用户状态管理（启用/禁用用户）
商品状态管理（上架/下架商品）
订单状态管理（处理/完成订单）
内容状态管理（发布/隐藏内容）
批量数据操作

⚙️ 工作原理

数据定位

根据传入的数据 ID 和条件自动定位数据记录
支持主键字段和自定义查询条件
确保数据操作的安全性和准确性
支持批量数据定位

状态更新

提供清晰的状态选项供用户选择
自动执行状态更新操作
支持单条和批量数据更新
支持自定义状态值

安全保护

数据验证和权限控制
防止恶意数据修改
详细的操作日志记录
支持操作权限验证

事务处理

支持数据库事务操作
确保数据一致性
支持回滚机制
异常处理机制

具体实现原理

为了充分利用 SaveHelper 数据更新助手在模型（Model）和控制器（Controller）中的功能，系统进行了以下优化：

模型继承：若需在模型中使用 SaveHelper 快捷查询器，该模型应继承 \think\admin\Model 类。这样做可以确保模型拥有 SaveHelper 提供的所有功能，方便进行数据的快速保存和查询操作。
控制器继承：对于需要使用 SaveHelper 快捷查询器的控制器，应继承 \think\admin\Controller 类。通过继承这个基类，控制器可以方便地调用 SaveHelper 的相关方法，实现对数据的快速处理和响应。
前端数据传递：前端需要传递需要修改的数据 ID 以及数据状态值给后端。为了确保数据的安全性和准确性，强烈建议前端传递第二个参数（如操作类型、验证信息等）。这样可以为后端提供更多的上下文信息，有助于后端进行更精确的数据处理和验证。
数据安全考虑：为了防止数据被恶意修改，使用 SaveHelper 时指定第二个参数是非常必要的。此外，还可以结合验证器 _vali() 和限定条件 $where 变量来进一步确保数据的安全性。验证器可以对数据进行严格的校验，确保只有符合规则的数据才能被保存；而 $where 变量则可以限制操作的范围，防止对不应修改的数据进行操作。

通过以上优化，SaveHelper 快捷查询器在模型和控制器中的使用变得更加灵活和安全，同时前端传递的数据也得到了更好的处理和验证，提升了整个系统的稳定性和安全性。

// 1.0 模型用法
// 参数 $data 为待修改数据
// 参数 $field 为主键字段
// 参数 $where 为修改查询条件
SystemUser::mSave($data, $field, $where);

// 1.1 模型通用更新
SystemUser::mSave();

// 1.2 配合验证器使用（推荐方式）
SystemUser::mSave($this->_vali([
    'status.require' => '状态值不能为空！',
    'status.in:0,1'  => '状态值范围异常！',
]));

// 1.3 配置验证器和限制条件
SystemUser::mSave($this->_vali([
    'status.require' => '状态值不能为空！',
    'status.in:0,1'  => '状态值范围异常！',
]), 'id', [
    'is_deleted' => 0,
    'status' => 1,
]);


// 2.0 控制器用法（不推荐，建议使用模型方法）
// 参数 $dbQuery 为模型名称
// 参数 $data 为待修改数据
// 参数 $field 为主键字段
// 参数 $where 为修改查询条件
$this->_save('SystemUser', $data, $field, $where);

// 2.1 通用修改器（不推荐，建议使用模型方法）
$this->_save('SystemUser');

// 2.2 配合验证器使用（不推荐，建议使用模型方法）
$this->_save('SystemUser', $this->_vali([
    'status.require' => '状态值不能为空！',
    'status.in:0,1'  => '状态值范围异常！',
]));

数据回调处理

对于数据更新操作，Controller 内置了两个回调方法：

// 更新前置操作，允许使用引用更改查询条件和数据
// 参数 $query：查询对象
// 参数 $data：待更新的数据数组
// 返回 false 时，默认行为将不会再执行
[_ACTION]_save_filter($query, array &$data)

// 更新后置操作
// 参数 $result：更新结果，成功为 true，失败为 false
// 返回 false 时，默认行为将不会再执行
[_ACTION]_save_result(bool $result)

实际应用案例

<?php
declare(strict_types=1);

namespace app\admin\controller;

use think\admin\Controller;
use think\admin\model\SystemUser;

/**
 * 系统用户管理
 * @class User
 * @package app\admin\controller
 */
class User extends Controller
{
    /**
     * 修改数据状态
     * @auth true 
     */
    public function state()
    {
        // 实际项目中的安全检查示例
        $this->_checkInput();
        
        SystemUser::mSave($this->_vali([
            'status.in:0,1'  => '状态值范围异常！',
            'status.require' => '状态值不能为空！',
        ]));
    }

    /**
     * 检查输入变量（实际项目中的私有方法示例）
     */
    private function _checkInput()
    {
        // 防止删除系统超级账号
        if (in_array('10000', str2arr(input('id', '')))) {
            $this->error('系统超级账号禁止删除！');
        }
    }

    /**
     * 更新前置回调（在更新前进行数据过滤）
     * @param $query 查询对象
     * @param array $data 待更新的数据
     */
    protected function _save_filter($query, array &$data)
    {
        // 可以修改查询条件
        $query->where('is_deleted', 0);
        
        // 可以修改待更新的数据
        if (isset($data['status'])) {
            // 添加额外的数据
            $data['update_at'] = date('Y-m-d H:i:s');
        }
    }

    /**
     * 更新后置回调（通用回调）
     * @param bool $result 更新结果
     */
    protected function _save_result(bool $result)
    {
        if ($result) {
            sysoplog('系统用户管理', '更新用户状态成功');
        }
    }

    /**
     * 当一个控制器存在多个 save 操作时，可以指定回调前缀
     * @param bool $result 更新结果
     */
    protected function _state_save_result(bool $result)
    {
        // 可以根据 $result 状态返回结果 
        // 失败 $this->error(MESSAGE);
        // 成功 $this->success(MESSAGE);
    }
}

如果是在 `ThinkAdmin` 后台基于 `admin.js` 的情况下，可使用 `data-action` 来与 `SaveHelper` 配合使用。

## 🔧 前端配合使用

**自动状态更新**
```html
<!-- 使用 data-action 属性自动更新状态 -->
<button data-action="{:url('save')}" 
        data-value="id#{{d.id}};status#1" 
        data-confirm="确认要启用这条记录吗？"
        class="layui-btn layui-btn-sm">启用</button>

批量状态更新

<!-- 批量更新多条记录 -->
<button data-action="{:url('save')}" 
        data-value="id#1,2,3;status#1" 
        data-confirm="确认要批量启用这些记录吗？"
        class="layui-btn layui-btn-sm">批量启用</button>

前端提交格式说明 前端提交上来的内容 data-value 支持多组数据，以英文分号 ; 分隔，键与值以英文 # 分隔，如：data-value="id#1;status#0;"

格式说明：

单条记录：data-value="id#1;status#0"
多条记录：data-value="id#1,2,3;status#1"

SaveHelper 深入应用

1. 数据库事务处理

<?php
declare(strict_types=1);

namespace app\admin\controller;

use think\admin\Controller;
use think\admin\model\SystemUser;
use think\facade\Db;

class User extends Controller
{
    /**
     * 批量更新用户状态（使用事务）
     * @auth true
     */
    public function batchState()
    {
        $data = $this->_vali([
            'ids.require' => '用户ID不能为空！',
            'status.require' => '状态值不能为空！',
            'status.in:0,1' => '状态值范围异常！',
        ]);
        
        // 开启数据库事务
        Db::startTrans();
        try {
            // 批量更新用户状态
            SystemUser::mk()
                ->whereIn('id', str2arr($data['ids']))
                ->where('is_deleted', 0)
                ->update(['status' => $data['status']]);
            
            // 记录操作日志
            sysoplog('系统用户管理', "批量更新用户状态[{$data['status']}]");
            
            // 提交事务
            Db::commit();
            $this->success('批量更新成功！');
        } catch (\Exception $e) {
            // 回滚事务
            Db::rollback();
            $this->error('批量更新失败：' . $e->getMessage());
        }
    }
}

2. 复杂业务逻辑处理

protected function _save_filter(array &$data)
{
    // 业务规则验证
    if (!empty($data['id'])) {
        $user = SystemUser::mk()->find($data['id']);
        if (empty($user)) {
            $this->error('用户不存在！');
        }
        
        // 状态变更时的特殊处理
        if ($user['status'] != $data['status']) {
            // 禁用用户时，清除登录会话
            if ($data['status'] == 0) {
                $this->app->session->delete("user_{$data['id']}");
            }
            
            // 记录状态变更日志
            sysoplog('系统用户管理', "用户[{$user['username']}]状态变更为[{$data['status']}]");
        }
    }
}

protected function _save_result(bool $result)
{
    if ($result) {
        // 触发用户状态变更事件
        $this->app->event->trigger('PluginAdminUserStatusChange', [
            'id' => input('id'),
            'status' => input('status'),
        ]);
    }
}

3. 条件限制和权限控制

public function save()
{
    // 非超级管理员只能更新自己的数据
    $where = [];
    if (!AdminService::isSuper()) {
        $where['uuid'] = AdminService::getUserId();
    }
    
    SystemUser::mSave(
        $this->_vali([
            'status.require' => '状态值不能为空！',
            'status.in:0,1' => '状态值范围异常！',
        ]),
        'id',
        $where
    );
}

4. 性能优化建议

// 批量更新时，使用 whereIn 而不是循环更新
// ❌ 不推荐：循环更新
foreach ($ids as $id) {
    SystemUser::mk()->where('id', $id)->update(['status' => 1]);
}

// ✅ 推荐：批量更新
SystemUser::mk()
    ->whereIn('id', $ids)
    ->update(['status' => 1]);

// 使用索引字段进行查询
SystemUser::mk()
    ->where('id', $id)  // id 是主键，有索引
    ->where('status', 1)  // 如果 status 有索引，查询更快
    ->update(['status' => 0]);

多字段更新：data-value="id#1;status#1;name#test"