mirror of
https://gitee.com/ulthon/ulthon_admin.git
synced 2026-07-01 15:32:48 +08:00
docs(CODERULE): 重构并优化项目开发规则文档结构
This commit is contained in:
augushong
266
CODERULE.md
266
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 项目开发的基本规范，所有开发者必须严格遵守。遵循这些规则可以提高代码质量，减少开发成本，便于系统维护和扩展。
|
||||
## 第二部分：框架开发规则
|
||||
> 适用对象：框架作者、核心贡献者
|
||||
|
||||
### 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 <-- 模块通用逻辑
|
||||
```
|
||||
|
||||
这种结构确保了逻辑与视图的解耦，便于维护。
|
||||
Reference in New Issue
Block a user