ulthon_admin/extend/base/common/command/tools

Tools 命令命名规范

概述

tools 目录下的命令是系统级工具命令，主要用于开发调试、系统维护等场景。与普通命令不同，tools 命令有独特的命名规则和目录结构。

目录结构

 extend/base/common/
 ├── service/
 │   ├── ToolsDbServiceBase.php       # 数据库工具服务
 │   ├── ToolsLogServiceBase.php      # 日志工具服务
 │   └── ToolsBackupServiceBase.php  # 备份工具服务
 └── command/
     └── tools/
         ├── README.md                # 本文件（命名规范说明）
         ├── db/                     # 数据库工具
         │   ├── ToolsDbQueryBase.php   # 基础命令类
         │   ├── ToolsDbExecuteBase.php
         │   └── ...
         ├── http/                    # HTTP 工具
         │   └── ToolsHttpCallBase.php
         └── ...

 app/common/command/
 ├── tools/
 │   ├── db/                       # 数据库工具
 │   │   ├── ToolsDbQuery.php         # 业务命令类
 │   │   ├── ToolsDbExecute.php
 │   │   └── ...
 │   └── http/                     # HTTP 工具
 │       └── ToolsHttpCall.php
 ├── admin/                        # 普通命令（无前缀）
 ├── scheme/
 ├── curd/
 └── ...

命名规则对比

普通命令（admin、scheme、curd 等）

项目	规则	示例
类名	无前缀，直接使用功能名称	Clear、MigrateFileData、ViewDebugLog
命名空间	app\common\command\[模块]	app\common\command\admin
命令名称	[模块]:[功能]	admin:clear、admin:migrate-file-data
目录	按模块分组	admin/、scheme/、curd/
Service	使用现有的 service 层或无	-

Tools 命令（tools 目录）

项目	规则	示例
类名前缀	Tools[类型]	ToolsDbQuery、ToolsLogClear、ToolsBackupCreate
类名后缀	基础类加 Base	ToolsDbQueryBase、ToolsDbExecuteBase
命名空间	app\common\command\tools\[类型]	app\common\command\tools\db
命令名称	tools:[类型]:[功能]	tools:db:query、tools:db:execute
目录	按工具类型分组（二级）	tools/db/、tools/log/、tools/backup/
Service	专用 Service（base 层加 Base 后缀）	base\common\service\ToolsDbServiceBase

命名规则详解

1. 类名规则

Service 类：

• 命名空间：base\common\service
• 格式：Tools[类型]ServiceBase
• 示例：ToolsDbServiceBase、ToolsLogServiceBase、ToolsBackupServiceBase

基础命令类：

• 命名空间：base\common\command\tools\[类型]
• 格式：Tools[类型][功能]Base
• 示例：ToolsDbQueryBase、ToolsDbExecuteBase、ToolsLogClearBase

业务命令类：

• 命名空间：app\common\command\tools\[类型]
• 格式：Tools[类型][功能]
• 示例：ToolsDbQuery、ToolsDbExecute、ToolsLogClear
• 继承：继承对应的 Base 类

2. 命令名称规则

• 格式：tools:[类型]:[功能]
• 示例：
  • tools:db:query - 数据库查询
  • tools:db:execute - 数据库执行
  • tools:http:call - HTTP 调用（类似 curl）
  • tools:log:clear - 日志清理
  • tools:backup:create - 创建备份

3. 目录结构规则

 tools/
 ├── db/           # 数据库工具（db）
 ├── http/         # HTTP 工具（http）
 ├── log/          # 日志工具（log）
 ├── backup/       # 备份工具（backup）
 ├── cache/        # 缓存工具（cache）
 └── ...

创建新 Tools 命令的步骤

示例：创建日志清理命令

1. 创建 Service 类

<?php
// extend/base/common/service/ToolsLogServiceBase.php
namespace base\common\service;

class ToolsLogServiceBase
{
    public function checkDebugMode(Output $output): bool
    {
        // 实现调试模式检查
    }

    public function formatOutput(array $data, Output $output): void
    {
        // 实现输出格式化
    }
}

2. 创建基础命令类

<?php
// extend/base/common/command/tools/log/ToolsLogClearBase.php
namespace base\common\command\tools\log;

use base\common\service\ToolsLogServiceBase;
use think\console\Command;

class ToolsLogClearBase extends Command
{
    protected function configure()
    {
        $this->setName('tools:log:clear')
            ->setDescription('清理日志文件')
            ->addOption('all', null, Option::VALUE_NONE, '清理所有日志');
    }

    protected function execute($input, $output)
    {
        $service = new ToolsLogServiceBase();
        // 实现命令逻辑
    }
}

3. 创建业务命令类

<?php
// app/common/command/tools/log/ToolsLogClear.php
namespace app\common\command\tools\log;

use base\common\command\tools\log\ToolsLogClearBase;

class ToolsLogClear extends ToolsLogClearBase
{
}

4. 注册命令

在 extend/think/UlthonAdminService.php 中注册：

use app\common\command\tools\log\ToolsLogClear;

$this->commands([
    // ...
    ToolsLogClear::class,
]);

注意事项

1. 命名一致性：所有 tools 命令必须遵循统一的命名规则
2. Service 层：每个工具类型应有对应的 Service 类
3. 开发者模式：大多数 tools 命令应仅在开发者模式下可用
4. 安全性：涉及数据修改的命令应有确认机制（如 --force 选项）
5. 帮助文档：每个命令都应提供详细的 --help 说明
6. 扩展性：tools 目录的设计便于添加新的系统级工具

已实现的工具

• 数据库工具 (db)

  • tools:db:query - 执行 SQL 查询
  • tools:db:execute - 执行 SQL 非查询语句
  • tools:db:table - 使用查询构建器操作表
  • tools:db:info - 显示数据库信息
  • tools:db:desc - 显示表结构
  • tools:db:count - 统计表记录数

• HTTP 工具 (http)

  • tools:http:call - HTTP 调用工具，类似 curl
    • 支持标准 curl 参数：--url, --method, --data, --body, --headers
    • 支持框架特性参数：--app, --controller, --action, --super-token, --user-id
    • JSON 输出格式：{ success, response: { status, data, headers }, execution_time, exception }