4.11 扩展性设计

概述

系统通过六种机制保证良好的扩展性：属性配置、生命周期钩子、自动参数校验、中间件链、注解系统、服务层复用。新增模块无需修改框架代码，只需继承基类 + 配置属性 + 按需重写钩子。

扩展机制总览

机制	位置	作用	扩展方式
属性配置	Logic 子类	声明式行为定义	设置属性值
生命周期钩子	Logic 子类	注入定制逻辑	重写钩子方法
自动参数校验	Validate + Logic	参数格式校验	创建 Validate + 配置 `$validateClass`
中间件链	middleware/	请求拦截处理	创建中间件 + 注册
注解系统	attribute/	声明式元数据	创建注解 + 中间件读取
服务层复用	service/	跨模块通用能力	创建 Service 类

1. 属性配置模式

Logic 层通过属性配置声明行为，新增模块只需设置属性，无需编写 CRUD 代码。

完整属性清单

php

class NewModuleLogic extends BaseLogic
{
    /**
     * 关联的模型类
     *
     * 所有增删改查操作都会基于此模型执行，子类必须指定
     *
     * @var string
     */
    protected string $modelClass = NewModule::class;

    /**
     * 参数验证器类
     *
     * 配置后，新增 / 修改等操作会自动调用该验证器进行参数校验，
     * 校验不通过会直接抛出异常，无需在业务代码中手动验证
     *
     * @var string
     */
    protected string $validateClass = NewModuleValidate::class;

    /**
     * 需要自动处理的文件上传字段
     *
     * 提交数据中若包含这些字段，框架会自动完成文件上传、存储与路径回填
     *
     * @var array
     */
    protected array $fileFields = ['cover', 'avatar'];

    /**
     * 文件保存的子目录
     *
     * 上传的文件会保存在该子目录下（相对于文件存储根目录）
     *
     * @var string
     */
    protected string $fileSaveDir = 'new_module';

    /**
     * 富文本字段
     *
     * 这些字段会做富文本特殊处理（如 XSS 过滤、图片路径修正等）
     *
     * @var array
     */
    protected array $contentFields = ['content'];

    /**
     * 列表查询中需要 LIKE 模糊匹配的字段
     *
     * 请求参数中若带有这些字段，会自动以 LIKE '%value%' 的方式参与查询
     *
     * @var array
     */
    protected array $pageLikeFields = ['name', 'title'];

    /**
     * 列表查询中需要精确匹配的字段
     *
     * 请求参数中若带有这些字段，会自动以 = 的方式参与查询
     *
     * @var array
     */
    protected array $pageEqFields = ['status', 'type'];

    /**
     * 列表查询的默认排序规则
     *
     * field：排序字段；type：排序方式（asc / desc）
     *
     * @var array
     */
    protected array $pageOrderBy = ['field' => 'sort', 'type' => 'asc'];

    /**
     * 唯一性校验字段
     *
     * 支持两种写法：
     * - 字符串：单字段全局唯一，如 'code'
     * - 数组：多字段组合唯一，如 ['name', 'pid'] 表示同层级下 name 唯一
     *
     * 新增 / 修改时会自动校验，冲突则抛出异常
     *
     * @var array
     */
    protected array $uniqueFields = ['code', ['name', 'pid']];

    /**
     * 枚举字段与显示名的映射
     *
     * 键为数据表字段名，值为对应的枚举字典 key，
     * 返回数据时会自动附加对应的枚举显示名（如 status_text）
     *
     * @var array
     */
    protected array $serializeMaps = ['status' => 'module_status'];

    /**
     * 数据权限-按创建人过滤的字段
     *
     * 配置后，非管理员用户只能看到自己创建的数据
     *
     * @var string
     */
    protected string $dataScopeUserField = 'create_user';

    /**
     * 数据权限-按部门过滤的字段
     *
     * 配置后，非管理员用户只能看到本部门（及子部门）的数据
     *
     * @var string
     */
    protected string $dataScopeDeptField = 'dept_id';

    /**
     * 租户隔离字段
     *
     * 继承 BaseTenantLogic 时自动启用，所有查询会自动追加 tenant_id 条件，
     * 保证多租户之间的数据完全隔离
     *
     * @var string
     */
    // protected string $tenantScopeField = 'tenant_id';

    /**
     * 树形结构的父级字段
     *
     * 配置后，列表接口会自动将平铺数据组装成树形结构
     *
     * @var string
     */
    protected string $treeParentField = 'parent_id';

    /**
     * 树形结构的搜索字段
     *
     * 树形搜索时对该字段做模糊匹配，命中节点会自动保留其父链
     *
     * @var string
     */
    protected string $treeLikeField = 'name';
}

属性驱动的自动行为

属性	触发的自动行为
`validateClass`	add/update 时自动调用验证器校验参数
`fileFields`	add/update 时迁移临时文件，查询时补全域名
`contentFields`	add/update 时处理富文本媒体文件，查询时替换占位符
`pageLikeFields`	pageList 时自动构建 LIKE 查询
`pageEqFields`	pageList 时自动构建精确查询
`pageOrderBy`	pageList/allList 时自动应用默认排序
`uniqueFields`	add/update 时自动校验唯一性
`serializeMaps`	查询时自动补全 `{字段名}Text` 枚举显示名
`dataScopeUserField`	查询时自动按创建人过滤
`dataScopeDeptField`	查询时自动按部门过滤
`tenantScopeField`	查询时自动叠加 tenant_id 条件，新增时自动填充

2. 生命周期钩子

通过重写钩子注入定制逻辑，无需修改基类。钩子方法在基类中定义为空实现或默认返回，子类按需覆盖。

钩子清单

钩子	时机	参数	返回值	可拦截
`beforeAdd`	新增前	`$data`	处理后的 `$data`	✅ 抛异常
`afterAdd`	新增后	`$id, $data`	void	❌
`beforeUpdate`	修改前	`$id, $data`	处理后的 `$data`	✅ 抛异常
`afterUpdate`	修改后	`$id, $data`	void	❌
`beforeDelete`	删除前	`$id`	void	✅ 抛异常
`afterDelete`	删除后	`$id`	void	❌
`beforeBatchDelete`	批量删除前	`$ids`	void	✅ 抛异常
`afterBatchDelete`	批量删除后	`$ids`	void	❌
`afterDetail`	详情查询后	`$id, &$data`	void（引用传递）	❌
`afterPageList`	列表查询后	`&$records, $params`	void（引用传递，分页与全量列表均触发）	❌

典型用法

php

class ArticleLogic extends BaseTenantLogic
{
    /**
     * 新增前处理：设置默认值
     *
     * @param array $data 待新增的数据
     * @return array 处理后的数据
     */
    protected function beforeAdd(array $data): array
    {
        // sort：排序字段，若未传则默认为 0
        $data['sort']   = $data['sort'] ?? 0;
        // author：作者字段，若未传则尝试从当前登录用户信息中取用户名
        $data['author'] = $data['author'] ?? request()->userInfo->username ?? '';
        return $data;
    }

    /**
     * 新增后处理：保存关联数据
     *
     * @param int   $id   新增文章的主键 ID
     * @param array $data 新增时提交的原始数据
     * @return void
     */
    protected function afterAdd(int $id, array $data): void
    {
        // 若提交数据中带有 tags（标签数组），则批量写入文章-标签关联表
        if (!empty($data['tags'])) {
            ArticleTag::insertAll(array_map(fn($tag) => [
                'article_id' => $id, 'tag' => $tag
            ], $data['tags']));
        }
    }

    /**
     * 修改前处理：过滤不可修改字段
     *
     * @param int   $id   文章 ID
     * @param array $data 待更新的数据
     * @return array 过滤后的数据
     */
    protected function beforeUpdate(int $id, array $data): array
    {
        // author（作者）字段不允许通过更新接口修改，直接剔除
        unset($data['author']);
        return $data;
    }

    /**
     * 删除前处理：业务约束校验
     *
     * @param int $id 文章 ID
     * @return void
     * @throws \Exception 文章下存在评论时抛出
     */
    protected function beforeDelete(int $id): void
    {
        // 若该文章下存在评论，则不允许删除
        $commentCount = Comment::where('article_id', $id)->count();
        if ($commentCount > 0) {
            throw new \Exception('该文章下存在评论，不可删除');
        }
    }

    /**
     * 详情查询后处理：补充单条记录的关联数据
     *
     * @param int   $id   文章 ID
     * @param array &$data 详情数据（引用传递）
     * @return void
     */
    protected function afterDetail(int $id, array &$data): void
    {
        $data['tags']         = ArticleTag::where('article_id', $id)->column('tag');
        $data['commentCount'] = Comment::where('article_id', $id)->count();
    }

    /**
     * 列表查询后处理：批量补充关联数据
     *
     * @param array &$records 记录列表（引用传递）
     * @param array $params   查询参数
     * @return void
     */
    protected function afterPageList(array &$records, array $params): void
    {
        if (empty($records)) return;

        // 提取当前页所有文章 ID
        $ids = array_column($records, 'id');

        // 一次性统计每篇文章的评论数，返回 [article_id => count] 结构
        $counts = Comment::whereIn('article_id', $ids)
            ->group('article_id')
            ->column('count(*)', 'article_id');

        // 将统计结果回填到每条记录
        foreach ($records as &$record) {
            $record['commentCount'] = $counts[$record['id']] ?? 0;
        }
    }
}

执行顺序

add 流程：beforeAdd → validateData → camel_to_snake → processTenantId → processFile → processContent → filterTableFields → checkUnique → Model::create → afterAdd

update 流程：beforeUpdate → validateData → camel_to_snake → processFile → processContent → filterTableFields → checkUnique → Model::find + save → afterUpdate

delete 流程：beforeDelete → is_delete = 1 → afterDelete

pageList/allList 流程：buildQuery → 排序 → 分页 → processFile → processContent → processSerializeMaps → filterFields → afterPageList

3. 自动参数校验

通过在 Logic 中配置 $validateClass，add/update 时自动调用验证器，无需手动调用。

扩展方式

php

// 1. 创建验证器
// app/validate/NewModuleValidate.php
class NewModuleValidate extends Validate
{
    protected $rule = [
        'name' => 'require|max:100',
        'code' => 'require|unique:new_module',
    ];
    protected $message = [
        'name.require' => '名称不能为空',
        'code.unique'  => '编码已存在',
    ];
    protected $scene = [
        'add'    => ['name', 'code'],
        'update' => ['name'],
    ];
}

// 2. 在 Logic 中配置
class NewModuleLogic extends BaseLogic
{
    protected string $validateClass = NewModuleValidate::class;
    // ...
}

详见 3.4 验证器开发。

4. 中间件机制

通过中间件链式处理请求，可灵活添加新的拦截逻辑。

现有中间件

text

请求进入
    │
    ▼
CorsMiddleware（全局）     ← OPTIONS 预检 + 跨域响应头
    │
    ▼
AuthMiddleware（路由级）   ← JWT 认证 + 权限校验 → 401/403
    │ 注入 userInfo
    ▼
TenantMiddleware（路由级） ← 租户上下文注入 → 403
    │ 注入 tenantId
    ▼
DemoMiddleware（路由级）   ← 演示环境拦截写操作 → 403
    │
    ▼
LogMiddleware（路由级）    ← 操作日志记录
    │
    ▼
控制器方法

创建自定义中间件

php

// 1. 创建中间件类
// app/middleware/RateLimitMiddleware.php
namespace app\middleware;

use think\facade\Cache;

class RateLimitMiddleware
{
    public function handle($request, \Closure $next)
    {
        $ip = $request->ip();
        $key = 'rate_limit_' . $ip;
        $count = Cache::get($key, 0);

        if ($count > 100) {
            return json(['code' => 1, 'msg' => '请求过于频繁'], 429);
        }

        Cache::set($key, $count + 1, 60);
        return $next($request);
    }
}

// 2. 注册中间件
// 方式一：全局注册（app/middleware.php）
return [
    \app\middleware\RateLimitMiddleware::class,
];

// 方式二：路由级注册（route/app.php）
Route::group('api', function () {
    // ...
})->middleware(\app\middleware\RateLimitMiddleware::class);

// 方式三：控制器级注册
class SomeController extends BaseController
{
    protected $middleware = [
        \app\middleware\RateLimitMiddleware::class,
    ];
}

5. 注解系统

通过 PHP 8 注解声明元数据，中间件通过反射读取，业务代码零侵入。

现有注解

注解	目标	说明	读取方
`#[Log]`	方法	操作日志（标题、类型、描述）	LogMiddleware
`#[Permission]`	方法/类	权限校验（权限编码）	AuthMiddleware
`#[DemoAllow]`	方法	演示环境放行标记	DemoMiddleware

使用示例

php

// 操作日志
#[Log('用户管理-新增记录', Log::TYPE_ADD, '新增用户：{username}')]

// 权限校验
#[Permission('sys:user:add', '添加用户')]

// 演示环境放行（允许在演示环境执行写操作）
#[DemoAllow]

// 组合使用
#[Log('文章管理-删除记录', Log::TYPE_DELETE, '删除文章ID:{id}')]
#[Permission('sys:article:delete', '删除文章')]
public function delete(int $id): Json
{
    return parent::_remove($this->logic, $id);
}

创建自定义注解

php

// 1. 定义注解类
// app/attribute/Cacheable.php
namespace app\attribute;

use Attribute;

#[Attribute(Attribute::TARGET_METHOD)]
class Cacheable
{
    public function __construct(
        public string $key = '',
        public int $ttl = 3600,
    ) {}
}

// 2. 在控制器方法上使用
#[Cacheable(key: 'article_list', ttl: 1800)]
public function list(): Json { ... }

// 3. 在中间件中读取
// 通过 AttributeService 或反射获取注解实例
$ref = new \ReflectionMethod($controller, $method);
$attrs = $ref->getAttributes(Cacheable::class);
if (!empty($attrs)) {
    $cacheable = $attrs[0]->newInstance();
    // $cacheable->key, $cacheable->ttl
}

注解读取服务

AttributeService 提供统一的注解读取接口（带缓存）：

php

AttributeService::getLog($class, $method);       // 获取 Log 注解
AttributeService::getPermission($class, $method); // 获取 Permission 注解

6. 服务层复用

通用能力封装为 Service，跨模块复用，无状态、无副作用。

现有服务清单

服务	文件	能力
`JwtService`	`app/service/JwtService.php`	登录、刷新、解析 Token
`PasswordService`	`app/service/PasswordService.php`	bcrypt 双重加盐加密
`DictService`	`app/service/DictService.php`	字典查询（两级缓存）
`ParamService`	`app/service/ParamService.php`	系统参数查询（两级缓存）
`CaptchaService`	`app/service/CaptchaService.php`	图片验证码生成与校验
`RequestInfoService`	`app/service/RequestInfoService.php`	客户端 IP、UA、归属地解析
`AttributeService`	`app/service/AttributeService.php`	注解反射读取 + 缓存
`GeneratorService`	`app/service/GeneratorService.php`	代码生成
`ExcelService`	`app/service/ExcelService.php`	Excel 导入导出
`DbMigrateService`	`app/service/DbMigrateService.php`	跨数据库迁移引擎
`DbSchemaBuilder`	`app/service/DbSchemaBuilder.php`	DDL 生成器（跨库映射）

使用示例

php

// 字典服务
DictService::getText('gender', 1);              // → '男'
DictService::getValue('user_status', '启用');    // → 1
DictService::getOptions('gender');               // → [['value'=>0,'label'=>'女'], ...]

// 密码服务
$encrypted = PasswordService::encrypt('123456'); // → ['password'=>'...', 'salt'=>'...']
$default = PasswordService::getDefaultPasswordPlain(); // → '123456'

// Excel 服务
ExcelService::importWithMap($filePath, $headerMap);
ExcelService::chunkExport($headers, $callback, '导出.xlsx', 500);

// 请求信息
$requestInfo = RequestInfoService::create(request());
$ip = $requestInfo->getIp();           // 客户端 IP（经 ProxyMiddleware 还原真实 IP）
$location = $requestInfo->getIpLocation(); // IP 归属地（基于 zoujingli/ip2region）
$os = $requestInfo->getOs();           // 操作系统
$browser = $requestInfo->getBrowser(); // 浏览器

创建自定义服务

php

// app/service/NotificationService.php
namespace app\service;

class NotificationService
{
    // 发送站内通知
    public static function send(int $userId, string $title, string $content): void
    {
        \app\model\Notice::create([
            'user_id' => $userId,
            'title'   => $title,
            'content' => $content,
            'status'  => 0,
        ]);
    }

    // 批量发送
    public static function batchSend(array $userIds, string $title, string $content): void
    {
        foreach ($userIds as $userId) {
            self::send($userId, $title, $content);
        }
    }
}

// 使用
NotificationService::send($userId, '系统通知', '您有一条新消息');

扩展性设计原则

开闭原则（OCP）

扩展场景	做法	不应该做
新增 CRUD 模块	创建 Controller/Logic/Model/Validate	修改基类
新增查询条件	设置 `pageLikeFields`/`pageEqFields`	重写 `buildQuery`
新增文件处理	设置 `fileFields`	手动调用 `save_file`
新增校验规则	创建 Validate + 配置 `validateClass`	在 Controller 手动 validate
新增请求拦截	创建中间件	修改现有中间件
新增操作日志	添加 `#[Log]` 注解	在方法内手动记录日志
新增权限节点	添加 `#[Permission]` 注解	在方法内手动校验权限
新增通用能力	创建 Service	在 Logic 中写静态方法

最小改动原则

新增一个完整的业务模块，只需要：

建表（含公共字段）
创建 Model（继承 BaseModel，声明表名）
创建 Validate（定义规则 + 场景）
创建 Logic（继承 BaseLogic/BaseTenantLogic，配置属性）
创建 Controller（继承 BaseController，初始化 Logic，CRUD 一行调用）
注册路由

不需要修改的文件： 基类、中间件、配置文件、服务层。

Become a sponsor

企业级中台解决方案

企业级中台解决方案

4.11 扩展性设计 ​

扩展机制总览 ​

1. 属性配置模式 ​

完整属性清单 ​

属性驱动的自动行为 ​

2. 生命周期钩子 ​

钩子清单 ​

典型用法 ​

执行顺序 ​

3. 自动参数校验 ​

扩展方式 ​

4. 中间件机制 ​

现有中间件 ​

创建自定义中间件 ​

5. 注解系统 ​

现有注解 ​

使用示例 ​

创建自定义注解 ​

注解读取服务 ​

6. 服务层复用 ​

现有服务清单 ​

使用示例 ​

创建自定义服务 ​

扩展性设计原则 ​

开闭原则（OCP） ​

最小改动原则 ​

4.11 扩展性设计

扩展机制总览

1. 属性配置模式

完整属性清单

属性驱动的自动行为

2. 生命周期钩子

钩子清单

典型用法

执行顺序

3. 自动参数校验

扩展方式

4. 中间件机制

现有中间件

创建自定义中间件

5. 注解系统

现有注解

使用示例

创建自定义注解

注解读取服务

6. 服务层复用

现有服务清单

使用示例

创建自定义服务

扩展性设计原则

开闭原则（OCP）

最小改动原则