在 spring boot 中，应保持成功响应（apiresponse）与错误响应（errorresponse）的结构分离，通过 http 状态码区分语义；前端依据 status 判断响应类型并分别解析，而非强行合并两类 dto。
在构建健壮的 RESTful API 时，一个常见误区是试图将“成功响应”和“错误响应”强制统一为同一个 Java 类（如让 GlobalExceptionHandler 返回 ApiResponse
✅ 正确做法是：职责分离 + 状态驱动
- ✅ 成功路径：控制器返回 ResponseEntity
>，HTTP 状态码为 2xx（如 200 OK） - ✅ 异常路径：@RestControllerAdvice 返回 ResponseEntity
，HTTP 状态码为对应错误码（如 400 Bad Request、404 Not Found、500 Internal Server Error） - ✅ 前端不依赖响应体结构判断成败，而优先检查 response.status —— 这是 REST 的契约基石。
以下是推荐的实现结构：
1. 保持两类响应体清晰独立
// 成功响应包装器（泛型，含时间戳、消息、业务数据） public class ApiResponse{ private final long timestamp; private final String message; private final T data; public ApiResponse(long timestamp, String message, T data) { this.timestamp = timestamp; this.message = message; this.data = data; } // getters... } // 错误响应（含状态码、用户提示、可选详情） public class ErrorResponse { private final int status; private final String message; private final List errors; // 如校验失败字段 public ErrorResponse(int status, String message, List errors) { this.status = status; this.message = message; this.errors = errors; } // getters... }
2. 全局异常处理器严格返回 ErrorResponse
@RestControllerAdvice
public class GlobalExceptionHandler {
@ExceptionHandler(ResourceNotFoundException.class)
public ResponseEntity handleNotFound(ResourceNotFoundException ex) {
ErrorResponse error = new ErrorResponse(
HttpStatus.NOT_FOUND.value(),
"Resource not found",
Collections.singletonList(ex.getMessage())
);
return ResponseEntity.status(HttpStatus.NOT_FOUND).body(error);
}
@ExceptionHandler(MethodArgumentNotValidException.class)
public ResponseEntity handleValidation(MethodArgumentNotValidException ex) {
List errors = ex.getBindingResult().getFieldErrors().stream()
.map(e -> e.getField() + ": " + e.getDefaultMessage())
.collect(Collectors.toList());
ErrorResponse error = new ErrorResponse(
HttpStatus.BAD_REQUEST.value(),
"Validation failed",
errors
);
return ResponseEntity.badRequest().body(error);
}
} 3. 控制器专注业务逻辑，不掺杂错误结构
@GetMapping("/units/{id}")
public ResponseEntity> findById(@PathVariable long id) {
UnitResponse response = unitService.findById(id);
long ts = Instant.now(clock).toEpochMilli();
return ResponseEntity.ok(new ApiResponse<>(ts, "Success", response));
} ⚠️ 关键注意事项
- ❌ 不要修改 @ExceptionHandler 方法签名去返回 ApiResponse
—— 这会破坏 HTTP 语义（例如 200 OK 携带错误内容），且使前端无法通过状态码做快速分流。 - ✅ 前端必须基于 response.status 分支处理：status >= 400 → 解析为 ErrorResponse；否则 → 解析为 ApiResponse
。 - ✅ 可借助 Axios 拦截器或 Fetch 封装层自动完成状态判断与错误抛出（如 throw new ApiError(errorResponse)），避免每个请求手动判 status。
- ✅ ErrorResponse 中的 status 字段是冗余的（HTTP 状态码已足够），建议仅保留语义化字段（message, errors, timestamp），避免前后端重复解析。
总结：RESTful 的灵魂在于“用标准协议表达意图”。状态码是 HTTP 层的权威信使，响应体是业务层的结构化载荷。二者协同，而非妥协统一——这才是可扩展、易调试、符合生态规范的 Spring Boot API 设计之道。
