mirror of
https://gitee.com/ulthon/ulthon_admin.git
synced 2026-07-01 23:42:48 +08:00
171 lines
6.5 KiB
Markdown
171 lines
6.5 KiB
Markdown
# Ulthon Admin 开发规则手册
|
||
|
||
本文档分为三部分：
|
||
1. **通用基础规范**：所有开发者（框架作者与业务开发者）均需遵守的基础准则。
|
||
2. **框架开发规则**：针对框架本身的维护者和贡献者。
|
||
3. **业务开发规则**：针对使用框架开发具体业务系统的开发者。
|
||
|
||
---
|
||
|
||
## 第一部分：通用基础规范
|
||
> 适用对象：所有开发者（必须遵守）
|
||
|
||
### 1. 技术栈标准
|
||
|
||
- **核心框架**: ThinkPHP 8.0
|
||
- **开发语言**: PHP 8+
|
||
- **数据库**: MySQL 8+
|
||
- **前端框架**: Layui 2.8.6
|
||
- **模板引擎**: ThinkPHP 内置模板引擎
|
||
- **代码生成器**: 自定义命令行工具
|
||
|
||
### 2. 命名与代码规范
|
||
|
||
所有代码（无论是核心框架还是业务代码）必须严格遵守以下规范：
|
||
|
||
- **命名规范**: [官方命名规范文档](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 标准，建议配置自动格式化工具。
|
||
|
||
### 3. 数据库设计规范
|
||
|
||
- **设计文档**: [官方表结构设计规范](https://doc.ulthon.com/read/augushong/ulthon_admin/619efc9d7af62/zh-cn/2.x.html)
|
||
- **核心要求**:
|
||
- 表名小写，使用下划线分隔。
|
||
- 按照前缀、模块、功能的顺序命名，例如：`ul_mall_goods`。
|
||
- 必须为所有字段编写清晰、完整的注释。
|
||
- 严格遵循文档中的字段类型定义。
|
||
|
||
### 4.在线文档
|
||
|
||
- **项目文档**: [Ulthon Admin 项目文档](https://doc.ulthon.com/read/augushong/ulthon_admin/home/zh-cn/2.x.html)
|
||
|
||
---
|
||
|
||
## 第二部分：框架开发规则
|
||
> 适用对象：框架作者、核心贡献者
|
||
|
||
### 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. **设计数据库表结构**
|
||
- 严格遵循【第一部分：通用基础规范】中的数据库设计规范。
|
||
- 可以直接在数据库中创建表，也可以使用 Scheme 层代码化创建。
|
||
|
||
2. **生成基础代码 (CURD)**
|
||
- 使用 `php think curd` 命令生成控制器、模型、视图等。
|
||
- 推荐先生成到临时目录 (`-r`) 确认无误。
|
||
|
||
3. **业务代码定制**
|
||
- 在生成的代码基础上进行修改。
|
||
- 仅操作 `application/` 目录。
|
||
|
||
4. **测试与验证**
|
||
- 功能测试、数据完整性检查、代码规范检查。
|
||
|
||
### 4. 常用开发工具
|
||
|
||
#### 4.1 代码生成命令 (CURD)
|
||
> 文档: [CURD 命令详解](https://doc.ulthon.com/read/augushong/ulthon_admin/curd-command/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 <-- 模块通用逻辑
|
||
```
|
||
|
||
这种结构确保了逻辑与视图的解耦，便于维护。
|
||
|
||
### 6. Scheme 机制（数据库代码化）
|
||
|
||
Ulthon Admin 引入了 Scheme 层，实现了数据库结构与 PHP 代码的双向同步，便于版本控制和快速迁移。
|
||
|
||
#### 6.1 核心概念
|
||
- **Code to DB (`scheme:sync`)**: 通过编写 PHP 类定义表结构，自动同步到数据库（支持备份原表）。
|
||
- **DB to Code (`scheme:make`)**: 读取现有数据库表结构，反向生成 PHP Scheme 类。
|
||
|
||
#### 6.2 目录规范
|
||
- **业务 Scheme**: `app/admin/scheme/` (所有生成的业务表结构类存放在此)
|
||
|
||
#### 6.3 常用命令
|
||
```bash
|
||
# 将数据库表 ul_test_goods 反向生成为 PHP 代码
|
||
php think scheme:make -t test_goods
|
||
|
||
# 将 app/admin/scheme/ 下的代码同步到数据库 (自动备份原表)
|
||
php think scheme:sync
|
||
```
|
||
|
||
#### 6.4 标准 CURD 开发工作流
|
||
Scheme 机制是 CURD 生成的前置依赖，开发流程如下：
|
||
|
||
1. **设计表结构**：
|
||
- 方式 A：手动创建/修改数据库表结构。
|
||
- 方式 B：手动编写/修改 `app/admin/scheme/` 下的 Scheme 类。（推荐）
|
||
|
||
2. **同步结构（确保一致性）**：
|
||
- 若采用方式 A，执行 `php think scheme:make -t {table}` 将变更同步到 Scheme。
|
||
- 若采用方式 B，执行 `php think scheme:sync` 将变更同步到数据库。
|
||
- **注意**：生成 CURD 前，Scheme 与数据库结构必须完全一致，否则会被拒绝。
|
||
|
||
3. **生成 CURD**：
|
||
- 执行 `php think curd -t {table}` 生成业务代码。
|