---
description: Backend layering responsibilities and Logic-Service boundaries
alwaysApply: true
---

# Backend Layering Rules

| 分层 | 职责 |
| --- | --- |
| **Controller** | 接收请求；补充 header / 路由参数；调用 Validate；构建 DTO；调用 Logic / Service；返回统一响应 |
| **Validate** | 参数必填、类型、长度、格式、枚举、数组结构 |
| **DTO** | 承载已校验参数；做轻量格式整理；**不**做参数合法性判断；**不**查数据库；**不**写业务规则 |
| **Logic** | 负责业务用例、流程编排、事务控制；可以调用本 Logic 内部方法组织步骤；简单逻辑可直接调用 Model；复杂或跨场景复用能力才调用 Service |
| **Service** | 只承载公共能力，例如 center / sdk / 公共配置 / 公共计算 / 跨业务复用逻辑；**不是**每张表都建一个 Service；**不是**把 Logic 方法简单搬过去 |
| **Model** | 数据查询；数据写入；scope / 搜索器 / 关联；把查询条件沉淀成模型方法 |

## Logic 与 Service 边界

- Logic 可以调用自己的私有方法或内部方法，用于拆分步骤、复用当前业务用例内的流程片段。
- 只有当某段能力具备跨场景复用价值、公共计算价值、公共配置访问、外部系统封装等公共属性时，才应抽到 Service。
- 不应创建只做中转的 Service 方法，例如 Logic 调用 Service，Service 再原样调用 Model 或另一个 Logic，且没有封装公共能力。
- 如果确实需要中转层，必须在代码或 PR 说明中解释原因，例如兼容历史接口、统一事务边界、隔离第三方 SDK、收敛跨模块依赖等。