mirror of
https://gitee.com/ulthon/ulthon_admin.git
synced 2026-07-01 15:32:48 +08:00
77da693d80
- 删除独立的 ulthon-core-extend-pattern 技能文档 - 将扩展模式内容整合到 ulthon-base-app-architecture 架构指南 - 简化 AGENTS.md 中的架构说明，移除冗余内容 - 在架构指南中按角色（框架使用者/作者）分章节组织内容
122 lines
5.6 KiB
Markdown
122 lines
5.6 KiB
Markdown
---
|
||
name: "ulthon-base-app-architecture"
|
||
description: "详细说明了 Base/App 双层架构的设计理念、三层结构、身份职责、目录映射、扩展模式及调用红线，帮助开发者理解框架结构并避免误操作。"
|
||
---
|
||
|
||
# Base/App 双层架构
|
||
|
||
本架构旨在解决**框架内核升级**与**业务代码定制**之间的矛盾。请根据您的身份阅读对应部分。
|
||
|
||
## 角色定位
|
||
|
||
| 你的身份 | 你的主要工作 | 请关注章节 |
|
||
| :--- | :--- | :--- |
|
||
| **框架使用者** | 开发具体业务功能、使用框架内置能力 | 一、我是框架使用者（做业务） |
|
||
| **框架作者** | 维护框架内核、修复 Bug、新增通用组件 | 二、我是框架作者（修内核） |
|
||
|
||
---
|
||
|
||
## 一、我是框架使用者（做业务）
|
||
|
||
### 1. 你的地盘与禁区
|
||
|
||
- **自由开发区**：除了 `extend/base/` 之外的所有目录。虽然业务代码通常推荐放在 `app/` 下，但你完全可以在项目中自由发挥。
|
||
- **绝对禁区**：`extend/base/` 目录。**严禁修改**这里的文件，因为 `php think admin:update` 会覆盖它。
|
||
|
||
### 2. 开发场景指南
|
||
|
||
#### 场景 A：新增全新的业务功能
|
||
|
||
直接在 `app/` 下创建控制器、模型或服务即可。不需要关心 Base 层，也不需要继承任何 Base 类（除非你需要利用框架基类的功能）。
|
||
|
||
- 公共代码放在 `app/common/`（工具类、基础类等）
|
||
- 命令类放在 `app/common/command/`（不放在 `app/admin/command/`）
|
||
- 新写业务能力：不需要、也不应该在 `extend/base/` 新建任何 `*Base.php`，这不是业务开发的默认模式
|
||
|
||
#### 场景 B：修改/扩展框架内置功能
|
||
|
||
如果你对框架默认的某个功能（如登录逻辑、CURD流程）不满意，请按以下步骤操作：
|
||
|
||
1. **定位**：找到该功能对应的 `app/` 入口类（例如 `app/admin/model/SystemAdmin.php`）。
|
||
2. **重写**：在该类中重写你需要修改的方法。
|
||
- 保持方法签名（参数、返回值）一致。
|
||
- 可以使用 `parent::method()` 复用父类逻辑，或复制父类代码后自行实现。
|
||
3. **生效**：系统会自动调用你的类，而不是底层的 Base 类。
|
||
|
||
#### 常见误区
|
||
|
||
- 误区：新增业务功能时，也要先在 `extend/base/` 建一个 `*Base` 再在 `app/` 继承
|
||
结论：不需要；这是框架内核维护模式，不是业务开发默认模式
|
||
- 误区：看到框架存在 Base/App 双层机制，就认为所有类都必须走"入口类"
|
||
结论：入口类主要用于"覆盖框架默认实现"，纯业务类可以直接使用，不需要额外包装
|
||
|
||
### 3. 更新机制与保障
|
||
|
||
执行 `php think admin:update` 时，系统会检查框架所有文件的更新：
|
||
|
||
- **Base 层（extend/base/）**：默认为**覆盖更新**（Always Yes），因为这里是内核。
|
||
- **App 层（app/）及其他**：默认为**保护模式**（Default No）。命令会提示即将变动的文件列表。
|
||
- **推荐操作**：一般选择**跳过**，随后根据实际业务代码与上游更新进行对比，手动合并差异。
|
||
- **替代操作**：也可选择**覆盖**，更新后通过 Git 查看差异，并恢复不应变动的业务代码。
|
||
|
||
---
|
||
|
||
## 二、我是框架作者（修内核）
|
||
|
||
### 1. 你的地盘与职责
|
||
|
||
- **你的地盘**：`extend/base/` 目录。通用逻辑、基类代码写在这里。
|
||
- **你的义务**：每在 Base 层新增一个类（如 `UserBase`），**必须**在 `app/` 层提供对应的入口类（如 `User`），并让入口类继承 Base 类。
|
||
|
||
### 2. 开发关键原则（依赖倒置）
|
||
|
||
为了保证使用者的重写能生效，你必须遵守以下**铁律**：
|
||
|
||
> **严禁直接调用 Base 类**
|
||
> 无论在何处，禁止写 `new UserBase()` 或 `UserBase::find()`。
|
||
|
||
> **必须调用 App 入口类**
|
||
> 必须写 `new \app\...\User()`。
|
||
|
||
**为什么？**
|
||
如果代码直接调用了 `UserBase`，那么使用者在 `app/` 下重写的 `User` 类就变成了"摆设"，无法拦截逻辑。只有调用 `app/` 下的子类，多态机制才能生效，使用者才有机会改变行为。
|
||
|
||
### 3. 文件组织规范
|
||
|
||
- **类文件**：以 `*Base.php` 结尾，放在 `extend/base/`。路径和名称与 `app/` 层一一对应。
|
||
- **辅助函数**：放在 `extend/base/helper.php`，通过 `app/common.php` 引入。
|
||
- **初始化数据**：放在 `extend/base/adminInitData/`（带 @internal-framework 注解标记）。
|
||
- **版本更新代码**：放在 `extend/base/adminUpdateCodeData/`（带 @internal-framework 注解标记）。
|
||
- 静态文件/模板/配置支持分层加载：优先加载 `app/`，不存在时再回落到框架默认实现（例如 `app_file_path`）。
|
||
|
||
### 4. 核心层维护原则
|
||
|
||
- 稳定性优先：保证向下兼容
|
||
- 通用性优先：不引入具体业务逻辑
|
||
|
||
---
|
||
|
||
## 三、架构参考资料
|
||
|
||
### 1. 三层结构图解
|
||
|
||
```
|
||
ThinkPHP 框架层（底层基础设施）
|
||
|
|
||
| 继承/扩展
|
||
ulthon_admin 内核层（extend/base/，框架作者维护）
|
||
|
|
||
| 继承/覆盖（依赖倒置：内核只调用 App 层入口）
|
||
App 应用层（app/，框架使用者维护）
|
||
```
|
||
|
||
### 2. 常见目录映射
|
||
|
||
| Base 层（内核实现） | App 层（调用入口） |
|
||
| :--- | :--- |
|
||
| `extend/base/admin/controller/system/AdminBase.php` | `app/admin/controller/system/Admin.php` |
|
||
| `extend/base/admin/model/SystemAdminBase.php` | `app/admin/model/SystemAdmin.php` |
|
||
| `extend/base/common/service/SmsBase.php` | `app/common/service/Sms.php` |
|
||
| `extend/base/common/command/CurdBase.php` | `app/common/command/Curd.php` |
|
||
| `extend/base/common/command/admin/role/AdminRoleCreateBase.php` | `app/common/command/admin/role/AdminRoleCreate.php` |
|