专栏首页BAT的乌托邦8. 格式化器大一统 -- Spring的Formatter抽象
原创

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&Parser

这两个接口是相反功能的接口。

  • Printer:格式化显示(输出)接口。将T类型转为String形式,Locale用于控制国际化@FunctionalInterface public interface Printer<T> { // 将Object写为String类型 String print(T object, Locale locale); }@FunctionalInterface public interface Parser<T> { T parse(String text, Locale locale) throws ParseException; }
  • Parser:解析接口。将String类型转到T类型,Locale用于控制国际化。

Formatter

格式化器接口,它的继承树如下:

由图可见,格式化动作只需关心到两个领域:

  • 时间日期领域
  • 数字领域(其中包括货币)

时间日期格式化

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中对时间日期的格式化还需分为这两大阵营来处理:

Date类型

虽然已经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类型

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,从而自己同时就具备这两项能力:

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

多说一句:虽然这个工厂Bean非常简单,但是它释放的信号可以作为编程指导

  1. 一个应用内,对日期、时间的格式化尽量只存在1种模版规范。比如我们可以向IoC容器里扔进去一个模版,需要时注入进来使用即可
    1. 注意:这里指的应用,一般不包含协议转换层使用的模版规范。如Http协议层可以使用自己单独的一套转换模版机制
  2. 日期时间模版不要在每次使用时去临时创建,而是集中统一创建好管理起来(比如放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
  1. 可通过setPattern()指定数字格式化的模版(一般建议显示指定)
  2. 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个思考题帮你复盘:

  1. Spring为何没有针对JSR310时间类型提供专用转换器实现?
  2. Spring内建众多Formatter实现,如何管理?
  3. 格式化器Formatter和转换器Converter是如何整合到一起的?

♚声明♚

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

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

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

原创声明,本文系作者授权云+社区发表,未经许可,不得转载。

如有侵权,请联系 yunjia_community@tencent.com 删除。

我来说两句

0 条评论
登录 后参与评论

相关文章

  • SpringBoot学习四:日志框架、SpringBoot自动化配置

    SpringBoot的日志模块选择 SpringBoot底层选择的日志抽象层是@Slf4j,日志的实现是Logback。 日志的使用

    关忆北.
  • Spring官网阅读(十五)Spring中的格式化(Formatter)

    从上面可以看出,这个两个接口维护了两个功能相反的方法,分别完成对String类型数据的解析以及格式化。

    程序员DMZ
  • 9. 细节见真章,Formatter注册中心的设计很讨巧

    Spring设计了org.springframework.format.Formatter格式化器接口抽象,对格式化器进行了大一统,让你只需要关心统一的API,...

    YourBatman
  • 彻底解决Spring mvc中时间类型的转换和序列化问题

    在使用Spring mvc 进行开发时我们经常遇到前端传来的某种格式的时间字符串无法用java8时间包下的具体类型参数来直接接收。同时还有一系列的序列化 、反序...

    码农小胖哥
  • 玩转spring mvc入参自定义类型转换和格式化

    最近小胖哥搞了个小程序,有几个spring mvc 接口传递了时间,时间用java 8 time 相关的api 来直接接收:

    码农小胖哥
  • SpringMVC数据类型转换器与国际化配置

    我们都知道在浏览器中,访问网页都是通过url访问的。所以在web开发中,我们经常会通过url来传递数据。如果我要在url参数上传递一个日期数据,我们是无法在后端...

    端碗吹水
  • 【小家Spring】聊聊Spring中的格式化:Formatter、AnnotationFormatterFactory、DateFormatter以及@DateTimeFormat...

    Converter只完成了数据类型的转换,却不负责输入输出数据的格式化工作,日期时间、货币等虽都以字符串形式存在,却有不同的格式。

    YourBatman
  • SpringBoot源码学习系列之SpringMVC自动配置

    web的自动配置在SpringBoot项目中是一个很重要的方面,实现代码在spring-boot-autoconfigure工程里:

    SmileNicky
  • springboot系列学习(十五):springboot项目里面,springMVC的自动配置的原理是什么?springMVC是如何使用的

    在进行项目编写前,我们还需要知道一个东西,就是SpringBoot对我们的SpringMVC还做了哪些配置,包括如何扩展,如何定制。

    一天不写程序难受
  • Spring Boot:定制type Formatters

    考虑到PropertyEditor的无状态和非线程安全特性,Spring 3增加了一个Formatter接口来替代它。Formatters提供和Property...

    阿杜
  • 深入分析Spring Formatter

      在Web项目中,通常需要将数据转换为具有某种格式的字符串进行展示,因此Spring3引入了格式化转换器(Formatter SPI) 和格式化服务API(F...

    良辰美景TT
  • Spring MVC-07循序渐进之验证器 上 (Spring自带的验证框架)

    Converter和Formatter作用域Field级。 在MVC应用程序中,它们将String转换或者格式化成另外一种Java类型,比如java.util....

    小小工匠
  • SpringCloud升级之路2020.0.x版-29.Spring Cloud OpenFeign 的解析(1)

    在使用云原生的很多微服务中,比较小规模的可能直接依靠云服务中的负载均衡器进行内部域名与服务映射,通过健康检查接口判断实例健康状态,然后直接使用 OpenFeig...

    干货满满张哈希
  • 关于SpringMVC自动配置

    https://docs.spring.io/spring-boot/docs/1.5.10.RELEASE/reference/htmlsingle/#boo...

    开源君
  • Spring MVC-06循序渐进之Converter和Formatter

    Spring MVC-05循序渐进之数据绑定和form标签库(上) 和 Spring MVC-05循序渐进之数据绑定和form标签库(下) 实战从0到1 我们已...

    小小工匠
  • 伙计,来跟我一起学SpringBoot! 【第一弹】

    YAML(YAML Ain't Markup Language) 标记语言,以数据为中心,比 json 、xml 等更适合做配置文件

    蔡不菜丶
  • 透过 Rust 探索系统的本原:泛型

    在 Fundamentals of Generic Programming[1] 里,Alexander Stepanov(泛型概念的创立者)用一段优雅的文字描...

    tyrchen
  • Python学习-logging

    Python的logging模块提供了通用的日志系统,可以方便第三方模块或者是应用使用。这个模块提供不同的日志级别,并可以采用不同的方式记录日志。

    py3study
  • 经典案例之某新闻网站的实现

    技术实现:python3.x+Flask+第三方sdk(云通讯+七牛云)+部署(阿里云)

    小闫同学啊

扫码关注云+社区

领取腾讯云代金券