Преамбула

В статье я хотел бы рассмотреть написание собственных конвертеров типов и форматтеров полей Spring Framework (в том числе с использованием аннотаций).

Статья написана by junior for junior, поэтому прошу отнестись к изложенному ниже с изрядной долей снисхождения :)

Конвертер - конвертирует один тип данных в другой
Форматтер - конвертирует только тип String в какой-то другой тип (и обратно в String)

Неплохое объяснение со stackoverflow

Рассматривать работу конвертеров и форматтеров будем на совершенно банальном примере - в @RequestParam контроллера приходит строка с датой или временем и надо ее сконвертировать в LocalDate или LocalTime. На месте строки с датой/временем может быть все, что угодно, например, описание сущности базы данных. Но думаю это усложнило бы пример, поэтому для простоты пускай остаются дата и время.

@RestController  
@RequestMapping(value = "/api/v1/some", produces = MediaType.APPLICATION_JSON_VALUE)  
public class SomeRestController {  

	// autowired services and others
	// ...
	
    @Override  
    @GetMapping("/filter")  
    public List<SomeDto> getFiltered(  
            @RequestParam(required = false) @DateTimeFormat(iso = DateTimeFormat.ISO.DATE) LocalDate startDate,  
            @RequestParam(required = false) @DateTimeFormat(iso = DateTimeFormat.ISO.TIME) LocalTime startTime,  
            @RequestParam(required = false) @DateTimeFormat(iso = DateTimeFormat.ISO.DATE) LocalDate endDate,  
            @RequestParam(required = false) @DateTimeFormat(iso = DateTimeFormat.ISO.TIME) LocalTime endTime) {  
  
        // ...
    }  
}

В приведенной выше реализации все конвертируется с помощью аннотаций форматирования Spring Framework. Для тренировки откажемся от использования стандартных аннотаций и напишем свои собственные конвертеры, потом форматтеры и аннотации.

Конфигурирование буду указывать только в xml, как самое мутное.

Конвертер

Документация

В самом простом случае для создания собственного конвертера надо создать класс, имплементирующий интерфейс Converter<S, T>. S - тип источника данных, T - тип данных, который должен быть получен в результате конвертации.

В нашем случае источником выступает тип String, а результирующими типами будут LocalDate и LocalTime. Таким образом, классов конвертеров у нас будет два. Вариант реализации:

import org.springframework.core.convert.converter.Converter;  
  
import java.time.LocalDate;  
import java.time.format.DateTimeFormatter;  
  
public class StringToLocalDateConverter implements Converter<String, LocalDate> {  
  
    private String datePattern = "yyyy-MM-dd";  
  
    public String getDatePattern() {  
        return datePattern;  
    }  
  
    public void setDatePattern(String datePattern) {  
        this.datePattern = datePattern;  
    }  
  
    @Override  
    public LocalDate convert(String dateString) {  
        return LocalDate.parse(dateString, DateTimeFormatter.ofPattern(datePattern));  
    }  
}

import org.springframework.core.convert.converter.Converter;  
  
import java.time.LocalTime;  
import java.time.format.DateTimeFormatter;  
  
public class StringToLocalTimeConverter implements Converter<String, LocalTime> {  
  
    private String timePattern = "HH:mm";  
  
    public String getTimePattern() {  
        return timePattern;  
    }  
  
    public void setTimePattern(String timePattern) {  
        this.timePattern = timePattern;  
    }  
  
    @Override  
    public LocalTime convert(String timeString) {  
        return LocalTime.parse(timeString, DateTimeFormatter.ofPattern(timePattern));  
    }  
}

Теперь надо рассказать Спрингу про наши конвертеры. Для этого надо создать бины конвертеров, зарегистрировать экземпляр класса ConversionService с именем conversionService и добавить в него наши конвертеры.

Документация

<bean id="stringToLocalTimeConverter" class="ru.jsft.util.converter.StringToLocalTimeConverter"/>  
<bean id="stringToLocalDateConverter" class="ru.jsft.util.converter.StringToLocalDateConverter"/>

<bean id="conversionService" class="org.springframework.context.support.ConversionServiceFactoryBean">  
    <property name="converters">
        <set>
            <ref bean="stringToLocalDateConverter"/>
            <ref bean="stringToLocalTimeConverter"/>  
        </set>
    </property>
</bean>

Остался последний штрих - сказать Spring MVC, что надо использовать наш ConversionService

Документация

в xml-конфигурации mvc:annotation-driven необходимо дополнить указанием conversionService

<mvc:annotation-driven conversion-service="conversionService"/>

Теперь можно переписать метод контроллера

@RestController  
@RequestMapping(value = "/api/v1/some", produces = MediaType.APPLICATION_JSON_VALUE)  
public class SomeRestController {  

	// autowired services and others
	// ...
	
    @Override  
    @GetMapping("/filter")  
    public List<SomeDto> getFiltered(  
            @RequestParam(required = false) LocalDate startDate,  
            @RequestParam(required = false) LocalTime startTime,  
            @RequestParam(required = false) LocalDate endDate,  
            @RequestParam(required = false) LocalTime endTime) {  
  
        // ...
    }  
}

Конспект

1. Создали классы конвертеров, имплементирующие Converter<S, T>

2. Создали бины классов (через xml, аннотацию или конфигурационный класс)

3. Создали через конфигурацию бин conversionService и указали в нем наши конвертеры

4. Указали Spring MVC, что надо пользоваться нашим conversionService

Форматтер

Теперь проделаем то же самое, только через форматирование строк.

Документация

Необходимо создать класс, имплементирующий интерфейс Formatter< T > где T - тип данных, которые будут получены в результате форматирования входящей строки. Напомню - форматтер работает только со String, поэтому входящий тип данных не нужен.

Вариант реализации

import org.springframework.format.Formatter;  
  
import java.time.LocalDate;  
import java.time.format.DateTimeFormatter;  
import java.util.Locale;  
  
public class CustomDateFormatter implements Formatter<LocalDate> {  
    @Override  
    public LocalDate parse(String text, Locale locale) {  
        return LocalDate.parse(text, DateTimeFormatter.ofPattern("yyyy-MM-dd"));  
    }  
  
    @Override  
    public String print(LocalDate localDate, Locale locale) {  
        return localDate.toString();  
    }  
}

import org.springframework.format.Formatter;  
  
import java.time.LocalTime;  
import java.time.format.DateTimeFormatter;  
import java.util.Locale;  
  
public class CustomTimeFormatter implements Formatter<LocalTime> {  
    @Override  
    public LocalTime parse(String text, Locale locale) {  
        return LocalTime.parse(text, DateTimeFormatter.ofPattern("HH:mm"));  
    }  
  
    @Override  
    public String print(LocalTime localTime, Locale locale) {  
        return localTime.toString();  
    }  
}

parse() - метод возвращает конвертированное из String значение

print() - в этом методе осуществляется обратная конвертация, значение в String. Здесь просто отконвертируем в строку штатными средствами.

Расскажем Спрингу про форматтеры. Укажем Spring MVC использовать наш conversionService.

Документация

Обратите внимание - для бина conversionService используется класс, отличный от использованного для конвертеров. При использовании этого класса, кстати, можно кроме форматтеров добавить и конвертеры. См. документацию.

<bean id="customDateFormatter" class="ru.jsft.util.formatter.CustomDateFormatter"/>  
<bean id="customTimeFormatter" class="ru.jsft.util.formatter.CustomTimeFormatter"/>

<bean id="conversionService" class="org.springframework.format.support.FormattingConversionServiceFactoryBean">  
	<property name="formatters">  
		<set>
			<ref bean="customDateFormatter"/>  
			<ref bean="customTimeFormatter"/>  
		</set>        
	</property>    
</bean>  

<mvc:annotation-driven conversion-service="conversionService"/>

Метод контроллера будет выглядеть так же, как и в случае с использованием конвертеров

@RestController  
@RequestMapping(value = "/api/v1/some", produces = MediaType.APPLICATION_JSON_VALUE)  
public class SomeRestController {  

	// autowired services and others
	// ...
	
    @Override  
    @GetMapping("/filter")  
    public List<SomeDto> getFiltered(  
            @RequestParam(required = false) LocalDate startDate,  
            @RequestParam(required = false) LocalTime startTime,  
            @RequestParam(required = false) LocalDate endDate,  
            @RequestParam(required = false) LocalTime endTime) {  
  
        // ...
    }  
}

Конспект

1. Создали классы форматтеров, имплементирующие Formatter< T >

2. Создали бины классов (через xml, аннотацию или конфигурационный класс)

3. Создали через конфигурацию бин conversionService и указали в нем наши форматтеры

4. Указали Spring MVC, что надо пользоваться нашей conversionService

Форматирование с использованием аннотаций

Теперь давайте сделаем так, чтобы форматирование происходило только там, где мы укажем соответствующие аннотации. В случае с предыдущими вариантами реализации применение конвертеров/контроллеров происходит по всему коду.

Я хочу, чтобы аннотация с помощью параметра могла применяться как для конвертации в LocalDate, так и в LocalTime. То есть не делать две разные аннотации, а сделать одну, но с уточняющим параметром (как это реализовано в случае @DateTimeFormat(iso = DateTimeFormat.ISO.DATE))

Документация

Первым делом создадим интерфейс для новой аннотации. В интерфейсе объявим параметр, в котором будет храниться указание, во что надо конвертировать - в LocalDate или в LocalTime. В качестве типа параметра укажем объявленный тут же enum. Значение по умолчанию для параметра я специально не делал.

import java.lang.annotation.ElementType;  
import java.lang.annotation.Retention;  
import java.lang.annotation.RetentionPolicy;  
import java.lang.annotation.Target;  
  
@Target({ElementType.METHOD, ElementType.FIELD, ElementType.PARAMETER})  
@Retention(RetentionPolicy.RUNTIME)  
public @interface CustomDateTimeFormat {  
  
    Type type();  
  
    public enum Type {  
        DATE,  
        TIME  
    }  
}

Теперь надо привязать аннотацию к форматтеру. Это делается с помощью реализации класса, имплементирующего интерфейс AnnotationFormatterFactory< A extends Annotation >

import org.springframework.format.AnnotationFormatterFactory;  
import org.springframework.format.Formatter;  
import org.springframework.format.Parser;  
import org.springframework.format.Printer;  
  
import java.time.LocalDate;  
import java.time.LocalTime;  
import java.util.HashSet;  
import java.util.List;  
import java.util.Set;  
  
public class CustomDateTimeFormatAnnotationFormatterFactory implements AnnotationFormatterFactory<CustomDateTimeFormat> {  
  
    @Override  
    public Set<Class<?>> getFieldTypes() {  
        return new HashSet<>(List.of(LocalDate.class, LocalTime.class));  
    }  
  
    @Override  
    public Printer<?> getPrinter(CustomDateTimeFormat annotation, Class<?> fieldType) {  
        return getFormatter(annotation, fieldType);  
    }  
  
    @Override  
    public Parser<?> getParser(CustomDateTimeFormat annotation, Class<?> fieldType) {  
        return getFormatter(annotation, fieldType);  
    }  
  
    private Formatter<?> getFormatter(CustomDateTimeFormat annotation, Class<?> fieldType) {  
        switch (annotation.type()) {  
            case DATE -> {  
                return new CustomDateFormatter();  
            }  
            case TIME -> {  
                return new CustomTimeFormatter();  
            }  
        }  
        return null;  
    }  
}

Тут давайте разберемся поподробнее с переопределенными методами интерфейса AnnotationFormatterFactory.

getFieldTypes() - метод возвращает список классов-типов данных, с которыми будет использоваться аннотация. Обратите внимание, если вы аннотируете тип, которого не будет в этом списке, то, несмотря на наличие аннотации, ничего не произойдет.

getPrinter() и getParser() - первый возвращает Printer для вывода значения аннотированного поля, второй возвращает Parser для разбора полученного значения. В обоих случаях у нас код будет одинаковый. Идея в том, что если у аннотации стоит параметр type == DATE, то вернется уже написанный нами ранее экземпляр класса CustomDateFormatter. А для type == TIME вернется экземпляр CustomTimeFormatter соответственно. Таким образом мы добиваемся того, что аннотация одна, а возвращаемый результат - разный.

Ну вот, теперь осталось познакомить Спринг с нашей привязкой аннотации. Не забудем указать Spring MVC наш conversionService.

Документация

<bean id="customDateTimeFormatAnnotationFormatterFactory" class="ru.jsft.util.formatter.CustomDateTimeFormatAnnotationFormatterFactory"/>

<bean id="conversionService" class="org.springframework.format.support.FormattingConversionServiceFactoryBean">  
	<property name="formatters">  
		<set>
			<ref bean="customDateTimeFormatAnnotationFormatterFactory"/>  
		</set>        
	</property>   
</bean>

<mvc:annotation-driven conversion-service="conversionService"/>

Теперь изменим метод контроллера, чтобы входящие параметры форматировались с использованием аннотаций

@RestController  
@RequestMapping(value = "/api/v1/some", produces = MediaType.APPLICATION_JSON_VALUE)  
public class SomeRestController {  

	// autowired services and others
	// ...
	
    @Override  
    @GetMapping("/filter")  
    public List<SomeDto> getFiltered(  
            @RequestParam(required = false) @CustomDateTimeFormat(type = CustomDateTimeFormat.Type.DATE) LocalDate startDate,  
            @RequestParam(required = false) @CustomDateTimeFormat(type = CustomDateTimeFormat.Type.TIME) LocalTime startTime,  
            @RequestParam(required = false) @CustomDateTimeFormat(type = CustomDateTimeFormat.Type.DATE) LocalDate endDate,  
            @RequestParam(required = false) @CustomDateTimeFormat(type = CustomDateTimeFormat.Type.TIME) LocalTime endTime) {  
  
        // ...
    }  
}

Конспект

1. Классы форматтеров у нас уже были

2. Создали интерфейс-аннотацию

3. Создали класс-привязку аннотации к форматтеру

4. Создали через конфигурацию бин conversionService и указали в нем класс, привязывающий аннотации к форматтерам

5. Указали Spring MVC, что надо пользоваться нашей conversionService

Заключение

Искренне надеюсь, что эта статья окажется полезной тем, кто только начинает разбираться с темой конвертирования типов и форматирования полей с помощью Spring Framework. Я понимаю, что за бортом осталась неразобранной значительная часть информации по этим темам. Но у меня не было цели перевести документацию к Спрингу или создать некое всеобъемлющее руководство. Эта статья - лишь способ помочь сдвинуться с мертвой точки.

Спасибо, что дочитали до конца.