---
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` |