Spring接口出错时返回泛型ResponseEntity还是抛出异常更好？

结论 #

优先选择抛出自定义业务异常，交由 @ControllerAdvice 全局统一处理，仅在极特殊的单接口独有错误场景下可以考虑使用 ResponseEntity<*>。

原因说明 #

• 类型更安全
  使用 ResponseEntity<*> 等于直接放弃了泛型的编译期类型校验，后续维护人员无法直接从方法签名判断接口的正常返回类型，也没法提前发现错误返回的类型不匹配问题。而异常方案不需要修改原方法的返回类型，ResponseEntity<CustomerResponse> 可以明确表示接口正常返回的结构，符合强类型语言的编码规范。
• 代码更简洁
  Controller 层只需要关注核心业务的正常流程，错误场景直接抛出对应异常即可，不需要在每个方法里重复编写构造错误响应、设置HTTP状态码的冗余代码。
• 维护成本更低
  所有错误响应的格式、状态码、日志打印、错误上报逻辑都可以集中在全局异常处理器里管理，后续如果要调整 ErrorResponse 的字段结构、新增错误统一处理逻辑，只需要修改一处代码，不需要挨个调整所有Controller的错误分支。
• 扩展性更强
  后续新增错误类型时，只需要定义对应的自定义异常类，在全局异常处理器中新增对应处理逻辑即可，完全不需要修改现有业务接口的代码。

代码改造示例 #

第一步：定义自定义业务异常 #

// 参数校验不通过异常
class ParameterInvalidException(message: String) : RuntimeException(message)
// 验证码校验失败异常
class CaptchaInvalidException(message: String) : RuntimeException(message)

第二步：改造Controller方法 #

@PostMapping("/customer")
fun handleRequest(@Valid @RequestBody customer: Customer, result: BindingResult): ResponseEntity<CustomerResponse> {
    if(result.hasErrors()) {
        val errorMsg = result.allErrors.joinToString(",") { it.defaultMessage ?: "参数不合法" }
        throw ParameterInvalidException(errorMsg)
    }

    val isValid = recapcthaService.validate(...)
    if(!isValid){
        throw CaptchaInvalidException("验证码校验失败")
    }

    // 正常业务逻辑省略
    val customerResponse = customerService.save(customer)
    return ResponseEntity.ok(customerResponse)
}

第三步：编写全局异常处理器 #

@RestControllerAdvice
class GlobalExceptionHandler {
    @ExceptionHandler(ParameterInvalidException::class)
    fun handleParamError(e: ParameterInvalidException): ResponseEntity<ErrorResponse> {
        val errorResp = ErrorResponse(
            code = 40001,
            message = e.message ?: "请求参数错误"
        )
        return ResponseEntity.status(400).body(errorResp)
    }

    @ExceptionHandler(CaptchaInvalidException::class)
    fun handleCaptchaError(e: CaptchaInvalidException): ResponseEntity<ErrorResponse> {
        val errorResp = ErrorResponse(
            code = 40002,
            message = e.message ?: "验证码错误"
        )
        return ResponseEntity.status(400).body(errorResp)
    }
}

注意事项 #

不要滥用自定义异常，只有真正的错误场景才适合用异常处理，正常的业务状态提示（比如“用户余额不足”这种业务分支返回）建议直接封装到通用响应体里，不要走异常流程。

内容的提问来源于stack exchange，提问作者lynxx