architecture-layering

name	architecture-layering
description	MallBase ThinkPHP 后端分层、Swoole Service 无状态与 IDE 泛型规则；开发或重构 backend/app 下的 Controller、Service、Model，调整 BaseController/BaseService、service()/model() 调用、构造注入或协程安全状态时使用。

ThinkPHP 分层与无状态规则

当前目录

• Controller：backend/app/controller/{admin,client,...}/
• Service：backend/app/service/{admin,client,...}/
• Model：backend/app/model/
• 基类：backend/mall_base/base/BaseController.php、BaseService.php

分层职责

1. 让 Controller 只负责读取请求参数、调用验证器、调用 Service 和返回响应。
2. 把业务判断、跨模型编排、事务边界和结果组装放在 Service。
3. 把表映射、关系、类型转换和字段访问语义放在 Model。
4. 优先经所属领域的 Service 复用业务不变量；只有纯数据访问且不会绕过领域约束时，才直接使用其它 Model。
5. 保持 Controller -> Service -> Model 为主调用方向，不在 Model 中反向调用 Controller 或请求对象。

Swoole 无状态

1. 不在 Service 属性、static 或全局变量中保存请求参数、当前用户、查询构造器或 Model 实例。
2. 通过 $this->model() 按需创建 Model；不要缓存其返回值供后续请求复用。
3. 允许构造注入无请求态的只读协作者，例如 private readonly AssetResolver $resolver。
4. SDK、驱动或客户端若含签名上下文、请求头或可变配置，按其专用 skill 决定生命周期，不默认做容器单例。

泛型与跳转

新增或修改继承基类的类时，保持具体泛型和默认类名一致：

/** @extends BaseController<GoodsService> */
class GoodsController extends BaseController
{
    protected string $serviceClass = GoodsService::class;
}

/** @extends BaseService<Goods> */
class GoodsService extends BaseService
{
    protected string $modelClass = Goods::class;
}

BaseController::service() 和 BaseService::model() 已提供方法级模板；传入具体 ::class 时保留类型推导，不再增加无收益的取实例包装。

自检

• Controller 中没有业务编排或直接持久化。
• Service 没有请求级可变状态和 Model/查询缓存。
• 业务约束没有被跨领域直接写表绕过。
• @extends、$serviceClass、$modelClass 指向同一具体类型。