Spring5.1.x官方参考指南中文版

 主页   资讯   文章   代码   电子书 

3.5Spring字段格式化

如前一节所述,core.convert是一个通用类型转换系统。它提供了一个统一的ConversionServiceAPI以及一个强类型转换器SPI,用于实现从一种类型到另一种类型的转换逻辑。Spring容器使用此系统绑定bean属性值。此外,Spring表达式语言(SPEL)和DataBinder都使用此系统绑定字段值。例如,当SPEL需要将short强制为long以完成expression.setValue(object bean,object value)尝试时,core.convert系统将执行强制。

现在考虑典型客户机环境(如Web或桌面应用程序)的类型转换要求。在这种环境中,你通常从字符串转换为支持客户端回发过程,以及从字符串转换为支持视图呈现过程。此外,你通常需要本地化字符串值。更通用的core.convert转换器SPI不能直接满足这种格式要求。为了直接解决这些问题,Spring3引入了一个方便的格式化程序SPI,它为客户机环境提供了一个简单而健壮的PropertyEditor实现替代方案。

通常,当需要实现通用类型转换逻辑时,可以使用Converter SPI,例如,在java.util.Date和Long之间转换。当你在客户端环境(如Web应用程序)中工作并且需要分析和打印本地化字段值时,可以使用Formatter SPI。ConversionService为两个SPI提供统一的类型转换API。

3.5.1 Formatter SPI

用于实现字段格式化逻辑的Formatter SPI是简单且强类型的。以下列表显示Formatter接口定义:

package org.springframework.format;

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

Formatter继承了Printer和Parser接口,下面是这两个接口的定义:

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;
}

如果要创建你自己的Formatter, 需要实现上面提到的Formatter接口。参数T是需要被格式化的对象,例如java.util.Date。print()方法用来将T打印出来。

parse()用来将从客户端返回的格式化表示形式解析为T的实例。如果解析尝试失败,格式化程序应引发ParseException或IllegalArgumentException。注意确保格式化程序实现是线程安全的。

format子包提供了方便使用的Formatter几种实现,number包提供了NumberStyleFormatter, CurrencyStyleFormatter, 和 PercentStyleFormatter 使用java.text.NumberFormat来格式化Number对象。datetime包提供了DateFormatter使用java.text.DateFormat来格式化java.util.Dat对象。datetime.joda包基于joda时间库提供全面的datetime格式支持。

下面的DateFormatter是Formatter的一个实现:

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;
    }
}

Spring团队欢迎社区驱动的Formatter程序贡献。

3.5.2 注解驱动的Formatting

字段的格式化可以通过字段类型的配置或者通过注解来实现。要绑定一个注解到Formatter,可以实现AnnotationFormatterFactory接口。下面显示了AnnotationFormatterFactory接口的定义:

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);
}

要创建实现,请执行以下操作:参数化A为要与格式逻辑关联的字段的annotationType,例如org.springframework.format.annotation.DateTimeFormat。getFieldTypes()返回可在其上使用注解的字段类型。 getprinter()返回Printer以打印注解字段的值。getParser()返回一个Parser来解析注解字段的clientValue。

以下示例AnnotationFormatterFactory实现将@NumberFormat注解绑定到formatter程序,以指定数字样式或模式:

public final class NumberFormatAnnotationFormatterFactory
        implements AnnotationFormatterFactory<NumberFormat> {

    public Set<Class<?>> getFieldTypes() {
        return new HashSet<Class<?>>(asList(new Class<?>[] {
            Short.class, Integer.class, Long.class, Float.class,
            Double.class, BigDecimal.class, BigInteger.class }));
    }

    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 {
            Style style = annotation.style();
            if (style == Style.PERCENT) {
                return new PercentStyleFormatter();
            } else if (style == Style.CURRENCY) {
                return new CurrencyStyleFormatter();
            } else {
                return new NumberStyleFormatter();
            }
        }
    }
}

可以使用@NumberFormat来触发格式化,如下所示:

public class MyModel {

    @NumberFormat(style=Style.CURRENCY)
    private BigDecimal decimal;
}

Format注解API

org.springframework.format.annotation包中存在可移植format annotation API。你可以使用@NumberFormat来格式化Number字段,如Double和Long,使用@DateTimeFormat来格式化java.util.Date、java.util.Calendar, Long(毫秒时间戳)以及jsr-310 java.time和Joda-Time值类型。

以下示例使用@DateTimeFormat 将java.util.date格式化为ISO日期(yyyy-mm-dd):

public class MyModel {

    @DateTimeFormat(iso=ISO.DATE)
    private Date date;
}

3.5.3 FormatterRegistry SPI

FormatterRegistry是用于注册格式化程序和转换器的SPI。FormattingConversionService是一种适用于大多数环境的FormatTerregistry的实现。你可以通过编程或声明方式将此变量配置为SpringBean,例如,通过使用FormattingConversionServiceFactoryBean。因为这个实现也实现了ConversionService,所以可以直接配置它与Spring的DataBinder和Spring表达式语言(SPEL)一起使用。

下面的列表显示了FormatterRegistry SPI:

package org.springframework.format;

public interface FormatterRegistry extends ConverterRegistry {

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

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

    void addFormatterForFieldType(Formatter<?> formatter);

    void addFormatterForAnnotation(AnnotationFormatterFactory<?, ?> factory);
}

如上面所示,你可以按字段类型或注解注册formatters。

FormatterRegistry SPI允许你集中配置格式化规则,而不是在控制器之间复制这样的配置。例如,你可能希望强制所有日期字段以某种方式格式化,或者具有特定注解的字段以某种方式格式化。使用共享FormatterRegistry,你只需定义一次这些规则,这些规则在需要格式化时会自动使用。

3.5.4 FormatterRegistrar SPI

FormatterRegistrar是一个SPI,用于通过FormatterRegistry注册formatters和converters。下面的列表显示了它的接口定义:

package org.springframework.format;

public interface FormatterRegistrar {

    void registerFormatters(FormatterRegistry registry);
}

在为给定格式类别(如日期格式)注册多个相关转换器和格式化程序时,FormatterRegistrar非常有用。如果声明性registration不足-例如,当formatter 需要在与其自身不同的特定字段类型下索引,或者在注册Printer/Parser对时,它也很有用。下一节提供有关converter和formatter注册的更多信息。

3.5.5.在 Spring MVC 中配置Formatting

参考 Spring MVC 的Conversion and Formatting 章节。