How Custom Spring Converters Eliminate Date and Enum Parameter Pain Points

When integrating front‑end parameters, developers repeatedly encounter two problems: a multitude of date formats that fail to parse and enum parameters passed as numeric or string codes that cannot be automatically mapped. Projects often end up writing repetitive null‑checks, format parsers, and enum‑matching logic, while overusing @DateTimeFormat and @JsonFormat leads to inconsistent global behavior and frequent runtime errors.

Spring uses two completely independent conversion systems. Spring MVC ConversionService handles URL, form, and non‑JSON request parameters, filling bean properties during data binding. Jackson processes @RequestBody JSON parameters and serializes response bodies. The default converters only support basic types (String, Integer, Long, Boolean) and cannot handle business‑specific date or enum formats, which is the root cause of most conversion bugs.

Spring defines three conversion interfaces: Converter<S,T>: a simple one‑to‑one converter, ideal for fixed conversions such as String → Date or String → Long. ConverterFactory: creates converters for a family of target types, commonly used to produce converters for all enum classes. GenericConverter: supports multi‑type, collection and nested generic conversions; it is powerful but complex and intended for framework internals.

The effective priority chain is:

@InitBinder (local) > @DateTimeFormat (local) > Global custom Converter > Spring default converters

Therefore, to achieve a globally uniform format, local annotations must be avoided except for special cases.

1. Global date converter

import org.springframework.core.convert.converter.Converter;
import java.text.ParseException;
import java.text.SimpleDateFormat;
import java.util.Arrays;
import java.util.Date;
import java.util.List;
/**
 * Global date converter supporting multiple patterns and 13‑digit timestamps.
 */
public class StringToDateConverter implements Converter<String, Date> {
    private static final List<String> DATE_PATTERN_LIST = Arrays.asList(
        "yyyy-MM-dd",
        "yyyy-MM-dd HH:mm:ss",
        "yyyy/MM/dd",
        "yyyy/MM/dd HH:mm:ss"
    );
    @Override
    public Date convert(String source) {
        if (source == null || source.trim().isEmpty()) {
            return null;
        }
        String value = source.trim();
        // 13‑digit timestamp
        if (value.matches("\\d{13}")) {
            return new Date(Long.parseLong(value));
        }
        for (String pattern : DATE_PATTERN_LIST) {
            try {
                SimpleDateFormat sdf = new SimpleDateFormat(pattern);
                sdf.setLenient(false);
                return sdf.parse(value);
            } catch (ParseException ignored) {}
        }
        throw new IllegalArgumentException("Invalid date format! Supported: standard dates, date‑time, 13‑digit timestamp");
    }
}

Register it globally:

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 ConvertGlobalConfig {
    @Bean
    public ConversionServiceFactoryBean conversionService() {
        ConversionServiceFactoryBean factoryBean = new ConversionServiceFactoryBean();
        Set<Converter<?, ?>> converters = new HashSet<>();
        converters.add(new StringToDateConverter());
        factoryBean.setConverters(converters);
        // Register enum factory (see below)
        // factoryBean.setConverterFactories(...);
        return factoryBean;
    }
}

Result: all GET/POST parameters, form fields, URL path variables, @Value injections and request bodies are automatically converted without any annotation, strict illegal‑date validation is enforced, and common formats as well as timestamps are fully supported.

2. Global enum conversion

Spring’s native conversion only matches the enum literal name. To support numeric codes, string codes and enum names, define a marker annotation and a factory:

import java.lang.annotation.*;
@Target(ElementType.FIELD)
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface EnumValue {}

import org.springframework.core.convert.converter.Converter;
import org.springframework.core.convert.converter.ConverterFactory;
import java.lang.reflect.Field;
/**
 * Factory that creates a converter capable of matching enum name, numeric code or string code.
 */
public class StringToEnumConverterFactory implements ConverterFactory<String, Enum<?>> {
    @Override
    public <T extends Enum<T>> Converter<String, T> getConverter(Class<T> targetType) {
        return new StringToEnumConverter<>(targetType);
    }
    private static class StringToEnumConverter<T extends Enum<T>> implements Converter<String, T> {
        private final Class<T> enumClass;
        private Field codeField;
        public StringToEnumConverter(Class<T> enumClass) {
            this.enumClass = enumClass;
            for (Field field : enumClass.getDeclaredFields()) {
                if (field.isAnnotationPresent(EnumValue.class)) {
                    this.codeField = field;
                    this.codeField.setAccessible(true);
                    break;
                }
            }
        }
        @Override
        public T convert(String source) {
            if (source == null || source.trim().isEmpty()) {
                return null;
            }
            source = source.trim();
            // 1. match enum name
            try { return Enum.valueOf(enumClass, source); } catch (IllegalArgumentException ignored) {}
            // 2. match @EnumValue field
            for (T constant : enumClass.getEnumConstants()) {
                try {
                    Object fieldValue = codeField.get(constant);
                    if (source.equals(String.valueOf(fieldValue))) {
                        return constant;
                    }
                } catch (Exception e) { continue; }
            }
            throw new IllegalArgumentException("Invalid enum parameter: " + source);
        }
    }
}

Example enum:

public enum OrderStatusEnum {
    WAIT_PAY(1, "待支付"),
    PAY_SUCCESS(2, "支付成功"),
    PAY_FAIL(3, "支付失败"),
    CANCEL(4, "订单取消");
    @EnumValue
    private final Integer code;
    private final String desc;
    OrderStatusEnum(Integer code, String desc) { this.code = code; this.desc = desc; }
    @JsonValue
    public Integer getCode() { return code; }
    public String getDesc() { return desc; }
}

Controller usage (no extra annotation needed):

@RestController
@RequestMapping("/order")
public class OrderController {
    @GetMapping("/list")
    public Result getOrderList(OrderStatusEnum status) {
        // Front‑end can pass 1, "1" or "WAIT_PAY" – all are converted automatically
        return Result.success(orderService.list(status));
    }
}

3. JSON side – Jackson configuration

import com.fasterxml.jackson.databind.DeserializationFeature;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.module.SimpleModule;
import com.fasterxml.jackson.databind.ser.std.ToStringSerializer;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Primary;
import java.text.SimpleDateFormat;
@Configuration
public class JacksonGlobalConfig {
    @Bean
    @Primary
    public ObjectMapper objectMapper() {
        ObjectMapper mapper = new ObjectMapper();
        mapper.setDateFormat(new SimpleDateFormat("yyyy-MM-dd HH:mm:ss"));
        mapper.configure(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES, false);
        mapper.configure(DeserializationFeature.ACCEPT_EMPTY_STRING_AS_NULL_OBJECT, true);
        SimpleModule module = new SimpleModule();
        module.addSerializer(Long.class, ToStringSerializer.instance);
        module.addSerializer(Long.TYPE, ToStringSerializer.instance);
        mapper.registerModule(module);
        return mapper;
    }
}

Adding @JsonValue on the enum getter makes the API return the numeric code instead of the enum name, keeping front‑end and back‑end perfectly aligned.

4. Global conversion‑exception handling

import org.springframework.http.HttpStatus;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.RestControllerAdvice;
@RestControllerAdvice
public class GlobalConvertExceptionHandler {
    @ExceptionHandler(IllegalArgumentException.class)
    public Result handleConvertException(IllegalArgumentException e) {
        return Result.fail(HttpStatus.BAD_REQUEST.value(), e.getMessage());
    }
}

5. Per‑controller special rules with @InitBinder

import org.springframework.web.bind.annotation.InitBinder;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.bind.WebDataBinder;
import org.springframework.beans.propertyeditors.CustomDateEditor;
import java.text.SimpleDateFormat;
import java.util.Date;
@RestController
@RequestMapping("/special")
public class SpecialController {
    @InitBinder
    public void customDateBinder(WebDataBinder binder) {
        SimpleDateFormat sdf = new SimpleDateFormat("yyyy-MM-dd");
        sdf.setLenient(false);
        binder.registerCustomEditor(Date.class, new CustomDateEditor(sdf, true));
    }
}

6. Comparison of solutions @DateTimeFormat local annotation – easy but limited to a single format, high maintenance, cannot handle timestamps.

Manual utility conversion – straightforward but leads to duplicated code and hard‑to‑maintain edge cases.

Global custom Converter / ConverterFactory – provides project‑wide uniformity, zero annotations, supports multiple formats, strict validation, and is suitable for 99% of production scenarios.

By following the steps above, developers can eliminate date‑format parsing errors and enum‑mapping failures, achieve consistent request/response handling, and reduce boilerplate code throughout the Spring application.