Spring Field 格式设置

如上一节所述，core.convert 是一个 通用型转换系统。它提供了一个统一的 API，如 以及一个强类型 SPI，用于实现一种类型的转换逻辑 到另一个。Spring 容器使用此系统来绑定 bean 属性值。在 此外，Spring 表达式语言 （SpEL） 和使用此系统都可以 bind 字段值。例如，当 SPEL 需要强制 a 到 a 到 完成 an attempt，系统执行强制转换。ConversionServiceConverterDataBinderShortLongexpression.setValue(Object bean, Object value)core.convertspring-doc.cn

现在考虑典型客户端环境的类型转换要求，例如 Web 或桌面应用程序。在此类环境中，您通常会从 转换为 以支持客户端回发过程，以及转换回以支持 View 渲染过程。此外，您通常需要本地化值。越多 通用 SPI 不满足此类格式要求 径直。为了直接解决它们，Spring 提供了一个方便的 SPI 为 Client 提供简单而健壮的 implementations 替代方案 环境。StringStringStringcore.convertConverterFormatterPropertyEditorspring-doc.cn

一般来说，当你需要实现通用类型时，你可以使用 SPI 转换逻辑 — 例如，用于在 a 和 a 之间进行转换。 当您在客户端环境（例如 Web application），并且需要解析和打印本地化的字段值。它为两个 SPI 提供了一个统一的类型转换 API。Converterjava.util.DateLongFormatterConversionServicespring-doc.cn

The SPIFormatter

用于实现字段格式化逻辑的 SPI 很简单，并且是强类型的。这 以下清单显示了接口定义：FormatterFormatterspring-doc.cn

package org.springframework.format;

public interface Formatter<T> extends Printer<T>, Parser<T> {
}

Formatter从 和 Building Block 接口扩展。这 下面的清单显示了这两个接口的定义：PrinterParserspring-doc.cn

public interface Printer<T> {

	String print(T fieldValue, Locale locale);
}
import java.text.ParseException;

public interface Parser<T> {

	T parse(String clientValue, Locale locale) throws ParseException;
}

要创建自己的 ，请实现前面显示的接口。 参数化为要格式化的对象类型，例如 .实现打印 for 实例的操作 display in client locale 中。实现该操作以从客户端区域设置返回的格式化表示形式解析 的实例。如果解析尝试失败，您应该抛出 a 或 an。拿 注意确保您的实现是线程安全的。FormatterFormatterTjava.util.Dateprint()Tparse()TFormatterParseExceptionIllegalArgumentExceptionFormatterspring-doc.cn

为方便起见，子包提供了多种实现。 该软件包提供 、 和 格式使用 . 该软件包提供了一个用于格式化对象的 a 以及 a 来格式化对象 以枚举中定义的不同样式（参见 格式注释 API）。formatFormatternumberNumberStyleFormatterCurrencyStyleFormatterPercentStyleFormatterNumberjava.text.NumberFormatdatetimeDateFormatterjava.util.Datejava.text.DateFormatDurationFormatterDuration@DurationFormat.Stylespring-doc.cn

下面是一个示例实现：DateFormatterFormatterspring-doc.cn

package org.springframework.format.datetime;

public final class DateFormatter implements Formatter<Date> {

	private String pattern;

	public DateFormatter(String pattern) {
		this.pattern = pattern;
	}

	public String print(Date date, Locale locale) {
		if (date == null) {
			return "";
		}
		return getDateFormat(locale).format(date);
	}

	public Date parse(String formatted, Locale locale) throws ParseException {
		if (formatted.length() == 0) {
			return null;
		}
		return getDateFormat(locale).parse(formatted);
	}

	protected DateFormat getDateFormat(Locale locale) {
		DateFormat dateFormat = new SimpleDateFormat(this.pattern, locale);
		dateFormat.setLenient(false);
		return dateFormat;
	}
}
class DateFormatter(private val pattern: String) : Formatter<Date> {

	override fun print(date: Date, locale: Locale)
			= getDateFormat(locale).format(date)

	@Throws(ParseException::class)
	override fun parse(formatted: String, locale: Locale)
			= getDateFormat(locale).parse(formatted)

	protected fun getDateFormat(locale: Locale): DateFormat {
		val dateFormat = SimpleDateFormat(this.pattern, locale)
		dateFormat.isLenient = false
		return dateFormat
	}
}

Spring 团队欢迎社区驱动的贡献。请参阅 GitHub Issues to contribute。Formatterspring-doc.cn

注释驱动的格式设置

字段格式可以按字段类型或注释进行配置。绑定 对 ， implement 的注释。以下内容 清单显示了接口的定义：FormatterAnnotationFormatterFactoryAnnotationFormatterFactoryspring-doc.cn

package org.springframework.format;

public interface AnnotationFormatterFactory<A extends Annotation> {

	Set<Class<?>> getFieldTypes();

	Printer<?> getPrinter(A annotation, Class<?> fieldType);

	Parser<?> getParser(A annotation, Class<?> fieldType);
}

要创建实施：spring-doc.cn

  1. 参数化 （Parameterize） 作为您希望与之关联的字段 格式设置逻辑 — 例如 .AannotationTypeorg.springframework.format.annotation.DateTimeFormatspring-doc.cn

  2. Have 返回可以使用注释的字段类型。getFieldTypes()spring-doc.cn

  3. Have return a 打印带注释的字段的值。getPrinter()Printerspring-doc.cn

  4. Have return a 解析带注释字段的 a。getParser()ParserclientValuespring-doc.cn

以下示例实现将 annotation 绑定到格式化程序，以允许指定数字样式或模式：AnnotationFormatterFactory@NumberFormatspring-doc.cn

public final class NumberFormatAnnotationFormatterFactory
		implements AnnotationFormatterFactory<NumberFormat> {

	private static final Set<Class<?>> FIELD_TYPES = Set.of(Short.class,
			Integer.class, Long.class, Float.class, Double.class,
			BigDecimal.class, BigInteger.class);

	public Set<Class<?>> getFieldTypes() {
		return FIELD_TYPES;
	}

	public Printer<Number> getPrinter(NumberFormat annotation, Class<?> fieldType) {
		return configureFormatterFrom(annotation, fieldType);
	}

	public Parser<Number> getParser(NumberFormat annotation, Class<?> fieldType) {
		return configureFormatterFrom(annotation, fieldType);
	}

	private Formatter<Number> configureFormatterFrom(NumberFormat annotation, Class<?> fieldType) {
		if (!annotation.pattern().isEmpty()) {
			return new NumberStyleFormatter(annotation.pattern());
		}
		// else
		return switch(annotation.style()) {
			case Style.PERCENT -> new PercentStyleFormatter();
			case Style.CURRENCY -> new CurrencyStyleFormatter();
			default -> new NumberStyleFormatter();
		};
	}
}
class NumberFormatAnnotationFormatterFactory : AnnotationFormatterFactory<NumberFormat> {

	override fun getFieldTypes(): Set<Class<*>> {
		return setOf(Short::class.java, Int::class.java, Long::class.java, Float::class.java, Double::class.java, BigDecimal::class.java, BigInteger::class.java)
	}

	override fun getPrinter(annotation: NumberFormat, fieldType: Class<*>): Printer<Number> {
		return configureFormatterFrom(annotation, fieldType)
	}

	override fun getParser(annotation: NumberFormat, fieldType: Class<*>): Parser<Number> {
		return configureFormatterFrom(annotation, fieldType)
	}

	private fun configureFormatterFrom(annotation: NumberFormat, fieldType: Class<*>): Formatter<Number> {
		return if (annotation.pattern.isNotEmpty()) {
			NumberStyleFormatter(annotation.pattern)
		} else {
			val style = annotation.style
			when {
				style === NumberFormat.Style.PERCENT -> PercentStyleFormatter()
				style === NumberFormat.Style.CURRENCY -> CurrencyStyleFormatter()
				else -> NumberStyleFormatter()
			}
		}
	}
}

要触发格式设置，您可以使用 . 对字段进行注释，如下所示 示例显示：@NumberFormatspring-doc.cn

public class MyModel {

	@NumberFormat(style=Style.CURRENCY)
	private BigDecimal decimal;
}
class MyModel(
	@field:NumberFormat(style = Style.CURRENCY) private val decimal: BigDecimal
)

格式注释 API

包中存在可移植格式注释 API。您可以用于设置字段的格式，例如 和 ，以 ISO-8601 和简化样式设置字段的格式。 以及设置字段的格式，例如 、 、 和 （对于毫秒时间戳） 以及 JSR-310 类型。org.springframework.format.annotation@NumberFormatNumberDoubleLong@DurationFormatDuration@DateTimeFormatjava.util.Datejava.util.CalendarLongjava.timespring-doc.cn

以下示例用于将 a 格式化为 ISO 日期 （yyyy-MM-dd）：@DateTimeFormatjava.util.Datespring-doc.cn

public class MyModel {

	@DateTimeFormat(iso=ISO.DATE)
	private Date date;
}
class MyModel(
	@DateTimeFormat(iso=ISO.DATE) private val date: Date
)

有关更多详细信息，请参阅适用于 @DateTimeFormat、@DurationFormat 和 @NumberFormat 的 javadoc。spring-doc.cn

基于样式的格式设置和解析依赖于区域设置敏感模式，这些模式可能会发生变化 取决于 Java 运行时。具体而言，依赖于日期、时间或 数字解析和格式化在运行时可能会遇到不兼容的行为更改 在 JDK 20 或更高版本上。spring-doc.cn

使用您控制的 ISO 标准化格式或具体模式允许 可靠的独立于系统和区域设置的日期、时间、 和数字值。spring-doc.cn

对于 ，使用回退模式也有助于解决 兼容性问题。@DateTimeFormatspring-doc.cn

有关更多详细信息，请参阅 Spring Framework Wiki 中的使用 JDK 20 及更高版本进行日期和时间格式化页面。spring-doc.cn

The SPIFormatterRegistry

这是一个用于注册格式化程序和转换器的 SPI。 是 适用于 大多数环境。您可以以编程方式或声明方式配置此变体 作为 Spring Bean 进行，例如，通过使用 .因为这个 implementation 也实现了，可以直接配置 用于 Spring 和 Spring 表达式语言 （SpEL）。FormatterRegistryFormattingConversionServiceFormatterRegistryFormattingConversionServiceFactoryBeanConversionServiceDataBinderspring-doc.cn

下面的清单显示了 SPI：FormatterRegistryspring-doc.cn

package org.springframework.format;

public interface FormatterRegistry extends ConverterRegistry {

	void addPrinter(Printer<?> printer);

	void addParser(Parser<?> parser);

	void addFormatter(Formatter<?> formatter);

	void addFormatterForFieldType(Class<?> fieldType, Formatter<?> formatter);

	void addFormatterForFieldType(Class<?> fieldType, Printer<?> printer, Parser<?> parser);

	void addFormatterForFieldAnnotation(AnnotationFormatterFactory<? extends Annotation> annotationFormatterFactory);
}

如前面的清单所示，您可以按字段类型或注释注册格式化程序。spring-doc.cn

SPI 允许您集中配置格式规则，而不是 在您的控制器之间复制此类配置。例如，您可能希望 强制所有日期字段都以某种方式格式化，或者强制字段具有特定的 annotation 以某种方式格式化。使用共享的 ，您可以定义 这些规则一次，每当需要格式化时都会应用它们。FormatterRegistryFormatterRegistryspring-doc.cn

The SPIFormatterRegistrar

FormatterRegistrar是一个 SPI，用于通过 FormatterRegistry 的下面的清单显示了它的接口定义：spring-doc.cn

package org.springframework.format;

public interface FormatterRegistrar {

	void registerFormatters(FormatterRegistry registry);
}

A 在注册多个相关转换器时很有用，并且 给定格式类别的格式化程序，例如日期格式。它也可以是 在声明式注册不足时很有用 — 例如，当格式化程序 需要在不同于其自身的特定字段类型下编制索引，或者 注册 / 对。下一节提供了有关 转换器和格式化程序注册。FormatterRegistrar<T>PrinterParserspring-doc.cn

在 Spring MVC 中配置格式

参见 Spring MVC 一章中的转换和格式化。spring-doc.cn