在 spring boot 中校验日期格式,最标准且推荐的做法是使用 jsr-380 (bean validation) 规范提供的 @datetimeformat 注解配合 localdate 或 localdatetime 类型。当请求参数无法解析为指定格式时,框架会自动抛出 methodargumenttypemismatchexception 异常,你可以通过全局异常处理器将其转换为标准的 json 错误响应。

如何配置全局异常处理以返回统一格式的错误信息
默认情况下,Spring Boot 遇到日期格式错误会返回 500 状态码和一段堆栈信息,这对前端不友好。我们需要实现一个 @ControllerAdvice 类来捕获 MethodArgumentTypeMismatchException,提取具体的字段名和错误原因,并封装成统一的 JSON 结构返回。

import org.springframework.http.ResponseEntity; import org.springframework.web.bind.annotation.ControllerAdvice; import org.springframework.web.bind.annotation.ExceptionHandler; import org.springframework.web.method.annotation.MethodArgumentTypeMismatchException; import java.util.HashMap; import java.util.Map; @ControllerAdvice public class GlobalExceptionHandler { @ExceptionHandler(MethodArgumentTypeMismatchException.class) public ResponseEntity<Map<String, Object>> handleTypeMismatch(MethodArgumentTypeMismatchException ex) { Map<String, Object> error = new HashMap<>(); error.put("field", ex.getName()); error.put("value", ex.getValue() != null ? ex.getValue().toString() : ""); error.put("message", "Invalid date format. Expected pattern: yyyy-MM-dd"); return ResponseEntity.badRequest().body(error); } }上述代码定义了一个全局拦截器。当 @RequestParam 或 @PathVariable 中的日期转换失败时,ex.getName() 能获取到参数名(如 startDate),ex.getValue() 获取用户传入的原始字符串。通过 ResponseEntity.badRequest() 返回 400 状态码,确保前端能正确区分业务错误和参数校验错误。
如何在 DTO 对象中使用注解进行复杂日期校验
除了简单的请求参数,更常见的场景是在接收 JSON 请求体时使用 DTO 对象。此时应使用 @JsonFormat 指定序列化/反序列化格式,并结合 @NotNull 或自定义逻辑进行非空校验。注意 @DateTimeFormat 主要用于 Web 层(URL 参数),而 @JsonFormat 用于 Jackson 数据绑定。

import com.fasterxml.jackson.annotation.JsonFormat; import javax.validation.constraints.NotNull; import java.time.LocalDate; public class EventDTO { @NotNull(message = "Start date is required") @JsonFormat(pattern = "yyyy-MM-dd") private LocalDate startDate; @NotNull(message = "End date is required") @JsonFormat(pattern = "yyyy-MM-dd") private LocalDate endDate; // getters and setters }在这个 DTO 示例中,@JsonFormat(pattern = "yyyy-MM-dd") 告诉 Jackson 将 JSON 中的字符串按此格式解析为 LocalDate。如果传入的 JSON 是 {"startDate": "2023-13-01"},Jackson 会在反序列化阶段直接抛出 InvalidFormatException。为了统一处理,我们通常还需要在 GlobalExceptionHandler 中添加对 InvalidFormatException 的捕获,逻辑与处理类型不匹配类似,但需针对 Jackson 的异常信息进行适配。
当日期范围存在逻辑依赖时如何校验
在实际业务中,结束日期必须晚于开始日期,这种跨字段的逻辑校验无法通过单个注解完成。我们需要编写一个自定义 Validator 或使用 Assert 在 Service 层进行前置检查。这里展示在 Controller 入口处进行简单断言的方式,以保持 Controller 的纯净性,同时避免进入 Service 层造成不必要的资源消耗。
import org.springframework.web.bind.annotation.PostMapping; import org.springframework.web.bind.annotation.RequestBody; import org.springframework.web.bind.annotation.RestController; @RestController public class EventController { @PostMapping("/events") public String createEvent(@RequestBody EventDTO dto) { if (dto.getEndDate().isBefore(dto.getStartDate())) { throw new IllegalArgumentException("End date must be after start date"); } return "Event created successfully"; } }这段代码展示了在方法体内直接比较两个日期字段。如果 endDate 早于 startDate,则抛出 IllegalArgumentException。虽然这不属于 Bean Validation 的标准流程,但在处理强业务约束时非常有效。结合之前的全局异常处理,这个异常也会被转化为友好的 JSON 错误响应,确保 API 行为的一致性。


















