Spring Boot中自定义Converter失效的原因与注册顺序解析 - 智猿学院-前后端，数据库，人工智能，云计算等领域前沿技术讲座

Spring Boot 中自定义 Converter 失效的原因与注册顺序解析

大家好，今天我们来聊聊 Spring Boot 中自定义 Converter 失效的问题，以及注册顺序对它的影响。Converter 在 Spring 中扮演着类型转换的关键角色，理解其工作机制和注册方式，对于避免开发中的各种“转换陷阱”至关重要。

Converter 的基本概念

Converter 是 Spring Framework 提供的一种类型转换机制，它允许你将一种类型的对象转换成另一种类型。这在 Web 开发中尤为重要，因为客户端提交的数据通常是字符串形式，而服务端需要将其转换成对应的 Java 对象进行处理。

Spring 提供了 Converter<S, T> 接口，其中 S 代表源类型，T 代表目标类型。你需要实现这个接口，并重写 convert(S source) 方法，在该方法中完成类型转换的逻辑。

例如，假设我们需要将字符串格式的日期 yyyy-MM-dd 转换为 java.time.LocalDate 对象，可以创建一个如下的 Converter：

import org.springframework.core.convert.converter.Converter;
import java.time.LocalDate;
import java.time.format.DateTimeFormatter;

public class StringToLocalDateConverter implements Converter<String, LocalDate> {

    private final DateTimeFormatter formatter = DateTimeFormatter.ofPattern("yyyy-MM-dd");

    @Override
    public LocalDate convert(String source) {
        if (source == null || source.isEmpty()) {
            return null;
        }
        return LocalDate.parse(source, formatter);
    }
}

Spring Boot 中注册 Converter 的几种方式

Spring Boot 提供了多种注册 Converter 的方式，常见的有以下几种：

实现 Converter 接口并使用 @Component 注解： 这是最简单直接的方式，Spring 会自动扫描并注册被 @Component 注解标记的 Converter。
```
@Component
public class StringToLocalDateConverter implements Converter<String, LocalDate> {
    // ... 省略代码 ...
}
```

实现 Converter 接口并在配置类中使用 ConversionServiceFactoryBean： 这种方式允许你更精细地控制 Converter 的注册，特别是在需要注册多个 Converter 时。

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.support.ConversionServiceFactoryBean;
import org.springframework.core.convert.converter.Converter;

import java.util.HashSet;
import java.util.Set;

@Configuration
public class WebConfig {

    @Bean
    public ConversionServiceFactoryBean conversionService() {
        ConversionServiceFactoryBean bean = new ConversionServiceFactoryBean();
        Set<Converter<?, ?>> converters = new HashSet<>();
        converters.add(new StringToLocalDateConverter());
        bean.setConverters(converters);
        return bean;
    }
}

实现 WebMvcConfigurer 接口并重写 addFormatters 方法： 这种方式适用于 Spring MVC 环境，允许你将 Converter 添加到 Spring MVC 的 FormattingConversionService。

import org.springframework.context.annotation.Configuration;
import org.springframework.format.FormatterRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

@Configuration
public class WebConfig implements WebMvcConfigurer {

    @Override
    public void addFormatters(FormatterRegistry registry) {
        registry.addConverter(new StringToLocalDateConverter());
    }
}

自定义 Converter 失效的常见原因

即使按照上述方式注册了 Converter，有时仍然会遇到 Converter 失效的情况。以下是一些常见原因：

类型不匹配： Converter 的源类型和目标类型必须与实际需要转换的类型匹配。例如，如果你的 Converter 定义为 Converter<String, LocalDate>，但你尝试将 String 转换为 LocalDateTime，那么这个 Converter 就不会被调用。
```
// 错误示例：尝试将 String 转换为 LocalDateTime，但没有对应的 Converter
@GetMapping("/test")
public String test(@RequestParam("date") LocalDateTime date) {
    return "Date: " + date;
}
```
Spring 未扫描到 Converter： 如果你使用了 @Component 注解注册 Converter，但 Spring 没有扫描到它，那么这个 Converter 就不会被注册。这可能是由于包扫描配置不正确，或者 Converter 类没有放在 Spring 可以扫描到的包中。

确保你的 Spring Boot 应用的启动类（通常带有 @SpringBootApplication 注解）位于包含 Converter 类的父包或同级包中。或者，你可以显式指定要扫描的包：
```
@SpringBootApplication(scanBasePackages = {"com.example", "com.example.converter"})
public class MyApplication {
    public static void main(String[] args) {
        SpringApplication.run(MyApplication.class, args);
    }
}
```
优先级问题： 当存在多个可以处理相同类型转换的 Converter 时，Spring 会根据优先级选择合适的 Converter。如果你的自定义 Converter 的优先级低于 Spring 默认的 Converter，那么 Spring 可能会选择默认的 Converter，导致你的自定义 Converter 失效。 Spring 默认Converter的优先级高于自定义的Converter。
注册顺序问题： 在使用 ConversionServiceFactoryBean 或 FormatterRegistry 注册 Converter 时，注册顺序可能会影响 Converter 的生效。如果你的自定义 Converter 依赖于其他 Converter，那么你需要确保它在依赖的 Converter 之后注册。
使用了错误的注解： 在 Spring MVC 环境中，确保使用了正确的注解来接收参数。例如，如果你希望将请求参数转换为 LocalDate，那么应该使用 @RequestParam 注解：
```
@GetMapping("/test")
public String test(@RequestParam("date") LocalDate date) {
    return "Date: " + date;
}
```
如果使用了 @PathVariable 注解，那么 Spring MVC 会将 URL 中的路径变量绑定到参数，而不是使用 Converter 进行类型转换。
类型转换服务未正确配置: 如果使用了ConversionService，但是这个服务没有被正确地注入到需要类型转换的地方，那么自定义的Converter就不会生效。例如，在自定义的validator中，需要手动注入ConversionService。
Bean的生命周期问题: 如果converter的bean的初始化晚于需要使用它的bean，可能会导致converter未生效。

注册顺序的影响

注册顺序对于 Converter 的生效至关重要，特别是在以下几种情况下：

存在多个可以处理相同类型转换的 Converter： 如果存在多个 Converter 可以将同一种源类型转换为同一种目标类型，那么 Spring 会按照注册顺序选择第一个匹配的 Converter。这意味着，如果你希望你的自定义 Converter 生效，你需要确保它在 Spring 默认的 Converter 之前注册。
Converter 之间存在依赖关系： 如果你的自定义 Converter 依赖于其他 Converter，那么你需要确保它在依赖的 Converter 之后注册。例如，假设你需要将字符串格式的日期和时间 yyyy-MM-dd HH:mm:ss 转换为 java.time.LocalDateTime 对象，并且你已经有一个 StringToLocalDateConverter，那么你可以创建一个新的 Converter，它先使用 StringToLocalDateConverter 将日期部分转换为 LocalDate 对象，然后再将时间部分转换为 LocalTime 对象，最后将它们合并成 LocalDateTime 对象。在这种情况下，你需要确保 StringToLocalDateConverter 在新的 Converter 之前注册。

让我们看一个更具体的例子。假设我们需要将字符串转换为一个自定义的枚举类型 OrderStatus：

public enum OrderStatus {
    PENDING,
    PROCESSING,
    SHIPPED,
    DELIVERED,
    CANCELLED
}

我们可以创建一个 Converter 将字符串转换为 OrderStatus：

import org.springframework.core.convert.converter.Converter;

public class StringToOrderStatusConverter implements Converter<String, OrderStatus> {

    @Override
    public OrderStatus convert(String source) {
        if (source == null || source.isEmpty()) {
            return null;
        }
        try {
            return OrderStatus.valueOf(source.toUpperCase());
        } catch (IllegalArgumentException e) {
            return null; // 或者抛出自定义异常
        }
    }
}

现在，假设我们还想创建一个更复杂的 Converter，它可以根据不同的前缀将字符串转换为不同的 OrderStatus。例如，如果字符串以 "P" 开头，则转换为 PENDING；如果以 "S" 开头，则转换为 SHIPPED。

import org.springframework.core.convert.converter.Converter;

public class AdvancedStringToOrderStatusConverter implements Converter<String, OrderStatus> {

    @Override
    public OrderStatus convert(String source) {
        if (source == null || source.isEmpty()) {
            return null;
        }
        if (source.startsWith("P_")) {
            return OrderStatus.PENDING;
        } else if (source.startsWith("S_")) {
            return OrderStatus.SHIPPED;
        } else {
            // 使用默认的 StringToOrderStatusConverter
            return new StringToOrderStatusConverter().convert(source);
        }
    }
}

在这种情况下，AdvancedStringToOrderStatusConverter 依赖于 StringToOrderStatusConverter 来处理不带前缀的字符串。因此，我们需要确保 StringToOrderStatusConverter 在 AdvancedStringToOrderStatusConverter 之前注册。

如果我们使用 WebMvcConfigurer 来注册这两个 Converter，那么注册顺序如下：

import org.springframework.context.annotation.Configuration;
import org.springframework.format.FormatterRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

@Configuration
public class WebConfig implements WebMvcConfigurer {

    @Override
    public void addFormatters(FormatterRegistry registry) {
        registry.addConverter(new StringToOrderStatusConverter());
        registry.addConverter(new AdvancedStringToOrderStatusConverter());
    }
}

在这个例子中，StringToOrderStatusConverter 会先注册，然后 AdvancedStringToOrderStatusConverter 会后注册。当 Spring 尝试将字符串转换为 OrderStatus 时，它会首先尝试使用 StringToOrderStatusConverter，然后再尝试使用 AdvancedStringToOrderStatusConverter。这意味着，即使字符串以 "P" 或 "S" 开头，StringToOrderStatusConverter 也会先尝试转换，如果转换失败（因为它无法处理带前缀的字符串），那么才会尝试使用 AdvancedStringToOrderStatusConverter。

为了让 AdvancedStringToOrderStatusConverter 优先处理带前缀的字符串，我们需要调整注册顺序：

import org.springframework.context.annotation.Configuration;
import org.springframework.format.FormatterRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

@Configuration
public class WebConfig implements WebMvcConfigurer {

    @Override
    public void addFormatters(FormatterRegistry registry) {
        registry.addConverter(new AdvancedStringToOrderStatusConverter());
        registry.addConverter(new StringToOrderStatusConverter());
    }
}

现在，AdvancedStringToOrderStatusConverter 会先注册，因此它会优先处理带前缀的字符串。如果字符串不带前缀，那么它会调用 StringToOrderStatusConverter 来处理。

总结来说，注册顺序非常重要，它决定了 Spring 在尝试类型转换时会按照什么顺序尝试不同的 Converter。确保你的自定义 Converter 在依赖的 Converter 之后注册，并且在 Spring 默认的 Converter 之前注册，可以避免 Converter 失效的问题。

如何调试 Converter 问题

当遇到 Converter 失效的问题时，可以使用以下方法进行调试：

设置断点： 在 Converter 的 convert 方法中设置断点，查看是否被调用，以及传入的参数是否正确。
打印日志： 在 Converter 的 convert 方法中打印日志，记录转换过程中的信息，例如传入的参数、转换结果等。
查看 Spring 的日志： 启用 Spring 的 DEBUG 级别日志，查看 Spring 在注册 Converter 时的信息，例如是否扫描到了 Converter，以及注册顺序。
使用 Spring Boot Actuator： Spring Boot Actuator 提供了 /autoconfig 端点，可以查看 Spring Boot 的自动配置报告，包括 Converter 的注册情况。

不同注册方式对注册顺序的影响

不同的注册方式对 Converter 的注册顺序有不同的影响：

注册方式	注册顺序	备注
`@Component` 注解	Spring 会根据扫描到的顺序注册 Converter，但这个顺序是不确定的。	无法精确控制注册顺序，适用于简单的场景。
`ConversionServiceFactoryBean`	按照添加到 `Set` 中的顺序注册 Converter。	可以精确控制注册顺序，适用于需要精细控制 Converter 注册的场景。
`WebMvcConfigurer.addFormatters`	按照添加到 `FormatterRegistry` 中的顺序注册 Converter。	可以精确控制注册顺序，适用于 Spring MVC 环境。
`application.properties`或`application.yml`配置	无法直接注册Converter，但是可以通过配置参数，影响 Spring 默认的Converter的行为。	不能直接增加自定义的Converter，但是可以修改已有的Converter的行为。

总而言之，如果需要精确控制 Converter 的注册顺序，建议使用 ConversionServiceFactoryBean 或 WebMvcConfigurer.addFormatters。

一些建议

优先使用 @Component 注解： 对于简单的 Converter，使用 @Component 注解是最方便的方式。
使用 WebMvcConfigurer 或 ConversionServiceFactoryBean 控制注册顺序： 当需要精确控制 Converter 的注册顺序时，使用 WebMvcConfigurer 或 ConversionServiceFactoryBean。
编写单元测试： 为你的 Converter 编写单元测试，确保它可以正确地将一种类型的对象转换为另一种类型。
仔细阅读 Spring 的文档： Spring 的文档包含了关于 Converter 的详细信息，可以帮助你更好地理解其工作机制。
开启debug模式，仔细观察启动日志 详细的启动日志，可以帮助你发现很多问题。

关键点的回顾

Converter 用于类型转换，简化数据处理。
多种注册方式，选择合适的很重要。
注册顺序影响 Converter 的生效，需要仔细安排。