mirror of https://gitee.com/ulthon/ulthon_admin.git synced 2026-07-01 15:32:48 +08:00

Files

2026-03-26 20:22:34 +08:00

4.5 KiB

Raw Blame History

name, description

name	description
ulthon-base-app-architecture	详细说明了 Base/App 双层架构的设计理念、三层结构、身份职责、目录映射、扩展模式及调用红线，帮助开发者理解框架结构并避免误操作。

Base/App 双层架构

本架构旨在解决框架内核升级与业务代码定制之间的矛盾。为了清晰起见，请根据您的身份阅读对应部分。

🎭 角色定位

你的身份	你的主要工作	请关注章节
框架使用者	开发具体业务功能、使用框架内置能力	👉 一、我是框架使用者（做业务）
框架作者	维护框架内核、修复 Bug、新增通用组件	👉 二、我是框架作者（修内核）

一、我是框架使用者（做业务）

1. 你的地盘与禁区

✅ 自由开发区：除了 extend/base/ 之外的所有目录。虽然业务代码通常推荐放在 app/ 下，但你完全可以在项目中自由发挥。
❌ 绝对禁区：extend/base/ 目录。严禁修改这里的文件，因为 php think admin:update 会无情覆盖它。

2. 开发场景指南

场景 A：新增全新的业务功能

直接在 app/ 下创建控制器、模型或服务即可。不需要关心 Base 层，也不需要继承任何 Base 类（除非你需要利用框架基类的功能）。

场景 B：修改/扩展框架内置功能

如果你对框架默认的某个功能（如登录逻辑、CURD流程）不满意，请按以下步骤操作：

定位：找到该功能对应的 app/ 入口类（例如 app/admin/model/SystemAdmin.php）。
重写：在该类中重写你需要修改的方法。
- 保持方法签名（参数、返回值）一致。
- 可以使用 parent::method() 复用父类逻辑。
生效：系统会自动调用你的类，而不是底层的 Base 类。

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/。
辅助函数：放在 extend/base/helper.php，通过 app/common.php 引入。
初始化数据：放在 extend/base/adminInitData/。

三、架构参考资料

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/command/CurdBase.php`	`app/common/command/Curd.php`
`extend/base/common/service/SmsBase.php`	`app/common/service/Sms.php`

4.5 KiB Raw Blame History Unescape Escape