如何让@RequestParam支持枚举@JsonProperty值的参数绑定

根因分析 #

@JsonProperty是Jackson提供的JSON序列化/反序列化注解，仅作用于请求体/响应体的JSON解析流程。而@RequestParam接收的是URL查询参数，走Spring MVC自带的参数绑定逻辑，默认只会匹配枚举的name()返回值（即大写的枚举常量名），不会读取@JsonProperty的配置值。

解决方案 #

提供两种适配方案，可根据业务场景选择：

方案1：全局通用配置（推荐） #

一次配置后所有带@JsonProperty注解的枚举都自动支持查询参数绑定，无需逐个修改枚举定义。

1. 实现自定义枚举转换器工厂

import com.fasterxml.jackson.annotation.JsonProperty;
import org.springframework.core.convert.converter.Converter;
import org.springframework.core.convert.converter.ConverterFactory;
import org.springframework.stereotype.Component;

import java.util.Arrays;

@Component
public class JsonPropertyEnumConverterFactory implements ConverterFactory<String, Enum<?>> {
    @Override
    public <T extends Enum<?>> Converter<String, T> getConverter(Class<T> targetType) {
        return source -> Arrays.stream(targetType.getEnumConstants())
                // 优先匹配@JsonProperty的value值
                .filter(enumConstant -> {
                    try {
                        JsonProperty annotation = targetType.getField(enumConstant.name()).getAnnotation(JsonProperty.class);
                        return annotation != null && annotation.value().equals(source);
                    } catch (NoSuchFieldException e) {
                        return false;
                    }
                })
                .findFirst()
                // 匹配不到则回退到枚举名匹配（支持大小写兼容，不需要可删除该段逻辑）
                .or(() -> Arrays.stream(targetType.getEnumConstants())
                        .filter(enumConstant -> enumConstant.name().equalsIgnoreCase(source))
                        .findFirst())
                .orElseThrow(() -> new IllegalArgumentException("无匹配枚举值：" + source));
    }
}

2. 注册转换器到Spring MVC

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

@Configuration
public class WebMvcConfig implements WebMvcConfigurer {
    @Resource
    private JsonPropertyEnumConverterFactory jsonPropertyEnumConverterFactory;

    @Override
    public void addFormatters(FormatterRegistry registry) {
        registry.addConverterFactory(jsonPropertyEnumConverterFactory);
    }
}

方案2：单个枚举适配（无需全局改动） #

如果仅需要适配少数枚举，可以直接用Spring提供的@EnumValue注解标记枚举常量，专门用于@RequestParam的枚举绑定：

import com.fasterxml.jackson.annotation.JsonProperty;
import org.springframework.format.annotation.EnumValue;

public enum Display {
    @JsonProperty("hidden")
    @EnumValue("hidden")
    HIDDEN,

    @JsonProperty("visible")
    @EnumValue("visible")
    VISIBLE,

    @JsonProperty("soon")
    @EnumValue("soon")
    SOON
}

该方案无需额外配置，添加注解后即可直接传入visible绑定到Display.VISIBLE。

内容的提问来源于stack exchange，提问作者pera.coyote