docs(command): 添加tools命令命名规范文档

2026-07-01 15:32:48 +08:00 · 2026-01-26 23:09:45 +08:00
parent 96eaa269a1
commit 148f8b7a6f
1 changed files with 194 additions and 0 deletions
--- a/extend/base/common/command/tools/README.md
+++ b/extend/base/common/command/tools/README.md
@@ -0,0 +1,194 @@
+# Tools 命令命名规范
+
+## 概述
+
+`tools` 目录下的命令是系统级工具命令，主要用于开发调试、系统维护等场景。与普通命令不同，tools 命令有独特的命名规则和目录结构。
+
+## 目录结构
+
+```
+extend/base/common/
+├── service/
+│   ├── ToolsDbServiceBase.php       # 数据库工具服务
+│   ├── ToolsLogServiceBase.php      # 日志工具服务
+│   └── ToolsBackupServiceBase.php  # 备份工具服务
+└── command/
+    └── tools/
+        ├── README.md                # 本文件（命名规范说明）
+        └── db/                     # 数据库工具
+            ├── ToolsDbQueryBase.php   # 基础命令类
+            ├── ToolsDbExecuteBase.php
+            └── ...
+
+app/common/command/
+├── tools/
+│   └── db/                       # 数据库工具
+│       ├── ToolsDbQuery.php         # 业务命令类
+│       ├── ToolsDbExecute.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:log:clear` - 日志清理
+  - `tools:backup:create` - 创建备份
+
+### 3. 目录结构规则
+
+```
+tools/
+├── db/           # 数据库工具（db）
+├── log/          # 日志工具（log）
+├── backup/       # 备份工具（backup）
+├── cache/        # 缓存工具（cache）
+└── ...
+```
+
+## 创建新 Tools 命令的步骤
+
+### 示例：创建日志清理命令
+
+#### 1. 创建 Service 类
+
+```php
+<?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
+<?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
+<?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` 中注册：
+
+```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` - 统计表记录数