text

┌─────────────────────────────────────────────────────────────────────┐
│                           支撑层                                     │
│                                                                     │
│  FormRequest（参数校验）  横切 Service（通用能力） Middleware（请求拦截）│
│  Http/Requests/*.php     Services/（Jwt/Dict…）   Http/Middleware/   │
└──────────────────────────────┬──────────────────────────────────────┘
                               │ 被主干层调用 / 前置拦截
                               ▼
┌─────────────────────────────────────────────────────────────────────┐
│                           主干链路                                    │
│                                                                     │
│  ┌─────────────────────────────────────────────────────────────┐   │
│  │ Controller（控制器层）                                        │   │
│  │ 注解标注 → 参数注入 → 调用 Service → 封装响应                  │   │
│  │ 基类：Controller | 文件：app/Http/Controllers/Api/*.php        │   │
│  └──────────────────────────┬──────────────────────────────────┘   │
│                             │ 调用 Service 方法                      │
│                             ▼                                       │
│  ┌─────────────────────────────────────────────────────────────┐   │
│  │ Service（服务层）                                             │   │
│  │ 属性配置 → 唯一性校验 → 生命周期钩子 → 事务 → 调用 Model       │   │
│  │ 基类：BaseService / BaseTenantService | Services/*.php        │   │
│  └──────────────────────────┬──────────────────────────────────┘   │
│                             │ 调用 Eloquent ORM                      │
│                             ▼                                       │
│  ┌─────────────────────────────────────────────────────────────┐   │
│  │ Model（模型层）                                               │   │
│  │ 表映射 → 软删除 → 审计字段 → 关联关系 → ORM → SQL              │   │
│  │ Trait：SoftDeletesByFlag / HasAuditColumns | Models/*.php     │   │
│  └──────────────────────────┬──────────────────────────────────┘   │
│                             ▼                                       │
│  ┌─────────────────────────────────────────────────────────────┐   │
│  │ Database（五种数据库：MySQL / PG / SQL Server / Oracle / SQLite）│
│  └─────────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────────┘

各层职责详解

Controller 层

文件：app/Http/Controllers/Api/{Module}Controller.php基类：App\\Http\\Controllers\\Controller职责：HTTP 请求入口，只做"编排"不做"判断"

职责	说明	示例
参数注入	类型注入 FormRequest 完成格式校验	`add(ExampleRequest $request)`
调用 Service	委托业务逻辑（快捷方法一行调用）	`$this->_add($service, $data)`
响应封装	统一 JSON 格式返回	`$this->success()` / `$this->fail()`
注解标注	声明权限和日志	`#[Permission]`、`#[OperationLog]`

Controller 不应该做：业务判断、数据库操作、文件处理、重复的格式校验。

php

class ExampleController extends Controller
{
    public function __construct(protected ExampleService $exampleService) {}

    // 标准 CRUD —— 一行调用（构造注入，无需 initialize）
    #[OperationLog('示例管理-查询分页', OperationLog::TYPE_QUERY)]
    #[Permission('sys:example:page', '示例分页')]
    public function page(): JsonResponse
    {
        return $this->_page($this->exampleService);
    }

    #[OperationLog('示例管理-新增', OperationLog::TYPE_ADD, '新增示例：{name}')]
    #[Permission('sys:example:add', '添加示例')]
    public function add(ExampleRequest $request): JsonResponse
    {
        return $this->_add($this->exampleService, $request->validated());
    }
}

Service 层

文件：app/Services/{Module}Service.php基类：BaseService（系统共享）/ BaseTenantService（租户隔离）职责：业务核心，通过"属性配置 + 生命周期钩子"声明式 CRUD

职责	方式	说明
行为定义	属性配置	`$pageLikeFields`、`$uniqueFields`、`$serializeMaps` 等 16 个声明式属性
业务定制	生命周期钩子	`beforeAdd`、`afterUpdate`、`beforeDelete` 等 10 个钩子
横切处理	Trait 组合	文件字段、字典翻译、数据权限、租户隔离（6 个 Concerns Trait）
数据安全	`DB::transaction`	add/update/delete/batchDelete 主流程事务包裹

php

class ExampleService extends BaseService
{
    use HasCrudOperations, HasQueryScopes, HasSerializeMaps, HasUniqueCheck;

    protected string $modelClass = Example::class;
    protected array $pageLikeFields = ['name'];
    protected array $pageEqFields = ['status'];
    protected array $uniqueFields = ['name'];
    protected array $serializeMaps = ['status' => 'example_status'];

    // 业务定制：钩子按需重写
    protected function beforeAdd(array $data): array
    {
        $data['sort'] = $data['sort'] ?? 0;
        return $data;
    }
}

Model 层

文件：app/Models/{TableName}.php基类：Eloquent Model + Concerns Trait 职责：数据持久化，只做表映射和自动维护

职责	说明
表映射	`protected $table = 'example'`（不含前缀，`DB_PREFIX` 自动拼接）
软删除	`SoftDeletesByFlag` 注册全局范围自动过滤 `is_delete=1`
审计字段	`HasAuditColumns` 的 `creating/updating` 事件自动填充
关联关系	`hasMany`、`belongsTo`、`belongsToMany` 等

Model 不应该做：业务判断、复杂查询编排（交给 Service）。

php

class Example extends Model
{
    use HasAuditColumns, SoftDeletesByFlag;

    protected $table = 'example';

    // 关联关系（按需定义）
    public function category()
    {
        return $this->belongsTo(Category::class, 'category_id');
    }
}

FormRequest 层（参数校验支撑）

文件：app/Http/Requests/{Module}Request.php基类：BaseRequest职责：参数格式校验（必填、类型、长度、枚举），不含业务规则

php

class ExampleRequest extends BaseRequest
{
    public function rules(): array
    {
        return [
            'name' => 'required|string|max:255',
            'type' => 'nullable|integer|in:1,2,3,4',
        ];
    }
}

触发方式：控制器方法类型注入，方法执行前自动校验；失败由 failedValidation() 返回统一 JSON（code=1 + 字段明细）。

横切 Service（通用能力支撑）

文件：app/Services/{Name}Service.php（横切类）职责：跨模块通用能力，无状态、无副作用

服务	能力
`JwtService`	令牌签发/刷新/解析（Redis 有状态）
`DictCacheService`	字典查询（两级缓存）
`PasswordService`	密码加密（bcrypt，成本因子 12）
`ExcelService`	Excel 导入导出（表头映射、分批）
`CaptchaService`	图片验证码（IP 限流）
`RequestInfoService`	IP 归属地 / OS / 浏览器解析

Middleware 层（请求拦截支撑）

文件：app/Http/Middleware/*.php职责：请求拦截，在 Controller 前后执行

text

ProxyMiddleware → Cors → ForceJsonResponse → Authenticate → ResolveTenant → LogOperation → Controller

中间件	作用	注入数据
`Authenticate`	JWT 认证 + 权限校验	`attributes['userInfo']`
`ResolveTenant`	租户上下文	`attributes['tenantId']` / `isSuperAdmin` / `tenantInfo`
`LogOperation`	操作日志（handle 采集，terminate 落库）	—

各层方法对照表

分页查询链路

层	方法	输入	输出
Controller	`_page($service)`	HTTP 请求参数	JsonResponse
Service	`pageList($params, $where, $with)`	参数数组	`['records'=>[], 'total'=>int, 'current'=>int, 'size'=>int]`
Model	`Model::query()->paginate(...)`	分页条件	LengthAwarePaginator

新增链路

层	方法	输入	输出
Controller	`_add($service, $data)`	FormRequest 校验后的数组	JsonResponse
Service	`add($data)`	snake_case 关联数组	`int`（新记录 ID）
Model	`Model::create($data)`	关联数组	Model 实例

beforeAdd → checkUnique → DB::transaction { Model::create（HasAuditColumns 审计填充）} → afterAdd

修改链路

层	方法	输入	输出
Controller	`_update($service, $id, $data)`	id + 请求数据	JsonResponse
Service	`update($id, $data)`	id + 关联数组	`bool`
Model	`Model::find($id)->update($data)`	模型 + 关联数组	`bool`

删除链路

层	方法	输入	输出
Controller	`_delete($service, $id)`	id	JsonResponse
Service	`delete($id)`	id	`bool`
Model	`$model->softDelete()`	软删除标记	`bool`（`UPDATE SET is_delete=1`）

数据流向

请求方向（前端 → 后端 → 数据库）

text

前端请求（camelCase JSON）
    │
    ▼
FormRequest::validated()              ← 格式校验（camelCase 规则），原样传递
    │
    ▼
Controller::_add($service, $data)     ← 编排 + 注解元数据
    │
    ▼
Service::doAdd 入口                    ← 键名统一转为 snake_case
    │
    ▼
Service::beforeAdd($data)             ← 钩子：预处理
    │
    ▼
Service::checkUnique($data)           ← 唯一性校验（BizException 拦截）
    │
    ▼
DB::transaction {
    Service::processTenantId($data)   ← 租户填充（HasDataScope 启用时）
    Service::processFileFieldsOnSave  ← 文件字段处理（HasFileProcessing 启用时）
    Model::create($data)              ← 审计字段自动填充（creating 事件）
}
    │
    ▼
Database（snake_case）

响应方向（数据库 → 后端 → 前端）

text

Database（snake_case 数据）
    │
    ▼
Model                                 ← ORM 查询（软删除全局范围生效）
    │
    ▼
Service 处理（processAfterRead 处理链）
    │ processFileFieldsOnRead()       ← 文件字段补全域名（启用时）
    │ processSerializeMapsList()      ← 字典显示名补全（status → statusText）
    │ afterDetail()/afterPageList()   ← 钩子：补充关联数据
    ▼
Result::success() / page()            ← snake_case → camelCase 转换
    │
    ▼
JSON 响应 → 前端

异常处理传播

text

Model 层异常（如数据库连接失败）
    │
    ▼ 向上抛出
Service 层异常
    │ beforeAdd/beforeDelete 抛出 BizException（业务规则）
    │ 唯一性校验抛出 BizException
    │ DB::transaction 自动回滚
    ▼ 向上抛出
Controller 层
    │ 方式一：_add/_update/_delete 等快捷方法捕获 BizException → fail(消息, code)
    │ 方式二：不捕获，由全局 Handler 统一处理
    ▼
Exceptions\\Handler::render()
    │ BizException            → {code:异常code(默认1), msg:"业务提示"}
    │ ValidationException     → {code:422, msg:"参数验证失败", data:...}
    │ AuthenticationException → {code:401}
    │ NotFoundHttpException   → {code:404}
    │ 其它异常                 → {code:500, msg:调试原文/生产"操作失败"}
    ▼
JSON 响应

完整请求示例

以"新增案例"为例，展示一个请求从进入到返回的完整链路：

text

POST /api/example/add
Content-Type: application/json
Authorization: Bearer <token>

{"name": "新案例", "type": 1, "status": 1}

text

1. ProxyMiddleware         → 真实 IP 识别（受信代理）
2. Cors                    → 非 OPTIONS，放行（响应时追加 CORS 头）
3. ForceJsonResponse       → Accept 强制 JSON
4. Authenticate            → 校验 Token → 注入 attributes['userInfo']
                             → 反射 #[Permission] → checkPermission('sys:example:add') ✓
5. ResolveTenant           → 注入 tenantId / isSuperAdmin
6. LogOperation(handle)    → 收集上下文，读 #[OperationLog]

7. ExampleRequest
   │ rules() 校验 name/type/status ✓
   │ validated() → ["name"=>"新案例", "type"=>1, "status"=>1]
   ▼
8. ExampleController::add()
   │ 注解元数据已由 4/6 读取
   │ $this->_add($service, $data)
   ▼
9. ExampleService::add($data)
   │ 入口键名转换            → array_camel_to_snake()
   │ beforeAdd($data)            → 默认 sort（钩子）
   │ checkUnique($data)          → name 唯一 ✓
   │ DB::transaction {
   │     Example::create($data)  → creating：create_user/create_time 自动填充
   │ }
   │ afterAdd($id, $data)        → 无额外操作
   ▼
10. Database INSERT → laravel_example → 自增 ID 42

11. 返回 {"code":0, "ok":true, "msg":"添加成功", "data":{"id":42}}

12. LogOperation(terminate) → 写入 laravel_operation_log（响应后，不影响业务）

规则	说明
Controller → Service	✅ 允许，标准调用
Controller → Model	❌ 禁止，越层
Controller → FormRequest	✅ 允许，类型注入
Service → Model	✅ 允许，标准调用
Service → 横切 Service	✅ 允许，调用通用能力（静态/注入均可）
Service → Controller	❌ 禁止，反向依赖
Service → FormRequest	❌ 禁止，格式校验在 HTTP 入口完成
Model → Service / Controller	❌ 禁止，反向依赖
Middleware → 后续链路	✅ 通过 `request->attributes` 注入数据
FormRequest → 业务规则	❌ 禁止，只做格式校验（业务规则在 Service）

4.3 后端分层架构

架构全景

各层职责详解

Controller 层

Service 层

Model 层

FormRequest 层（参数校验支撑）

横切 Service（通用能力支撑）

Middleware 层（请求拦截支撑）

各层方法对照表

分页查询链路

新增链路

修改链路

删除链路

数据流向

请求方向（前端 → 后端 → 数据库）

响应方向（数据库 → 后端 → 前端）

异常处理传播

完整请求示例

层间通信规范

4.3 后端分层架构 ​

架构全景 ​

各层职责详解 ​

Controller 层 ​

Service 层 ​

Model 层 ​

FormRequest 层（参数校验支撑） ​

横切 Service（通用能力支撑） ​

Middleware 层（请求拦截支撑） ​

各层方法对照表 ​

分页查询链路 ​

新增链路 ​

修改链路 ​

删除链路 ​

数据流向 ​

请求方向（前端 → 后端 → 数据库） ​

响应方向（数据库 → 后端 → 前端） ​

异常处理传播 ​

完整请求示例 ​

层间通信规范 ​

4.3 后端分层架构

架构全景

各层职责详解

Controller 层

Service 层

Model 层

FormRequest 层（参数校验支撑）

横切 Service（通用能力支撑）

Middleware 层（请求拦截支撑）

各层方法对照表

分页查询链路

新增链路

修改链路

删除链路

数据流向

请求方向（前端 → 后端 → 数据库）

响应方向（数据库 → 后端 → 前端）

异常处理传播

完整请求示例

层间通信规范