第十课：Controller 层的正确打开方式 —— 接口不是业务层

一、先说结论（这一课到底在解决什么）

绝大多数后端项目烂，不是烂在数据库，不是烂在事务， 而是烂在 Controller 层。

新手 Controller：

• 写业务逻辑
• 控事务
• 拼对象
• try-catch
• 写 SQL
• 写 if/else

成熟系统里的 Controller 只有一句话定位：

👉 Controller 是“接口适配层”，不是业务层。

它只负责： 接请求 → 校验 → 转换 → 调用 → 返回

二、Controller 在分层架构中的真实位置

你现在这套体系是：

interfaces （Controller / DTO / Assembler）
application （用例编排）
domain (业务核心)
infrastructure（底座）

👉 Controller 所在的 interfaces 层，本质是：

协议适配层（HTTP / RPC / MQ → 系统内部模型）

就像 Android 里的：

Activity / ViewModel 负责“接用户输入 + 转换 + 调用业务 + 渲染结果”

它不应该写业务规则。

三、Controller 层只允许干 5 件事

✅ 1. 接收协议输入（HTTP）

@RequestBody
@PathVariable
@RequestParam

✅ 2. 参数校验（接口质量第一道门）

@NotBlank
@NotNull
@Size
@Validated

👉 非法请求必须挡在 Controller。

✅ 3. DTO → 内部模型转换

Controller 不认识 Entity / Domain。

RequestDTO → Command / Query → ApplicationService

👉 这是接口边界，不是啰嗦。

✅ 4. 调用 Application 层

userAppService.register(cmd);

👉 Controller 不直接操作 Domain / Repo。

✅ 5. 统一返回

return Result.ok(dto);

👉 所有异常，交给第9课。

四、Controller 层“绝对禁止”的事

❌ 写业务 if/else ❌ 控事务 ❌ 捕获业务异常 ❌ 拼复杂领域对象 ❌ 写 SQL / 调 Repo ❌ 关心库存、状态机、规则

👉 一句话：Controller 脏，系统必烂。

五、标准工程结构（接口系统结构）

interfaces
└── http
├── controller
├── dto
│ ├── request
│ └── response
└── assembler

• controller：接口入口
• dto：协议模型（HTTP 专用）
• assembler：DTO ↔ 内部模型转换

👉 和 Android 的： ui / vo / mapper 一个思想。

六、标准接口流（工程级）

① Request DTO（协议模型）

public class RegisterReq {
@NotBlank
private String phone;

@NotBlank
private String password;
}

② Command（内部用例模型，application 层）

public class RegisterUserCommand {
private String phone;
private String password;
}

③ Assembler（接口边界）

public class UserAssembler {
public static RegisterUserCommand toCommand(RegisterReq req) {
RegisterUserCommand cmd = new RegisterUserCommand();
cmd.setPhone(req.getPhone());
cmd.setPassword(req.getPassword());
return cmd;
}
}

④ Controller（非常薄）

@RestController
@RequestMapping("/users")
public class UserController {

@PostMapping
public Result<UserDTO> register(@Validated @RequestBody RegisterReq req) {
RegisterUserCommand cmd = UserAssembler.toCommand(req);
UserDTO dto = userAppService.register(cmd);
return Result.ok(dto, RequestId.get());
}
}

👉 这才叫工程级 Controller。

七、参数校验 = Controller 的核心责任

Controller 是系统质量的第一道防线：

• 空参数
• 非法格式
• 越界
• 枚举非法
• 长度攻击

全部挡在这里。

@NotBlank
@Pattern
@Email
@Min @Max

第9课异常体系兜底。

👉 从第10课开始： Service 里不再写参数校验。

八、Controller 和异常体系的配合（第9课联动）

Controller 只做两种事：

• 参数非法 → ValidationException → GlobalHandler
• 业务失败 → BizException → GlobalHandler

Controller 自己不处理。

👉 这是接口系统“稳定性闭环”。

九、你从这一课开始能力发生的变化

你不再是：

❌ 写接口的人

而是在做：

✅ 接口系统设计 ✅ 协议与业务隔离 ✅ 工程边界治理 ✅ 质量防线建设

这一步是从“功能开发”走向“系统工程”的门槛。

十、这一课学完你应该具备的能力

你应该能清楚回答：

• 一个接口从哪进，从哪出
• Controller 能写什么，不能写什么
• DTO 为什么不能复用 Entity
• 参数校验放哪里最合理
• 异常和 Controller 怎么分工

如果你能答清楚这 5 个问题， 👉 第10课你已经站在高级工程师视角了。

十一、一句话总结

Controller 不是业务层， 是系统的“前台大厅”。

大厅越干净，后面的系统才越稳定。

下一篇：

第十课实战版：Controller 层的正确打开方式 —— 接口不是业务层