架构与系统设计 / 系统课时
Controller 里应该写多少逻辑
Controller 里应该写多少逻辑
Controller 并不是越短越好,而是只保留与接口边界有关的逻辑。参数格式校验、粗粒度访问控制、应用用例调用和响应转换可以留在 Controller;需要表达业务政策、状态约束或跨步骤编排的代码则应移出接口层。
学习目标
- 区分 Controller 中可以保留和应该移出的逻辑
- 理解参数校验与业务校验、接口权限与业务权限的差别
- 能设计一个职责清晰但不过度空壳化的 Controller
用四类逻辑划清边界
Controller 中最常见的代码可以按变化原因分成四类。边界清楚后,不需要用固定行数判断 Controller 是否“太厚”。
| 逻辑 | 常见归属 | 判断依据 |
|---|---|---|
| 参数解析与格式校验 | 接口层 | 与 HTTP、JSON、字符串格式等外部协议有关 |
| 粗粒度访问控制 | 接口层或框架中间件 | 判断调用者能否访问某类接口 |
| 用例调用与业务编排 | 应用层 | 换成消息入口或定时任务后仍然需要 |
| 响应 DTO 与状态码转换 | 接口层 | 只为外部协议服务 |
权限尤其容易混淆。比如“用户是否具有 order:cancel 接口权限”可以在接口边界处理;但“只能取消自己创建且尚未发货的订单”需要读取业务数据并表达业务约束,更适合由应用层和领域层完成。
一个保持薄而不空的 Controller
下面的示例保留三件接口层应该做的事情:检查请求结构、执行粗粒度权限检查、调用应用用例并转换返回值。订单当前是否允许取消没有出现在 Controller 中。
public class CancelOrderControllerDemo {
record UserContext(String userId, boolean canCancelOrder) {}
record CancelOrderRequest(String orderId, String reason) {}
record CancelOrderCommand(String operatorId, String orderId, String reason) {}
record CancelOrderResult(String orderId, String status) {}
record ApiResponse(int status, String body) {}
interface CancelOrderUseCase {
CancelOrderResult handle(CancelOrderCommand command);
}
static final class CancelOrderController {
private final CancelOrderUseCase useCase;
CancelOrderController(CancelOrderUseCase useCase) {
this.useCase = useCase;
}
ApiResponse cancel(UserContext user, CancelOrderRequest request) {
if (request.orderId() == null || request.orderId().isBlank()) {
return new ApiResponse(400, "orderId is required");
}
// 这里只检查调用者是否具有进入该用例的粗粒度权限。
if (!user.canCancelOrder()) {
return new ApiResponse(403, "forbidden");
}
var command = new CancelOrderCommand(
user.userId(), request.orderId(), request.reason());
var result = useCase.handle(command);
return new ApiResponse(
200, "order=" + result.orderId() + ",status=" + result.status());
}
}
public static void main(String[] args) {
CancelOrderUseCase useCase = command ->
new CancelOrderResult(command.orderId(), "CANCELED");
var controller = new CancelOrderController(useCase);
var user = new UserContext("U-01", true);
var request = new CancelOrderRequest("ORD-1001", "duplicate order");
var response = controller.cancel(user, request);
System.out.println(response.status() + " " + response.body());
}
}预期输出
200 order=ORD-1001,status=CANCELED真实系统中的 CancelOrderUseCase 还应加载订单并判断订单状态、操作者与订单的关系等业务条件。即使这些判断只需要几行代码,也不应为了减少一次方法调用而塞回 Controller。
参数校验不要吞掉业务规则
接口层校验主要保证输入能够被系统理解,例如必填字段存在、日期字符串能解析、枚举值属于协议允许的集合。它的失败通常意味着请求格式本身有问题。
业务校验则回答“这个操作现在是否允许”。例如取消原因是否满足特定业务政策、订单是否已经发货、当前客户是否拥有该订单。这些规则即使换成消息消费者调用也依然成立,因此不应绑定在 HTTP Controller 上。
不要用代码行数判断 Controller 是否过重
一个只有十几行的 Controller 也可能越界,例如直接读取仓储、修改领域对象并决定折扣;一个稍长的 Controller 如果主要在解析协议字段、处理不同响应码和映射 DTO,仍可能属于合理的接口适配代码。
检查 Controller 时可以问几个问题:删除 HTTP 或 JSON 后,这段逻辑是否仍有意义;同一个用例改由消息消费者触发后,这条规则是否还必须执行;规则是否会随着业务政策而变化。如果答案指向协议之外,就应该把逻辑移到应用层或领域层。
Controller 最合适的状态不是“没有逻辑”,而是只拥有接口边界所需的逻辑。这样接口代码能清楚表达请求如何进入系统,同时核心业务不会随着 Web 框架、传输协议或响应格式一起变化。