---
name: "ulthon-core-extend-pattern"
description: "业务开发默认只写 app；需要改内置能力时，通过 app 入口类覆盖 *Base 默认实现。"
---

# 扩展内置能力（继承与重写）

## 何时调用

- 需要新增业务能力（新控制器/模型/服务/命令等）：直接在 `app/` 写代码。
- 需要扩展/调整系统已有能力（默认实现存在于 `extend/base/`）：在 `app/` 下对应入口类重写以覆盖默认实现。

## 关键原则

- 新写业务代码：只写 `app/`，不需要、也不应该去 `extend/base/` 做任何“对齐”。
- 改内置能力：只改 `app/` 下对应入口类（必要时 `extends` 对应 `*Base`）。
- 严禁直接修改 `extend/base/` 下任何文件。
- 重写时保持方法签名一致；可用 `parent::method()` 复用父类逻辑，或复制父类代码后自行实现。

## 操作流程

### A. 新写业务能力（推荐默认路径）

1. 直接在 `app/` 下创建需要的控制器/模型/服务/命令等类文件（按项目命名规范与目录约定放置）。
2. 让业务入口只依赖 `app/` 下的类，不需要为“对应 Base 层文件”做额外映射。

### B. 覆盖框架默认行为（扩展/调整已有能力）

1. 定位对应的 `*Base` 默认实现文件路径（通常在 `extend/base/`）。
2. 在 `app/` 下创建或修改同路径的入口类文件，并 `extends` 对应 `*Base`。
3. 在入口类中重写需要调整的方法，确保方法签名一致。

## 常见误区（避免歧义）

- 误区：新增业务功能时，也要先在 `extend/base/` 建一个 `*Base` 再在 `app/` 继承  
  结论：不需要；这是框架内核维护模式，不是业务开发默认模式
- 误区：看到框架存在 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/admin/role/AdminRoleCreateBase.php` → `app/common/command/admin/role/AdminRoleCreate.php`