数据绑定原理

// Converter：通用型，任意类型互转，无上下文
public interface Converter<S, T> {
    T convert(S source);
}

// Formatter：专门用于 String ↔ 目标类型，支持 Locale 上下文
public interface Formatter<T> extends Printer<T>, Parser<T> {
    String print(T object, Locale locale);    // 对象 → 字符串
    T parse(String text, Locale locale);      // 字符串 → 对象
}

// 1. 定义值对象
public class ProductCode {
    private final String prefix;    // FX
    private final int year;         // 2024
    private final String category;    // ABC
    private final int sequence;       // 00123
    
    // 构造方法、getter、校验逻辑...
}

// 2. 实现 Converter
@Component
public class StringToProductCodeConverter implements Converter<String, ProductCode> {
    
    private static final Pattern PATTERN = Pattern.compile("([A-Z]+)-(\d{4})-([A-Z]+)-(\d+)");
    
    @Override
    public ProductCode convert(String source) {
        Matcher matcher = PATTERN.matcher(source);
        if (!matcher.matches()) {
            throw new IllegalArgumentException(
                "Invalid product code format. Expected: XX-YYYY-CATEGORY-SEQ, got: " + source);
        }
        return new ProductCode(
            matcher.group(1),
            Integer.parseInt(matcher.group(2)),
            matcher.group(3),
            Integer.parseInt(matcher.group(4))
        );
    }
}

// 3. 注册到 Spring MVC（Spring Boot 方式）
@Configuration
public class WebConfig implements WebMvcConfigurer {
    
    @Autowired
    private StringToProductCodeConverter productCodeConverter;
    
    @Override
    public void addFormatters(FormatterRegistry registry) {
        registry.addConverter(productCodeConverter);
    }
}

// 4. Controller 中直接使用
@RestController
public class InventoryController {
    
    @GetMapping("/products/{code}")
    public ProductDetail getProduct(@PathVariable ProductCode code) {
        // code 已经是解析好的 ProductCode 对象
        return productService.findByCode(code);
    }
}

@RestController
@RequestMapping("/api/v1/orders")
public class OrderController {

    @GetMapping
    public Page<OrderSummary> listOrders(
            @RequestParam @DateTimeFormat(iso = DateTimeFormat.ISO.DATE) LocalDate date,
            @RequestParam OrderStatus status,
            @RequestParam(defaultValue = "0") @Min(0) int page,
            @RequestParam(defaultValue = "20") @Min(1) @Max(100) int size,
            @RequestParam(required = false) SortField sortBy) {
        
        return orderService.findByDateAndStatus(date, status, PageRequest.of(page, size, sortBy));
    }

    @PostMapping
    public Order createOrder(@Valid @RequestBody OrderCreateRequest request) {
        return orderService.create(request);
    }
}

@Configuration
public class WebConfig implements WebMvcConfigurer {
    
    @Override
    public void addFormatters(FormatterRegistry registry) {
        // 自定义日期格式（覆盖默认 ISO 格式）
        DateTimeFormatterRegistrar registrar = new DateTimeFormatterRegistrar();
        registrar.setDateFormatter(DateTimeFormatter.ofPattern("yyyy/MM/dd"));
        registrar.setDateTimeFormatter(DateTimeFormatter.ofPattern("yyyy/MM/dd HH:mm:ss"));
        registrar.registerFormatters(registry);
    }
}

public class OrderCreateRequest {
    
    @NotBlank(message = "客户名称不能为空")
    @Size(max = 100, message = "客户名称长度不能超过100")
    private String customerName;
    
    @NotNull(message = "订单金额不能为空")
    @DecimalMin(value = "0.01", message = "订单金额必须大于0")
    private BigDecimal amount;
    
    @NotNull(message = "期望交付日期不能为空")
    @Future(message = "期望交付日期必须是未来日期")
    private LocalDate expectedDeliveryDate;
    
    @Pattern(regexp = "FX-[0-9]{4}-[A-Z]{3}-[0-9]{5}", message = "商品编码格式错误")
    private String productCode;
    
    // getter / setter
}

// ❌ 错误：不传 page 时会尝试将 null 绑定到 int，报错
@GetMapping("/orders")
public List<Order> list(@RequestParam(required = false) int page) { ... }

// ✅ 正确：使用包装类型，不传时为 null
@GetMapping("/orders")
public List<Order> list(@RequestParam(required = false) Integer page) { ... }

// ✅ 更正确：给基本类型配默认值
@GetMapping("/orders")
public List<Order> list(@RequestParam(defaultValue = "0") int page) { ... }

// 方案一：注解声明（单个参数）
@RequestParam @DateTimeFormat(pattern = "yyyy/MM/dd") LocalDate date

// 方案二：全局配置（推荐）
@Configuration
public class WebConfig implements WebMvcConfigurer {
    @Override
    public void addFormatters(FormatterRegistry registry) {
        DateTimeFormatterRegistrar registrar = new DateTimeFormatterRegistrar();
        registrar.setDateFormatter(DateTimeFormatter.ofPattern("yyyy/MM/dd"));
        registrar.registerFormatters(registry);
    }
}