API错误400的深度解析与实战解决方案：参数校验与异常处理最佳实践

1次阅读

共计 3044 个字符，预计需要花费 8 分钟才能阅读完成。

每个后端开发者都见过这个经典错误：HTTP 400 Bad Request。当 API 参数校验失败时，服务器常返回模糊的提示如 ” 参数有误 ”，这种不友好的响应会导致：

前端开发反复猜测参数格式
联调时间增加 30% 以上（根据笔者团队统计）
生产环境难以快速定位问题根源

通过本文，你将掌握一套完整的参数校验解决方案。我们先看一个典型的反面案例：

{"error":"Invalid parameters"}

这种响应就像对前端说 ” 你错了，但我不告诉你怎么错的 ”。

首先在 DTO 上使用 JSR-380 注解：

public class UserDTO {@NotBlank(message = "用户名不能为空")
    @Size(min = 4, max = 20, message = "用户名长度 4 -20 位")
    private String username;

    @Email(message = "邮箱格式不正确")
    private String email;

    @Pattern(regexp = "^(?=.*[A-Za-z])(?=.*\\d)[A-Za-z\\d]{8,}$", 
             message = "密码需包含字母和数字，至少 8 位")
    private String password;
}

不同场景需要不同校验规则时：

public interface CreateGroup {}
public interface UpdateGroup {}

public class ProductDTO {@Null(groups = CreateGroup.class, message = "创建时 ID 必须为空")
    @NotNull(groups = UpdateGroup.class, message = "更新时 ID 不能为空")
    private Long id;
}

@PostMapping
public void create(@Validated(CreateGroup.class) ProductDTO dto) {...}

实现特定业务规则校验：

@Target({FIELD})
@Retention(RUNTIME)
@Constraint(validatedBy = PhoneValidator.class)
public @interface ValidPhone {String message() default "手机号格式错误";
    Class<?>[] groups() default {};
    Class<? extends Payload>[] payload() default {};}

public class PhoneValidator implements 
    ConstraintValidator<ValidPhone, String> {
    @Override
    public boolean isValid(String phone, ConstraintValidatorContext context) {return phone != null && phone.matches("^1[3-9]\\d{9}$");
    }
}

@RestControllerAdvice
public class GlobalExceptionHandler {@ExceptionHandler(MethodArgumentNotValidException.class)
    public ResponseEntity<ErrorResponse> handleValidationExceptions(MethodArgumentNotValidException ex) {List<String> errors = ex.getBindingResult()
            .getFieldErrors()
            .stream()
            .map(error -> error.getField() + ":" + error.getDefaultMessage())
            .collect(Collectors.toList());

        return ResponseEntity.badRequest()
            .body(new ErrorResponse("VALIDATION_FAILED", errors));
    }

    @ExceptionHandler(BusinessException.class)
    public ResponseEntity<ErrorResponse> handleBusinessException(BusinessException ex) {return ResponseEntity.status(ex.getHttpStatus())
            .body(new ErrorResponse(ex.getErrorCode(), ex.getMessage()));
    }
}

public class ErrorResponse {
    private String code;  // 如："INVALID_PARAM"
    private String type;  // 如："validation_error"
    private String message;
    private List<String> details; // 用于参数校验的详细错误
    private Instant timestamp = Instant.now();

    // 构造方法省略
}

处理复杂 DTO 时注意：

public class OrderDTO {
    @Valid  // 关键注解触发嵌套校验
    private List<@Valid OrderItem> items; 
}

public class OrderItem {@Min(1)
    private Integer quantity;

    @NotNull
    private Long productId;
}

在 resources 下创建：

ValidationMessages.properties
ValidationMessages_zh_CN.properties

然后在注解中使用占位符：

@Size(min = 6, message = "{password.size}")
private String password;

建议采用分级编码：

01xxx: 用户相关错误
02xxx: 订单相关错误
03xxx: 支付相关错误

例如：

01001 - 用户名已存在
01002 - 密码强度不足

@Bean
public OpenAPI customOpenAPI() {return new OpenAPI()
        .components(new Components()
            .addSchemas("ErrorResponse", new Schema<ErrorResponse>()
                .type("object")
                .properties("code", new Schema().type("string").example("VALIDATION_FAILED"),
                    "message", new Schema().type("string").example("参数校验失败")
                )));
}

通过本文方案，我们实现了：