看山聊Java：开始使用 Java8 中的时间类

刺骨的言语ヽ痛彻心扉 2021-09-25 11:26 313阅读 0赞

![Java8 的时间库（3）：开始使用 Java8 中的时间类][Java8 _3_ Java8]

> 该图片由[Erik Karits][]在[Pixabay][]上发布

你好，我是看山。

前面聊了聊 Java8 新版时间 API 的类，然后又说了说怎么与旧版时间 API 的转换，今天来聊聊怎样通过新 API 实现老 API 的功能，这样我们就可以逐步替换掉旧版 API，与时俱进。

Java8 之前，我们常用的时间类有`java.util.date`、`java.util.Calendar`和`java.util.Timezone`。还会有一些不那么常用的，`java.sql.Date`、`java.sql.TimeStamp`。

这些类可以实现一些简单的功能，但是要实现复杂的功能，我们只能自己实现很多工具类，或者借助第三方类库，其中比较著名的第三方库是 joda-time，后来 Java8 吸收其设计，直接让 joda-time 转正了。

> 因为这个系列说的都是时间库，后文没有特殊说明，使用“新版 API”指代`JSR 310`提供的时间 API，使用“旧版 API”指代 Java 8 之前提供的官方时间 API。

## 新版 API 的优势 ##

新版 API 的优势，对应的就是旧版 API 的劣势。

### 语义明确 ###

这点非常重要。

我们在定义一个实体的时候，能够做到语义明确没有歧义非常重要。

比如，我们需要定义出生日期，只需要年月日，在以前只能用`java.util.Date`，但是这个类包含时分秒。

或者，我们需要定义生日，正常只需要月日就行，连年都不需要，`java.util.Date`更加做不到。

在这些场景中，我们只能通过注释或者属性名做一些松散约束，很容易出错。

经验告诉我们，人是不可靠的，约定是不可靠的，只要有犯错的可能，就一定会犯错。

新版 API 完美解决这个问题，提供具有不同语义且语义明确的类。如果想表示日期可以用`LocalDate`，如果想表示生日，可以用`MonthDay`。这样，我们就能够借助编译器增强约束力。

### 符合自然规律 ###

我们来通过一段代码感受下（测试日期是 2021 年 6 月 28 日），执行结果放在每行结尾处：

Date date = new Date();
    System.out.println(date);// Mon Jun 28 21:41:25 CST 2021
    System.out.println(date.getYear());// 121
    System.out.println(date.getMonth());// 5
    System.out.println(date.getDay());// 1
    
    Calendar calendar = Calendar.getInstance();
    calendar.setTime(date);
    System.out.println(calendar.get(Calendar.YEAR));// 2021
    System.out.println(calendar.get(Calendar.MONTH));// 5
    System.out.println(calendar.get(Calendar.DAY_OF_MONTH));// 28
    
    LocalDate localDate = LocalDate.now();
    System.out.println(localDate.getYear());// 2021
    System.out.println(localDate.getMonth());// JUNE
    System.out.println(localDate.getDayOfMonth());// 28

仅仅一个年月日的获取，旧版 API 已经是存在各种含义。

`java.util.Date#getYear`表示的是当前年份减去 1900；`java.util.Date#getDay`返回的是当前是一周中的第几天，下标从 0 开始。当然，这几个 API 在 JDK1.1 的时候已经标记废弃了，但是知道现在也没有删除。相信很多初次使用旧版 API 的同学，都可能踩过坑。

更甚的是，`java.util.Date`和`java.util.Calendar`的返回的月份，都是从 0 开始计数的。但是年和日是从 1 开始计数，实在没有搞懂当时开发人员的脑回路是怎样的。

再看新版 API，完全符合我们的认知：年是自然年，月使用`Month`枚举（枚举的 value 值是自然月），日是自然日，一切都是根据我们对自然规律的理解。

而且，新版 API 很贴心的考虑了夏令时，在使用`ZonedDateTime`进行不同区域时间转换时，会自动计算。可以说，关于时间的逻辑，新版 API 已经都包含了。

### 功能完善 ###

旧版 API 提供的时间类，只能实现一些简单的逻辑，想要做一些复杂的操作，就需要自己实现。新版 API 提供了灵活的时间功能 API。

*  `Instant`：表示时间戳，也就是一个时间点。
 *  `LocalDate`：表示日期，年、月、日
 *  `LocalTime`：表示时间，时、分、秒、纳秒
 *  `LocalDateTime`：表示日期+时间，内部也是通过`LocalDate`和`LocalTime`存储数据的
 *  `OffsetDateTime`：带有时间偏移的`LocalDateTime`
 *  `OffsetTime`：带有时间偏移的`LocalTime`
 *  `ZonedDateTime`：比`OffsetDateTime`多了时区，也就是带有时区、带有时间偏移的`LocalDateTime`
 *  `MonthDay`：表示月、日，不包含年和时间
 *  `YearMonth`：表示年、月，不包含日和时间
 *  `Duration`：表示纳秒、秒的时间量，可以度量天、小时、分、秒、毫秒、纳秒。
 *  `Period`：表示年、月、日的时间量，可以度量年、月、日、周。

有了上面这些类，我们可以在操作时间时横着走了。

### 不可变（线程安全） ###

上面提到的这些类中，都是不可修改的，这些类的成员变量都使用`final`修饰，所有需要修改数据的方法，都是返回一个新实例。新版 API 通过这种方式实现了时间类的不可变性。

我们都知道，一个对象是不可变的，那它就是线程安全的。

旧版 API 的则不是这样，数据可变且对并发敏感。当然，这只能算是设计初衷不同。

新版 API 表示时间的类是线程安全的，可以对时间格式化的`DateTimeFormatter`也是时间安全的。

旧版的`SimpleDateFormat`也是类似的功能，但却不是线程安全的。这点就不是设计初衷不同了，而是缺少设计。相信很多没有被这个类毒打过的小白，会定义一些工具类，里面是`static`定义的`SimpleDateFormat`，然后对时间进行格式化，测试的时候没有一点问题，放在线上就出现各种诡异错误。

## 开启征程 ##

我们通过一些常用场景，展示新旧版本 API 的实现方式。

### 获取当前时间 ###

旧版 API：

Date now = new Date();

新版 API：

// 没有偏移、没有时区概念的当前时间
    LocalDateTime now = LocalDateTime.now();
    // 有偏移和时区的当前时间
    ZonedDateTime now2 = ZonedDateTime.now();

### 指定日期 ###

旧版 API：

Date birthday = new GregorianCalendar(1988, Calendar.AUGUST, 20).getTime();

新版 API：

LocalDate birthday = LocalDate.of(1988, Month.AUGUST, 20);
    LocalDate birthday2 = LocalDate.of(1988, 8, 20);

### 获取指定量 ###

旧版 API：

int month = new GregorianCalendar().get(Calendar.MONTH);

新版 API：

Month month = LocalDateTime.now().getMonth();

### 调整时间 ###

比如，获取当前之间 5 小时前的时间。

旧版 API：

GregorianCalendar calendar = new GregorianCalendar();
    calendar.add(Calendar.HOUR_OF_DAY, -5);
    Date fiveHoursBefore = calendar.getTime();

新版 API：

LocalDateTime fiveHoursBefore = LocalDateTime.now().minusHours(5);

### 调整指定时间量 ###

比如，将时间调整到 6 月。

旧版 API：

GregorianCalendar calendar = new GregorianCalendar();
    calendar.set(Calendar.MONTH, Calendar.JUNE);
    Date inJune = calendar.getTime();

新版 API：

LocalDateTime inJune = LocalDateTime.now().withMonth(Month.JUNE.getValue());

### 截断时间量 ###

我们有时候会将时间对象某个单位后面的所有时间量设置为 0，这个操作形象的称为截断。比如，将分、秒、毫秒设置为零。

旧版 API：

Calendar now = Calendar.getInstance();
    now.set(Calendar.MINUTE, 0);
    now.set(Calendar.SECOND, 0);
    now.set(Calendar.MILLISECOND, 0);
    Date truncated = now.getTime();

新版 API：

LocalTime truncated = LocalTime.now().truncatedTo(ChronoUnit.HOURS);

### 时区转换 ###

旧版 API：

GregorianCalendar calendar = new GregorianCalendar();
    calendar.setTimeZone(TimeZone.getTimeZone("CET"));
    Date centralEastern = calendar.getTime();

新版 API：

ZonedDateTime centralEastern = LocalDateTime.now().atZone(ZoneId.of("CET"));

### 计算时间跨度 ###

旧版 API：

GregorianCalendar calendar = new GregorianCalendar();
    Date now = new Date();
    calendar.add(Calendar.HOUR, 1);
    Date hourLater = calendar.getTime();
    long elapsed = hourLater.getTime() - now.getTime();

新版 API：

LocalDateTime now = LocalDateTime.now();
    LocalDateTime hourLater = LocalDateTime.now().plusHours(1);
    Duration span = Duration.between(now, hourLater);

`Duration`是跨度较小，可以度量天、小时、分、秒、毫秒、纳秒。如果跨度较大，可以使用`Period`，可以度量年、月、日、周。

### 时间格式化和解析 ###

新版 API 使用`DateTimeFormatter`，这个类是线程安全的。而且相较于`SimpleDateFormat`提供了很多额外的功能。

旧版 API：

SimpleDateFormat dateFormat = new SimpleDateFormat("yyyy-MM-dd");
    Date now = new Date();
    String formattedDate = dateFormat.format(now);
    Date parsedDate = dateFormat.parse(formattedDate);

新版 API：

DateTimeFormatter formatter = DateTimeFormatter.ofPattern("yyyy-MM-dd");
    LocalDate now = LocalDate.now();
    String formattedDate = now.format(formatter);
    LocalDate parsedDate = LocalDate.parse(formattedDate, formatter);

### 其他一些小功能 ###

比如，计算一个月有几天：

旧版 API：

Calendar calendar = new GregorianCalendar(1990, Calendar.FEBRUARY, 20);
    int daysInMonth = calendar.getActualMaximum(Calendar.DAY_OF_MONTH);

新版 API：

int daysInMonth = YearMonth.of(1990, 2).lengthOfMonth();

## 新旧版 API 的转换 ##

新版 API 虽然好用，但是罗马不是一天建成的。旧版 API 不会一夜消失，可能需要共用。Java 8 提供了很多方法，用来在新旧版本 API 之间进行转换。比如：

// 从 Calendar 转换 Instant
    Instant instantFromCalendar = GregorianCalendar.getInstance().toInstant();
    // 从 Calendar 转换 ZonedDateTime
    ZonedDateTime zonedDateTimeFromCalendar = new GregorianCalendar().toZonedDateTime();
    // 从 Instant 转换 Date
    Date dateFromInstant = Date.from(Instant.now());
    // 从 ZonedDateTime 转换 Calendar
    GregorianCalendar calendarFromZonedDateTime = GregorianCalendar.from(ZonedDateTime.now());
    // 从 Date 转换 Instant
    Instant instantFromDate = new Date().toInstant();
    // 从 TimeZone 转换 ZoneId
    ZoneId zoneIdFromTimeZone = TimeZone.getTimeZone("PST").toZoneId();

更多的内容可以看看该系列的另一篇：[Java8 的时间库（2）：Date 与 LocalDate 或 LocalDateTime 互相转换][Java8 _2_Date _ LocalDate _ LocalDateTime]。

## 文末总结 ##

在本文中，我们讲解了旧版 API 的缺点、新版 API 的优点。新版 API 提供了很多友好的方法，而且不同类之间操作几乎一致，所以很多例子虽然只是说了一个类的使用，但是其他类也可以采用相似方式实现。

## 推荐阅读 ##

1.  [Java8 的时间库（1）：介绍 Java8 中的时间类及常用 API][Java8 _1_ Java8 _ API]
2.  [Java8 的时间库（2）：Date 与 LocalDate 或 LocalDateTime 互相转换][Java8 _2_Date _ LocalDate _ LocalDateTime]
3.  [Java8 的时间库（3）：开始使用 Java8 中的时间类][Java8 _3_ Java8 1]
4.  未完待续……

--------------------

你好，我是看山，10 年老猿，开源贡献者。游于码界，戏享人生。关注公众号：[看山的小屋][Link 1]，领取学习资料。

个人主页：[https://www.howardliu.cn][https_www.howardliu.cn]  
个人博文：[Java8 的时间库（3）：开始使用 Java8 中的时间类][Java8 _3_ Java8 1]  
CSDN 主页：[https://kanshan.blog.csdn.net/][https_kanshan.blog.csdn.net]  
CSDN 博文：[Java8 的时间库（3）：开始使用 Java8 中的时间类][Java8 _3_ Java8 2]

![公众号：看山的小屋][21785bb43b333b0ff8efda479e715378.png]

[Java8 _3_ Java8]: /images/20210923/c4c19f10fd204942a610f760787b9d34.png
[Erik Karits]: https://pixabay.com/zh/users/erik_karits-15012370/?utm_source=link-attribution&utm_medium=referral&utm_campaign=image&utm_content=6370080
[Pixabay]: https://pixabay.com/zh/?utm_source=link-attribution&utm_medium=referral&utm_campaign=image&utm_content=6370080
[Java8 _2_Date _ LocalDate _ LocalDateTime]: https://www.howardliu.cn/java-date-to-localdate-and-localdatetime/
[Java8 _1_ Java8 _ API]: https://www.howardliu.cn/java-date-and-time-intro/
[Java8 _3_ Java8 1]: https://www.howardliu.cn/java-date-time-migrating-to-jsr310/
[Link 1]: http://static.howardliu.cn/about/kanshanshuo.png
[https_www.howardliu.cn]: https://www.howardliu.cn
[https_kanshan.blog.csdn.net]: https://kanshan.blog.csdn.net/
[Java8 _3_ Java8 2]: https://kanshan.blog.csdn.net/article/details/118371660
[21785bb43b333b0ff8efda479e715378.png]: /images/20210923/99d35f28e8ce4e40816ccbbee887a287.png