关于spring:8-格式化器大一统-Spring的Formatter抽象

你好，我是 A 哥(YourBatman)。

上篇文章介绍了 java.text.Format 格式化体系，作为 JDK 1.0 就提供的格式化器，除了设计上存在肯定缺点，过于底层无奈标准化对使用者不够敌对，这都是对格式化器提出的更高要求。Spring 作为 Java 开发的规范基建，本文就来看看它做了哪些补充。

Spring Framework：5.3.x
Spring Boot：2.4.x

在利用中（特地是 web 利用），咱们常常须要将前端 /Client 端传入的字符串转换成 指定格局 / 指定数据类型 ，同样的服务端也心愿能把指定类型的数据依照 指定格局 返回给前端 /Client 端，这种状况下Converter 曾经无奈满足咱们的需要了。为此，Spring 提供了格式化模块专门用于解决此类问题。

首先能够从宏观上先看看 spring-context 对 format 模块的目录构造安顿：

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

能够看到，该接口自身没有任何办法，而是聚合了另外两个接口 Printer 和 Parser。

这两个接口是相同性能的接口。

Printer：格式化显示（输入）接口。将 T 类型转为 String 模式，Locale 用于管制国际化

@FunctionalInterface
public interface Printer<T> {
    // 将 Object 写为 String 类型
    String print(T object, Locale locale);
}

Parser：解析接口。将 String 类型转到 T 类型，Locale 用于管制国际化。

@FunctionalInterface
public interface Parser<T> {T parse(String text, Locale locale) throws ParseException;
}

格式化器接口，它的继承树如下：

由图可见，格式化动作只需关怀到两个畛域：

工夫日期畛域
数字畛域（其中包含货币）

Spring 框架从 4.0 开始反对 Java 8，针对 JSR 310 日期工夫类型的格式化专门有个包org.springframework.format.datetime.standard：

值得一提的是 ：在 Java 8 进去之前，Joda-Time 是 Java 日期工夫解决最好的解决方案，应用宽泛，甚至失去了 Spring 内置的反对。当初 Java 8 未然成为支流，JSR 310 日期工夫 API 齐全能够 代替 Joda-Time（JSR 310 的贡献者其实就是 Joda-Time 的作者们）。因而 joda 库也逐步辞别历史舞台，后续代码中不再举荐应用，本文也会选择性疏忽。

除了 Joda-Time 外，Java 中对工夫日期的格式化还需分为这两大阵营来解决：

尽管曾经 2020 年了（Java 8 于 2014 年公布），但谈到工夫日期那必然还是得有 java.util.Date，毕竟积重难返。所以呢，Spring 提供了DateFormatter 用于反对它的格式化。

因为 Date 早就存在，所以 DateFormatter 是随同着 Formatter 的呈现而呈现，@since 3.0

// @since 3.0
public class DateFormatter implements Formatter<Date> {private static final TimeZone UTC = TimeZone.getTimeZone("UTC");
    private static final Map<ISO, String> ISO_PATTERNS;
    static {Map<ISO, String> formats = new EnumMap<>(ISO.class);
        formats.put(ISO.DATE, "yyyy-MM-dd");
        formats.put(ISO.TIME, "HH:mm:ss.SSSXXX");
        formats.put(ISO.DATE_TIME, "yyyy-MM-dd'T'HH:mm:ss.SSSXXX");
        ISO_PATTERNS = Collections.unmodifiableMap(formats);
    }
}

默认应用的 TimeZone 是 UTC 标准时区，ISO_PATTERNS代表 ISO 规范模版，这和 @DateTimeFormat 注解的 iso 属性是 一一对应 的。也就是说如果你不想指定 pattern，能够疾速通过指定 ISO 来实现。

另外，对于格式化器来说有这些属性你都能够自在去定制：

DateFormatter：@Nullable
    private String pattern;
    private int style = DateFormat.DEFAULT;
    @Nullable
    private String stylePattern;
    @Nullable
    private ISO iso;
    @Nullable
    private TimeZone timeZone;

它对 Formatter 接口办法的实现如下：

DateFormatter：@Override
    public String print(Date date, Locale locale) {return getDateFormat(locale).format(date);
    }

    @Override
    public Date parse(String text, Locale locale) throws ParseException {return getDateFormat(locale).parse(text);
    }

    // 依据 pattern、ISO 等等失去一个 DateFormat 实例
    protected DateFormat getDateFormat(Locale locale) {...}

能够看到不论输出还是输入，底层依赖的都是 JDK 的java.text.DateFormat（理论为 SimpleDateFormat），当初晓得为毛上篇文章要先讲 JDK 的格式化体系做铺垫了吧，万变不离其宗。

因而能够认为，Spring 为此做的事件的外围，只不过是写了个依据 Locale、pattern、IOS 等参数生成 DateFormat 实例的逻辑而已，属于利用层面的封装。也就是须要通晓 getDateFormat() 办法的逻辑，此局部逻辑绘制成图如下：

因而：pattern、iso、stylePattern 它们的优先级谁先谁后，一看便知。

代码示例

@Test
public void test1() {DateFormatter formatter = new DateFormatter();
    
    Date currDate = new Date();

    System.out.println("默认输入格局：" + formatter.print(currDate, Locale.CHINA));
    formatter.setIso(DateTimeFormat.ISO.DATE_TIME);
    System.out.println("指定 ISO 输入格局：" + formatter.print(currDate, Locale.CHINA));
    formatter.setPattern("yyyy-mm-dd HH:mm:ss");
    System.out.println("指定 pattern 输入格局：" + formatter.print(currDate, Locale.CHINA));
}

运行程序，输入：

默认输入格局：2020-12-26
指定 ISO 输入格局：2020-12-26T13:06:52.921Z
指定 pattern 输入格局：2020-06-26 21:06:52

留神：ISO 格局输入的工夫，是存在时差问题的，因为它应用的是 UTC 工夫，请稍加留神。

还记得本系列后面介绍的 CustomDateEditor 这个属性编辑器吗？它也是用于对 String -> Date 的转化，底层依赖也是 JDK 的DateFormat，但应用灵便度上没这个自在，已被摈弃 / 取代。

对于 java.util.Date 类型的格式化，在此，苦口婆心的号召一句：如果你是新我的项目，请全我的项目禁用 Date 类型吧；如果你是新代码，也请不要再应用 Date 类型，太拖后腿了。

JSR 310 日期工夫类型是 Java8 引入的一套 全新的 工夫日期 API。新的工夫及日期 API 位于 java.time 中，此包中的是类是不可变且线程平安的。上面是一些要害类

Instant——代表的是工夫戳（另外可参考 Clock 类）
LocalDate——不蕴含具体工夫的日期，如 2020-12-12。它能够用来存储生日，周年纪念日，入职日期等
LocalTime——代表的是不含日期的工夫，如 18:00:00
LocalDateTime——蕴含了日期及工夫，不过没有偏移信息或者说时区
ZonedDateTime——蕴含时区的 残缺的 日期工夫还有时区，偏移量是以 UTC/ 格林威治工夫为基准的
Timezone——时区。在新 API 中时区应用 ZoneId 来示意。时区能够很不便的应用静态方法 of 来获取到

同时还有一些辅助类，如：Year、Month、YearMonth、MonthDay、Duration、Period 等等。

从上图 Formatter 的继承树来看，Spring 只提供了一些辅助类的格式化器实现，如 MonthFormatter、PeriodFormatter、YearMonthFormatter 等，且实现形式都是趋同的：

class MonthFormatter implements Formatter<Month> {

    @Override
    public Month parse(String text, Locale locale) throws ParseException {return Month.valueOf(text.toUpperCase());
    }
    @Override
    public String print(Month object, Locale locale) {return object.toString();
    }

}

这里以 MonthFormatter 为例，其它辅助类的格式化器实现其实根本一样：

那么问题来了：Spring 为毛没有给 LocalDateTime、LocalDate、LocalTime 这种更为罕用的类型提供 Formatter 格式化器呢？

其实是这样的：JDK 8 提供的这套日期工夫 API 是十分优良的，本人就提供了十分好用的 java.time.format.DateTimeFormatter 格式化器，并且设计、性能上都曾经十分欠缺了。既然如此，Spring 并不需要再反复造轮子，而是仅需思考如何整合此格式化器即可。

整合 DateTimeFormatter

为了实现“整合”，把 DateTimeFormatter 融入到 Spring 本人的 Formatter 体系内，Spring 筹备了多个 API 用于连接。

DateTimeFormatterFactory

java.time.format.DateTimeFormatter的工厂。和 DateFormatter 一样，它反对如下属性不便你间接定制：

DateTimeFormatterFactory：@Nullable
    private String pattern;
    @Nullable
    private ISO iso;
    @Nullable
    private FormatStyle dateStyle;
    @Nullable
    private FormatStyle timeStyle;
    @Nullable
    private TimeZone timeZone;


    // 依据定制的参数，生成一个 DateTimeFormatter 实例
    public DateTimeFormatter createDateTimeFormatter(DateTimeFormatter fallbackFormatter) {...}

优先级关系二者是统一的：

pattern
iso
dateStyle/timeStyle

阐明：统一的设计，能够给与开发者近乎统一的 编程体验，毕竟 JSR 310 和 Date 示意的都是工夫日期，尽量放弃一致性是一种很人性化的设计考量。

DateTimeFormatterFactoryBean

顾名思义，DateTimeFormatterFactory 用于生成一个 DateTimeFormatter 实例，而本类用于把生成的 Bean 放进 IoC 容器内，实现和 Spring 容器的整合。客气的是，它间接继承自 DateTimeFormatterFactory，从而本人同时就具备这两项能力：

生成 DateTimeFormatter 实例
将该实例放进 IoC 容器

多说一句：尽管这个工厂 Bean 非常简单，然而它开释的信号能够作为 编程领导：

一个利用内，对日期、工夫的格式化尽量只存在 1 种模版标准。比方咱们能够向 IoC 容器里扔进去一个模版，须要时注入进来应用即可
1. 留神：这里指的利用内，个别不蕴含协定转换层应用的模版标准。如 Http 协定层能够应用本人独自的一套转换模版机制
日期工夫模版不要在每次应用时去长期创立，而是集中统一创立好治理起来（比方放 IoC 容器内），这样保护起来不便很多

阐明：DateTimeFormatterFactoryBean这个 API 在 Spring 外部并未应用，这是 Spring 专门给使用者用的，因为 Spring 也心愿你这么去做从而把日期工夫格式化模版治理起来

代码示例

@Test
public void test1() {// DateTimeFormatterFactory dateTimeFormatterFactory = new DateTimeFormatterFactory();
    // dateTimeFormatterFactory.setPattern("yyyy-MM-dd HH:mm:ss");

    // 执行格式化动作
    System.out.println(new DateTimeFormatterFactory("yyyy-MM-dd HH:mm:ss").createDateTimeFormatter().format(LocalDateTime.now()));
    System.out.println(new DateTimeFormatterFactory("yyyy-MM-dd").createDateTimeFormatter().format(LocalDate.now()));
    System.out.println(new DateTimeFormatterFactory("HH:mm:ss").createDateTimeFormatter().format(LocalTime.now()));
    System.out.println(new DateTimeFormatterFactory("yyyy-MM-dd HH:mm:ss").createDateTimeFormatter().format(ZonedDateTime.now()));
}

运行程序，输入：

2020-12-26 22:44:44
2020-12-26
22:44:44
2020-12-26 22:44:44

阐明：尽管你也能够间接应用 DateTimeFormatter#ofPattern() 静态方法失去一个实例，然而若在 Spring 环境下应用它我还是倡议应用 Spring 提供的工厂类来创立，这样能保障对立的编程体验，B 格也略微高点。

应用倡议 ：当前对日期工夫类型（包含 JSR310 类型）就不要本人去写原生的SimpleDateFormat/DateTimeFormatter 了，倡议能够用 Spring 包装过的DateFormatter/DateTimeFormatterFactory，应用体验更佳。

通过了上篇文章的学习之后，对数字的格式化就一点也不生疏了，什么数字、百分数、钱币等都属于数字的领域。Spring 提供了 AbstractNumberFormatter 形象来专门解决数字格式化议题：

public abstract class AbstractNumberFormatter implements Formatter<Number> {
    ...
    @Override
    public String print(Number number, Locale locale) {return getNumberFormat(locale).format(number);
    }


    @Override
    public Number parse(String text, Locale locale) throws ParseException {
        // 伪代码，外围逻辑就这一句
        return getNumberFormat.parse(text, new ParsePosition(0));
    }

    // 失去一个 NumberFormat 实例
    protected abstract NumberFormat getNumberFormat(Locale locale);
    ...
}

这和 DateFormatter 的实现模式何其相似，几乎截然不同：底层实现依赖于（委托给）java.text.NumberFormat去实现。

此抽象类共有三个具体实现：

NumberStyleFormatter：数字格式化，如小数，分组等
PercentStyleFormatter：百分数格式化
CurrencyStyleFormatter：钱币格式化

NumberStyleFormatter应用 NumberFormat 的 数字款式 的通用数字格式化程序。可定制化参数为：pattern。外围源码如下：

NumberStyleFormatter：@Override
    public NumberFormat getNumberFormat(Locale locale) {NumberFormat format = NumberFormat.getInstance(locale);
        ...
        // 解析时，永远返回 BigDecimal 类型
        decimalFormat.setParseBigDecimal(true);
        // 应用格式化模版
        if (this.pattern != null) {decimalFormat.applyPattern(this.pattern);
        }
        return decimalFormat;
    }

代码示例：

@Test
public void test2() throws ParseException {NumberStyleFormatter formatter = new NumberStyleFormatter();

    double myNum = 1220.0455;
    System.out.println(formatter.print(myNum, Locale.getDefault()));

    formatter.setPattern("#.##");
    System.out.println(formatter.print(myNum, Locale.getDefault()));

    // 转换
    // Number parsedResult = formatter.parse("1,220.045", Locale.getDefault()); // java.text.ParseException: 1,220.045
    Number parsedResult = formatter.parse("1220.045", Locale.getDefault());
    System.out.println(parsedResult.getClass() + "-->" + parsedResult);
}

运行程序，输入：

1,220.045
1220.05

class java.math.BigDecimal-->1220.045

可通过 setPattern()指定数字格式化的模版（个别倡议显示指定）
parse()办法返回的是 BigDecimal 类型，从而保障了数字精度

PercentStyleFormatter示意应用百分比款式去格式化数字。外围源码（其实是全副源码）如下：

PercentStyleFormatter：@Override
    protected NumberFormat getNumberFormat(Locale locale) {NumberFormat format = NumberFormat.getPercentInstance(locale);
        if (format instanceof DecimalFormat) {((DecimalFormat) format).setParseBigDecimal(true);
        }
        return format;
    }

这个就更简略啦，pattern 模版都不须要指定。代码示例：

@Test
public void test3() throws ParseException {PercentStyleFormatter formatter = new PercentStyleFormatter();

    double myNum = 1220.0455;
    System.out.println(formatter.print(myNum, Locale.getDefault()));

    // 转换
    // Number parsedResult = formatter.parse("1,220.045", Locale.getDefault()); // java.text.ParseException: 1,220.045
    Number parsedResult = formatter.parse("122,005%", Locale.getDefault());
    System.out.println(parsedResult.getClass() + "-->" + parsedResult);
}

运行程序，输入：

122,005%
class java.math.BigDecimal-->1220.05

百分数的格式化不能指定 pattern，差评。

应用 钱币款式 格式化数字，应用 java.util.Currency 来形容货币。代码示例：

@Test
public void test3() throws ParseException {CurrencyStyleFormatter formatter = new CurrencyStyleFormatter();

    double myNum = 1220.0455;
    System.out.println(formatter.print(myNum, Locale.getDefault()));

    System.out.println("-------------- 定制化 --------------");
    // 指定货币品种（如果你晓得的话）// formatter.setCurrency(Currency.getInstance(Locale.getDefault()));
    // 指定所需的分数位数。默认是 2
    formatter.setFractionDigits(1);
    // 舍入模式。默认是 RoundingMode#UNNECESSARY
    formatter.setRoundingMode(RoundingMode.CEILING);
    // 格式化数字的模版
    formatter.setPattern("#.#¤¤");

    System.out.println(formatter.print(myNum, Locale.getDefault()));

    // 转换
    // Number parsedResult = formatter.parse("￥1220.05", Locale.getDefault());
    Number parsedResult = formatter.parse("1220.1CNY", Locale.getDefault());
    System.out.println(parsedResult.getClass() + "-->" + parsedResult);
}

运行程序，输入：

￥1,220.05
-------------- 定制化 --------------
1220.1CNY
class java.math.BigDecimal-->1220.1

值得关注的是：这三个实现在 Spring 4.2 版本之前是“耦合”在一起。直到 4.2 才拆开，职责拆散。

本文介绍了 Spring 的 Formatter 形象，让格式化器大一统。这就是 Spring 最强能力：API 设计、形象、大一统。

Converter 能够从任意源类型，转换为任意指标类型。而 Formatter 则是从 String 类型转换为工作指标类型，有点相似 PropertyEditor。能够感觉出 Converter 是 Formater 的超集，实际上在 Spring 中 Formatter 是被拆解成 PrinterConverter 和 ParserConverter，而后再注册到 ConverterRegistry，供后续应用。

对于格式化器的注册核心、注册员，这就是下篇文章内容喽，欢送放弃继续关注。

看完了不肯定懂，看懂了不肯定记住，记住了不肯定把握。来，文末 3 个思考题帮你复盘：

Spring 为何没有针对 JSR310 工夫类型提供专用转换器实现？
Spring 内建泛滥 Formatter 实现，如何治理？
格式化器 Formatter 和转换器 Converter 是如何整合到一起的？

本文所属专栏：Spring 类型转换，公号后盾回复专栏名即可获取全部内容。

分享、成长，回绝浅藏辄止。关注公众号【BAT 的乌托邦 】，回复关键字 专栏 有 Spring 技术栈、中间件等小而美的 原创专栏 供以收费学习。本文已被 https://www.yourbatman.cn 收录。

本文是 A 哥(YourBatman) 原创文章，未经作者容许不得转载，谢谢合作。

……
5. 穿过拥挤的人潮，Spring 已为你制作好高级赛道
6. 抹平差别，对立类型转换服务 ConversionService
7. JDK 拍了拍你：字符串拼接肯定记得用 MessageFormat#format
……

关于spring:8-格式化器大一统-Spring的Formatter抽象

本文提纲

版本约定

✍注释

Printer&Parser

Formatter

工夫日期格式化

Date 类型

代码示例

JSR 310 类型

整合 DateTimeFormatter

代码示例

数字格式化

数字格式化

百分数格式化

钱币格式化

✍总结

♨本文思考题♨

♚申明♚

☀举荐浏览☀

Just My Socks（注册教程内含优惠码）

关于spring:8-格式化器大一统-Spring的Formatter抽象

本文提纲

版本约定

✍注释

Printer&Parser

Formatter

工夫日期格式化

Date 类型

代码示例

JSR 310 类型

整合 DateTimeFormatter

代码示例

数字格式化

数字格式化

百分数格式化

钱币格式化

✍总结

♨本文思考题♨

♚申明♚

☀举荐浏览☀

Just My Socks（注册教程 内含优惠码）

Just My Socks（注册教程内含优惠码）