diff --git a/CODERULE.md b/CODERULE.md index b99f679..e146f29 100644 --- a/CODERULE.md +++ b/CODERULE.md @@ -1,6 +1,16 @@ -# Ulthon Admin 项目开发规则 +# Ulthon Admin 开发规则手册 -## 1. 框架技术栈 +本文档分为三部分： +1. **通用基础规范**：所有开发者（框架作者与业务开发者）均需遵守的基础准则。 +2. **框架开发规则**：针对框架本身的维护者和贡献者。 +3. **业务开发规则**：针对使用框架开发具体业务系统的开发者。 + +--- + +## 第一部分：通用基础规范 +> 适用对象：所有开发者（必须遵守） + +### 1. 技术栈标准 - **核心框架**: ThinkPHP 8.0 - **开发语言**: PHP 8+ @@ -9,160 +19,116 @@ - **模板引擎**: ThinkPHP 内置模板引擎 - **代码生成器**: 自定义命令行工具 -## 2. 项目架构设计 +### 2. 命名与代码规范 -### 2.1 双层架构设计 +所有代码（无论是核心框架还是业务代码）必须严格遵守以下规范： -Uthon Admin 采用独特的双层架构设计，将系统功能分为核心基础层和业务应用层，便于开发者进行二次开发和功能扩展： +- **命名规范**: [官方命名规范文档](https://doc.ulthon.com/read/augushong/ulthon_admin/64fbcf8830640/zh-cn/2.x.html) + - 涵盖：类名、方法名、变量名、目录名等。 +- **代码风格**: [官方代码规范文档 (PHP-CS-Fixer)](https://doc.ulthon.com/read/augushong/ulthon_admin/64360c249d66a/zh-cn/2.x.html) + - 统一使用 PSR 标准，建议配置自动格式化工具。 -- **基础核心层 (`extend/base/`)**: - - 包含系统内置的所有核心功能代码 - - 提供标准化的类和方法接口 - - 不可直接修改，确保系统稳定性 - - 示例：`extend/base/controller/Base.php`、`extend/base/model/BaseModel.php` +### 3. 数据库设计规范 -- **业务应用层 (`application/`)**: - - 基于基础核心层扩展开发的具体业务代码 - - 所有业务类必须继承基础核心层的对应类 - - 开发者可自由修改和扩展，不会影响核心功能 - - 示例：`application/admin/controller/User.php` 继承 `base\controller\Base` - -### 2.2 继承重写机制 +- **设计文档**: [官方表结构设计规范](https://doc.ulthon.com/read/augushong/ulthon_admin/619efc9d7af62/zh-cn/2.x.html) +- **核心要求**: + - 表名小写，使用下划线分隔。 + - 按照前缀、模块、功能的顺序命名，例如：`ul_mall_goods`。 + - 必须为所有字段编写清晰、完整的注释。 + - 严格遵循文档中的字段类型定义。 -**注意**：继承重写机制主要针对 ulthon-admin 自身的内置功能（如管理员管理、菜单、权限等），用于扩展或修改框架内置功能。 +### 4.在线文档 -- 对于 ulthon-admin 内置功能，通过继承基础核心类（位于 `extend/base/`），可以获得内置功能并进行扩展 -- 需要修改内置功能时，在业务类中重写对应方法，保持方法签名一致 -- 支持调用父类方法：`parent::methodName()` - -**用户自定义代码**： -- 用户自己的业务代码不需要遵守该继承规则 -- 生成的代码直接位于 `application/` 目录下 -- 可以直接在 `application/` 目录下进行开发和修改 - -## 3. 开发流程 - -### 3.1 标准开发步骤 - -1. **设计数据库表结构** - - 按照业务需求设计合理的表结构 - - 必须为所有字段编写清晰、完整的注释 - - 遵循命名规范：表名小写，使用下划线分隔 - -2. **生成基础代码** - - 使用内置命令行工具生成代码 - - 支持生成到临时目录，避免覆盖已定制代码 - - 生成内容包括：控制器、模型、视图、验证器、菜单配置 - -3. **代码定制** - - 基于生成的代码进行业务定制 - - 仅修改 `application/` 目录下的文件 - - 使用继承重写机制扩展基础功能 - -4. **测试与验证** - - 测试所有功能是否正常工作 - - 确保数据完整性和安全性 - - 检查代码规范和性能 - -### 3.2 代码生成命令 - -CURD命令大全 - -ulthon_admin框架以内置快速生成CURD的命令, 包括控制器、视图、模型、JS文件。能够使开发者效率得到进一步提升。 - -> 备注：在进行CURD命令行之前, 请按照规范设计表结构, 请参考表结构规范模块说明。 - -**常用命令** -``` -# 生成ul_test_goods表的CURD -php think curd -t test_goods - -# 生成ul_test_goods表的CURD到临时目录 -php think curd -t test_goods -r - -# 生成ul_test_goods表的CURD, 文件冲突时强制覆盖 -php think curd -t test_goods -f - -# 删除ul_test_goods表的CURD -php think curd -t test_goods -d - -# 生成ul_test_goods表的CURD, 控制器在目录demo下的Goods.php文件 -# 原路径： `controller\text\Goods.php`， -# 此时路径：`controller\demo\Goods.php` -# 不建议指定该参数 -php think curd -t test_goods -c demo/Goods - -# 生成ul_test_goods表的CURD, 模型在目录demo下的Goods.php文件 -# 原路径： `model\MallCate.php` -# 此时路径: `model\demo\Goods.php` -# 不建议指定该参数 -php think curd -t test_goods -m demo/Goods -``` - -**参数介绍** - -| 短参 | 长参 |说明| -| ------------ | ------------ | ------| -| -t | `--table=VALUE` | 主表名 | -| -c | `--controllerFilename=VALUE` | 控制器文件名 | -|-m| `--modelFilename=VALUE` |主表模型文件名| -|-f| `--force`|强制覆盖模式 | -|-d| `--delete`|删除模式 | -|-r |`--runtime`|生成到临时目录| - -**官方命令行文档**: [https://doc.ulthon.com/read/augushong/ulthon_admin/619efc929565f/zh-cn/2.x.html](https://doc.ulthon.com/read/augushong/ulthon_admin/619efc929565f/zh-cn/2.x.html) - -**CURD 文档地址**: [https://doc.ulthon.com/read/augushong/ulthon_admin/619efc816472e/zh-cn/2.x.html](https://doc.ulthon.com/read/augushong/ulthon_admin/619efc816472e/zh-cn/2.x.html) - -### 3.3 表结构设计规范 - -**官方表结构规范文档**: [https://doc.ulthon.com/read/augushong/ulthon_admin/619efc9d7af62/zh-cn/2.x.html](https://doc.ulthon.com/read/augushong/ulthon_admin/619efc9d7af62/zh-cn/2.x.html) - -> 以官方在线文档为准，包含详细的表结构设计规范，包括表名规则、特殊字段、数据类型定义等。 - -## 4. 命名规范 - -**官方命名规范文档**: [https://doc.ulthon.com/read/augushong/ulthon_admin/64fbcf8830640/zh-cn/2.x.html](https://doc.ulthon.com/read/augushong/ulthon_admin/64fbcf8830640/zh-cn/2.x.html) - -> 以官方在线文档为准，包含详细的命名规范说明。 - -## 5. 代码规范 - -**官方代码规范文档**: [https://doc.ulthon.com/read/augushong/ulthon_admin/64360c249d66a/zh-cn/2.x.html](https://doc.ulthon.com/read/augushong/ulthon_admin/64360c249d66a/zh-cn/2.x.html) - -> 以官方在线文档为准，包含 PHP-CS-Fixer 配置和详细的代码规范说明。 - -### 5.1 前端文件组织规范 - -**视图与JS文件对应规则**：后台的所有视图，每个HTML文件都会搭配一个对应的JS文件，文件结构示例： - -``` -goods -├─ add.html -├─ add.js -├─ edit.html -├─ edit.js -├─ index.html -├─ index.js -├─ read.html -├─ read.js -└─ _common.js -``` - -- 每个功能页面的HTML和JS文件名保持一致 -- `_common.js` 用于存放该模块通用的JS代码 -- JS文件中应包含对应页面的业务逻辑、事件绑定等 -- 这种结构便于维护和扩展，确保前端代码的组织性 - -## 7. 二次开发注意事项 - -- 不要修改 `extend/base/` 目录下的任何文件 -- 所有业务逻辑都应放在 `application/` 目录下 -- 扩展功能时优先考虑继承重写机制 -- 保持代码结构清晰，便于维护 -- 定期备份代码和数据库 -- 遵循版本控制规范，提交信息清晰 +- **项目文档**: [Ulthon Admin 项目文档](https://doc.ulthon.com/read/augushong/ulthon_admin/home/zh-cn/2.x.html) --- -以上规则是 Ulthon Admin 项目开发的基本规范，所有开发者必须严格遵守。遵循这些规则可以提高代码质量，减少开发成本，便于系统维护和扩展。 \ No newline at end of file +## 第二部分：框架开发规则 +> 适用对象：框架作者、核心贡献者 + +### 1. 架构设计理念 + +#### 1.1 双层架构核心 +Ulthon Admin 采用独特的双层架构设计，其中 **基础核心层 (`extend/base/`)** 是框架的基石： + +- **职责**: 存放系统内置的所有核心功能代码，提供标准化的类和接口。 +- **原则**: 保持高度稳定，**严禁依赖具体的业务逻辑**。 +- **框架代码写到 `extend/base/` 目录下**。但所有的调用都是从app目录下开始的。即便是纯框架要用到的代码，也是从app目录下开始调用的。 + - 比如base层有一个 AuthServiceBase 类，在app目录下有一个 AuthService 类，它继承了 AuthServiceBase 类。实际调用时，是从app目录下调用 AuthService 类的方法，而不是从base目录下调用 AuthServiceBase 类的方法。 + - 这样做的好处是，业务代码可以根据需要自由扩展和定制，而不会受到框架核心的影响。 + +### 2. 核心层维护原则 + +- **稳定性优先**: 核心层的任何修改都必须保证向下兼容。 +- **通用性**: 核心代码应具有高度的抽象性，不应包含特定项目的业务逻辑。 + +--- + +## 第三部分：业务系统开发规则 +> 适用对象：业务功能开发者 + +### 1. 开发红线与原则 + +- **核心保护**: 严禁修改 `extend/base/` 目录下的任何文件。 +- **业务隔离**: 所有业务逻辑必须放在 `application/` 目录下。 + +### 2. 扩展机制：继承与重写 + +当需要修改或扩展框架内置功能（如管理员管理、菜单权限）时，请遵循以下机制： + +- **继承**: 业务类继承 `extend/base/` 中的基础类。 +- **重写**: 在业务类中重写父类方法，保持方法签名一致。 +- **调用父类**: 使用 `parent::methodName()` 复用原有逻辑，或者从父类复制代码重新实现。 +- **注意**: 全新开发的业务模块不受此限制，直接在 `application/` 下开发即可。 + +### 3. 标准开发流程 + +1. **设计数据库表结构** + - 严格遵循【第一部分：通用基础规范】中的数据库设计规范。 + +2. **生成基础代码 (CURD)** + - 使用 `php think curd` 命令生成控制器、模型、视图等。 + - 推荐先生成到临时目录 (`-r`) 确认无误。 + +3. **业务代码定制** + - 在生成的代码基础上进行修改。 + - 仅操作 `application/` 目录。 + +4. **测试与验证** + - 功能测试、数据完整性检查、代码规范检查。 + +### 4. 常用开发工具 + +#### 4.1 代码生成命令 (CURD) +> 文档: [CURD 命令详解](https://doc.ulthon.com/read/augushong/ulthon_admin/619efc816472e/zh-cn/2.x.html) + +**常用命令示例**: +```bash +# 生成表 ul_test_goods 的 CURD +php think curd -t test_goods + +# 生成到临时目录 (推荐) +php think curd -t test_goods -r + +# 强制覆盖 +php think curd -t test_goods -f + +# 删除生成的 CURD +php think curd -t test_goods -d +``` + +### 5. 前端开发规范 + +#### 5.1 文件组织 +每个视图 HTML 文件应搭配一个同名的 JS 文件，结构如下： + +```text +goods/ +├── add.html <-- 视图 +├── add.js <-- 对应逻辑 +├── index.html +├── index.js +└── _common.js <-- 模块通用逻辑 +``` + +这种结构确保了逻辑与视图的解耦，便于维护。 \ No newline at end of file