一款智能的日期解析工具

前言

Java中日期、时间相关的类相当的多,并且分不同的版本提供了不同的实现,包括DateCalendarLocalDateTimeZonedDateTimeOffsetDateTime等等。针对这些时间类型又通过SimpleDateFormatDateTimeFormatter实现不同的日期与字符串之间的格式化和解析。

为了应对各种各样的日期解析,我们通常会封装类似于DateUtils的工具类,专门用来处理日期字符串的解析,同时为了兼容不同格式的日期字符串,又需要预先枚举出可能用到的日期格式。这种传统的DateUtils通常会面临性能与兼容性的两难问题。

而本文要介绍的,是一个截然不同的日期解析工具dateparser,它可以智能地解析几百上千种任意格式的日期字符串,更为难得的是它的性能同样非常出色。

DateUtils的两难问题

一个比较典型的日期解析函数类似这样(这是commons-lang3在其DateUtils中提供的函数):

1
2
3
public static Date parseDate(final String str, final String... parsePatterns) {
return parseDate(str, null, parsePatterns);
}

这种日期解析函数的内部逻辑,往往是根据一批DATE_FORMAT轮番尝试,通过异常重试的方式出来唯一匹配的格式。这种简单粗暴的方式,事实上存在着一个两难问题。

首先,我们很难穷举出全部可能出现的日期格式,年月日的分隔符、排列次序、时分秒、是否有毫秒、时区处理、PM与AM的支持等等,罗列出来的话不计其数。

其次,异常重试的方式存在一些性能损耗,据我粗略测算,在MBP硬件环境中异常中断大概需要消耗2微秒,而一次日期解析可能消耗0.75微秒。如果提供的parsePatterns数量很多,则解析一个日期字符串的循环重试的最终耗时甚至会超过Redis读写操作。

那么,有没有办法既可以支持无数多个不规则的日期字符串,同时也没有性能问题的技术方案呢?

dateparser

这就是解决日期字符串解析的灵丹妙药,它是一个高性能且非常智能的datetime字符串解析工具。

为了实现高性能与可扩展性,它并没有采用SimpleDateFormatDateTimeFormatter,而是正则表达式。通过预定义的正则表达式来自动地捕捉不同格式的日期片段,它可以自动抽取出字符串中存在的 year, month, day, hour, minute, second, zone等熟悉。

这些预定义的正则表达式片段包括:

  • (?<week>%s)\W*可以将Monday解析为week
  • ?(?<year>\d{4})$可以将2019解析为year
  • ^(?<year>\d{4})(?<month>\d{2})$可以抽取出201909内部的yearmonth
  • ?(?<hour>\d{1,2}) o’clock\W*可以将12 o’clock解析为hour
  • 更多规则参见DateParserBuilder.java

如此多的正则表达式,会不会也存在性能隐患呢?如果使用的是java.util.regex包来进行循环匹配,随着规则增加,确实会有性能问题。

但是dateparser使用retree将预定义的一大批正则表达式合并为一颗树,也就是正则匹配树。它可以非常快速地对一大批正则表达式执行并行匹配,内部结构可以理解为字典树,但是树中的节点并不是字母,而是正则匹配节点。

安装Maven依赖

可以通过此maven坐标引入依赖:

1
2
3
4
5
<dependency>
<groupId>com.github.sisyphsu</groupId>
<artifactId>dateparser</artifactId>
<version>1.0.2</version>
</dependency>

基础使用

dateparser提供了一个DateParserUtils工具类,可以直接使用它将字符串解析为DateCalendarLocalDateTimeOffsetDateTime等:

1
2
3
4
5
6
7
8
9
10
11
Date date = DateParserUtils.parseDate("Mon Jan 02 15:04:05 -0700 2006");
// Tue Jan 03 06:04:05 CST 2006
Calendar calendar =
DateParserUtils.parseCalendar("Fri Jul 03 2015 18:04:07 GMT+0100 (GMT Daylight Time)");
// 2015-07-03T17:04:07Z
LocalDateTime dateTime =
DateParserUtils.parseDateTime("2019-09-20 10:20:30.12345678 +0200");
// 2019-09-20T16:20:30.123456780
OffsetDateTime offsetDateTime =
DateParserUtils.parseOffsetDateTime("2015-09-30 18:48:56.35272715 +0000 UTC");
// 2015-09-30T18:48:56.352727150Z

需要注意的是,它会根据字符串中标明的TimeZoneZoneOffset自动进行偏移量转换。

创建新DateParser实例

由于DateParser不是线程安全的,同时parse操作通常非常快速(1us),因此DateParserUtils内部直接维护了一个DateParser单例,然后通过synchronized进行并发控制。

如果你想在多线程中高频率、并发地使用它,就应该为不同的线程创建不同的DateParser实例:

1
2
3
DateParser parser = DateParser.newBuilder().build();
Date date = parser.parseDate("Mon Jan 02 15:04:05 -0700 2006");
// Tue Jan 03 06:04:05 CST 2006

DateParser实例相当笨重一些,所以你应该尽量多的复用它以提高性能。

MM/dddd/MM的优先级

多数情况下,dateparser可以按照规则自动地识别出字符串内部的monthday片段。

但是对于MM/dd/yydd/MM/yy,有时候它就难以区分了。因为世界上多数国家会使用dd/MM/yy作为日期的格式,但是也有少数国家会特立独行地使用MM/dd/yy作为日期格式,最典型的就是美帝国主义。

因此当dateparser遇到类似于7.8.2019这样的日期时,它就很难判断到底是7月8日还是8月7日

为解决这个难题,dateparser内部增加了一个名为preferMonthFirst的选项,用于辅助解决这个问题:

1
2
3
4
5
6
DateParserUtils.preferMonthFirst(true);
DateParserUtils.parseCalendar("08.03.71");
// 1971-08-03
DateParserUtils.preferMonthFirst(false);
DateParserUtils.parseCalendar("08.03.71");
// 1971-03-08

默认情况下,如果无法甄别,则视为在后。如果你指定了preferMonthFirsttrue,则试为在前。

自定义Parser

你可以使用DateParserBuilder构建自己的日期解析器,通过此builder`,你可以自定义新的解析规则。

例如,如果你想支持【2019】这样的year字符串,可以这样做:

1
2
3
DateParser parser = DateParser.newBuilder().addRule("【(?<year>\\d{4})】").build();
Calendar calendar = parser.parseCalendar("【1991】");
assert calendar.get(Calendar.YEAR) == 1991;

需要注意的是,正则表达式【(?<year>\\d{4})】里面的year非常重要,它是dateparser内置的捕捉关键词。

你也可以增加更加灵活的解析规则,就像这样:

1
2
3
4
5
6
7
8
9
10
11
DateParser parser = DateParser.newBuilder()
.addRule("民国(\\d{3})年", (input, matcher, dt) -> {
int offset = matcher.start(1);
int i0 = input.charAt(offset) - '0';
int i1 = input.charAt(offset + 1) - '0';
int i2 = input.charAt(offset + 2) - '0';
dt.setYear(i0 * 100 + i1 * 10 + i2 + 1911);
})
.build();
Calendar calendar = parser.parseCalendar("民国101年");
assert calendar.get(Calendar.YEAR) == 2012;

这个例子里面,新增了一个捕捉并解析民国xxx年的日期规则。

性能对比

你可以在此处查看Benchmark的源代码。

首先,在单一日期格式下,对比一下dateparserSimpleDateFormat的性能表现:

1
2
3
Benchmark               Mode  Cnt     Score    Error  Units
SingleBenchmark.java avgt 6 921.632 ± 12.299 ns/op
SingleBenchmark.parser avgt 6 1553.909 ± 70.664 ns/op

可以看到,在日期格式固定且单一的情况下,dateparser在性能上处于下风,这也在预料之中。

然后,在单一日期格式下,对比一下dateparserDateTimeFormatter的性能表现:

1
2
3
Benchmark                       Mode  Cnt     Score    Error  Units
SingleDateTimeBenchmark.java avgt 6 654.553 ± 16.703 ns/op
SingleDateTimeBenchmark.parser avgt 6 1680.690 ± 34.214 ns/op

可以看到,DateTimeFormatter的性能表现确实比SimpleDateFormat更加出色一些。同时dateparser的设计初衷是为了应对不规则日期格式,因此在固定格式匹配上存在劣势并不意外。

如果我们将日期格式增加为16种时,性能表现就不一样了:

1
2
3
Benchmark              Mode  Cnt      Score      Error  Units
MultiBenchmark.format avgt 6 47385.021 ± 1083.649 ns/op
MultiBenchmark.parser avgt 6 22852.113 ± 310.720 ns/op

如果换算一下,无论日期格式是一种还是16中,dateparser的性能始终维持在1.5us,说明它在算法上是非常稳定的,面对不同的场景不会有什么性能损失。

支持的日期格式(部分)

以下为dateparser在单元测试中完成测试解析的日期格式样例,具体可以参考源代码。同时需要注意的是,这个列表只是一个子集:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
May 8, 2009 5:57:51 PM                               
oct 7, 1970
oct 7, '70
oct. 7, 1970
oct. 7, 70
Mon Jan 2 15:04:05 2006
Mon Jan 2 15:04:05 MST 2006
Mon Jan 02 15:04:05 -0700 2006
Monday, 02-Jan-06 15:04:05 MST
Mon, 02 Jan 2006 15:04:05 MST
Tue, 11 Jul 2017 16:28:13 +0200 (CEST)
Mon, 02 Jan 2006 15:04:05 -0700
Thu, 4 Jan 2018 17:53:36 +0000
Mon Aug 10 15:44:11 UTC+0100 2015
Fri Jul 03 2015 18:04:07 GMT+0100 (GMT Daylight Time)
September 17, 2012 10:09am
September 17, 2012 at 10:09am PST-08
September 17, 2012, 10:10:09
October 7, 1970
October 7th, 1970
12 Feb 2006, 19:17
12 Feb 2006 19:17
7 oct 70
7 oct 1970
03 February 2013
1 July 2013
2013-Feb-03
3/31/2014
03/31/2014
08/21/71
8/1/71
4/8/2014 22:05
04/08/2014 22:05
4/8/14 22:05
04/2/2014 03:00:51
8/8/1965 12:00:00 AM
8/8/1965 01:00:01 PM
8/8/1965 01:00 PM
8/8/1965 1:00 PM
8/8/1965 12:00 AM
4/02/2014 03:00:51
03/19/2012 10:11:59
03/19/2012 10:11:59.3186369
2014/3/31
2014/03/31
2014/4/8 22:05
2014/04/08 22:05
2014/04/2 03:00:51
2014/4/02 03:00:51
2012/03/19 10:11:59
2012/03/19 10:11:59.3186369
2014年04月08日
2006-01-02T15:04:05+0000
2009-08-12T22:15:09-07:00
2009-08-12T22:15:09
2009-08-12T22:15:09Z
2014-04-26 17:24:37.3186369
2012-08-03 18:31:59.257000000
2014-04-26 17:24:37.123
2013-04-01 22:43
2013-04-01 22:43:22
2014-12-16 06:20:00 UTC
2014-12-16 06:20:00 GMT
2014-04-26 05:24:37 PM
2014-04-26 13:13:43 +0800
2014-04-26 13:13:43 +0800 +08
2014-04-26 13:13:44 +09:00
2012-08-03 18:31:59.257000000 +0000 UTC
2015-09-30 18:48:56.35272715 +0000 UTC
2015-02-18 00:12:00 +0000 GMT
2015-02-18 00:12:00 +0000 UTC
2015-02-08 03:02:00 +0300 MSK m=+0.000000001
2015-02-08 03:02:00.001 +0300 MSK m=+0.000000001
2017-07-19 03:21:51+00:00
2014-04-26
2014-04
2014
2014-05-11 08:20:13,787
3.31.2014
03.31.2014
08.21.71
2014.03
2014.03.30
20140601
20140722105203
1332151919
1384216367189
1384216367111222
1384216367111222333

这些测试案例中的绝大多数都来自于https://github.com/araddon/dateparse.

写在最后

这个日期解析工具主要用来演示retree算法的使用场景和实际表现。

如果你对它的算法原理感到好奇的话,可以直接查看它的源代码或文档,也可以通过评论等联系我。

如果你希望dateparser支持一些新的格式,也可以通过issue提出建议。

如果使用过程中遇到问题或bug,也欢迎提出issue,我会第一时间解决。