Java8新的时间和日期API

旧的缺陷

在Java 8之前，所有关于时间和日期的API都存在各种使用方面的缺陷，主要有：

Java的java.util.Date和java.util.Calendar类易用性差，不支持时区，而且他们都不是线程安全的；
用于格式化日期的类DateFormat被放在java.text包中，它是一个抽象类，所以我们需要实例化一个SimpleDateFormat对象来处理日期格式化，并且DateFormat也是非线程安全，这意味着如果你在多线程程序中调用同一个DateFormat对象，会得到意想不到的结果。
对日期的计算方式繁琐，而且容易出错，因为月份是从0开始的，从Calendar中获取的月份需要加一才能表示当前月份。

由于以上这些问题，出现了一些三方的日期处理框架，例如Joda-Time，date4j等开源项目。但是，Java需要一套标准的用于处理时间和日期的框架，于是Java 8中引入了新的日期API。新的日期API是JSR-310规范的实现，Joda-Time框架的作者正是JSR-310的规范的倡导者，所以能从Java 8的日期API中看到很多Joda-Time的特性。

Java 8日期/时间类

Java 8的日期和时间类包含LocalDate、LocalTime、Instant、Duration以及Period，这些类都包含在java.time包中，下面我们看看这些类的用法。

综述

新的API：java.time，由5个包组成：

java.time – 包含值对象的基础包
java.time.chrono – 提供对不同的日历系统的访问
java.time.format – 格式化和解析时间和日期
java.time.temporal – 包括底层框架和扩展特性
java.time.zone – 包含时区支持的类
大多数开发者只会用到基础和format包，也可能会用到temporal包。因此，尽管有68个新的公开类型，大多数开发者，大概，将只会用到其中的三分之一。

LocalDate和LocalTime

LocalDate类表示一个具体的日期，但不包含具体时间，也不包含时区信息。可以通过LocalDate的静态方法of()创建一个实例，LocalDate也包含一些方法用来获取年份，月份，天，星期几等：

LocalDate localDate = LocalDate.of(2019, 7, 3);     // 初始化一个日期：2019-07-03
int year = localDate.getYear();                     // 年份：2019
Month month = localDate.getMonth();                 // 月份：JULY
int dayOfMonth = localDate.getDayOfMonth();         // 月份中的第几天：3
DayOfWeek dayOfWeek = localDate.getDayOfWeek();     // 一周的第几天：WEDNESDAY
int length = localDate.lengthOfMonth();             // 月份的天数：31
boolean leapYear = localDate.isLeapYear();          // 是否为闰年：false

也可以调用静态方法now()来获取当前日期：

1	LocalDate now = LocalDate.now(); // 2019-07-03

LocalTime和LocalDate类似，他们之间的区别在于LocalDate不包含具体时间，而LocalTime包含具体时间，例如：

LocalTime localTime = LocalTime.of(21, 48, 26);     // 初始化一个时间：21:48:26
int hour = localTime.getHour();                     // 时：21
int minute = localTime.getMinute();                 // 分：48
int second = localTime.getSecond();                 // 秒：26

同样可以调用静态方法now()来获取当前时间

1	LocalTime now = LocalTime.now() // 21:48:21.487

LocalDateTime

LocalDateTime类是LocalDate和LocalTime的结合体，可以通过of()方法直接创建，也可以调用LocalDate的atTime()方法或LocalTime的atDate()方法将LocalDate或LocalTime合并成一个LocalDateTime：

LocalDateTime ldt1 = LocalDateTime.of(2019, Month.JULY, 3, 21, 48, 26);

LocalDate localDate = LocalDate.of(2019, Month.JULY, 3);
LocalTime localTime = LocalTime.of(21, 48, 26);
LocalDateTime ldt2 = localDate.atTime(localTime);

LocalDateTime也提供用于向LocalDate和LocalTime的转化：

1
2
3

LocalDateTime ldt1 = LocalDateTime.now(); // 2019-07-03T21:54:11.707
LocalDate date = ldt1.toLocalDate(); // 2019-07-03
LocalTime time = ldt1.toLocalTime(); // 21:54:11.707

LocalDateTime的其他方法跟LocalDate和LocalTime相似。这种相似的方法模式非常有利于API的学习。下面总结了用到的方法前缀：

of：静态工厂方法，从组成部分中创建实例
from：静态工厂方法，尝试从相似对象中提取实例。from()方法没有of()方法类型安全
now：静态工厂方法，用当前时间创建实例
parse：静态工厂方法，总字符串解析得到对象实例
get：获取时间日期对象的部分状态
is：检查关于时间日期对象的描述是否正确
with：返回一个部分状态改变了的时间日期对象拷贝
plus：返回一个时间增加了的、时间日期对象拷贝
minus：返回一个时间减少了的、时间日期对象拷贝
to：把当前时间日期对象转换成另外一个，可能会损失部分状态
at：用当前时间日期对象组合另外一个，创建一个更大或更复杂的时间日期对象
format：提供格式化时间日期对象的能力

Instant

Instant用于表示一个时间戳，它与我们常使用的System.currentTimeMillis()有些类似，不过Instant可以精确到纳秒（Nano-Second），System.currentTimeMillis()方法只精确到毫秒（Milli-Second）。如果查看Instant源码，发现它的内部使用了两个常量，seconds表示从1970-01-01 00:00:00开始到现在的秒数，nanos表示纳秒部分（nanos的值不会超过999,999,999）。
Instant典型的用法是，当你需要记录事件的发生时间，而不需要记录任何有关时区信息时，存储和比较时间戳。
Instant除了使用now()方法创建外，还可以通过ofEpochSecond方法创建：

1 2	Instant instant = Instant.now(); // 2019-07-03T13:56:36.792Z Instant instant2 = Instant.ofEpochSecond(120, 100000); // 1970-01-01T00:02:00.000100Z

ofEpochSecond()方法的第一个参数为秒，第二个参数为纳秒，上面的代码表示从1970-01-01 00:00:00开始后两分钟的10万纳秒的时刻。

Duration

Duration的内部实现与Instant类似，也是包含两部分：seconds表示秒，nanos表示纳秒。两者的区别是Instant用于表示一个时间戳（或者说是一个时间点），而Duration表示一个时间段，所以Duration类中不包含now()静态方法。可以通过Duration.between()方法创建Duration对象：

LocalDateTime from = LocalDateTime.of(2019, Month.JANUARY, 1, 10, 7, 0);    // 2019-01-01 10:07:00
LocalDateTime to = LocalDateTime.of(2019, Month.JULY, 3, 21, 59, 0);     // 2019-07-03 21:59:00
Duration duration = Duration.between(from, to);     // 表示从 2019-01-01 10:07:00 到 2019-07-03 21:59:00 这段时间

long days = duration.toDays();              // 这段时间的总天数
long hours = duration.toHours();            // 这段时间的小时数
long minutes = duration.toMinutes();        // 这段时间的分钟数
long seconds = duration.getSeconds();       // 这段时间的秒数
long milliSeconds = duration.toMillis();    // 这段时间的毫秒数
long nanoSeconds = duration.toNanos();      // 这段时间的纳秒数

Duration对象还可以通过of()方法创建，该方法接受一个时间段长度，和一个时间单位作为参数：

1 2	Duration duration1 = Duration.of(5, ChronoUnit.DAYS); // 5天 Duration duration2 = Duration.of(1000, ChronoUnit.MILLIS); // 1000毫秒

Period

Period在概念上和Duration类似，区别在于Period是以年月日来衡量一个时间段，比如2年3个月6天：

1	Period period = Period.of(2, 3, 6);

Period对象也可以通过between()方法创建，值得注意的是，由于Period是以年月日衡量时间段，所以between()方法只能接收LocalDate类型的参数：

1 2	// 2019-01-01 到 2019-07-03 这段时间 Period period = Period.between(LocalDate.of(2019, 1, 1), LocalDate.of(2019, 7, 3));

操作日期

增加和减少日期

Java 8中的日期/时间类都是不可变的，这是为了保证线程安全。当然，新的日期/时间类也提供了方法用于创建对象的可变版本，比如增加一天或者减少一天：

LocalDate date = LocalDate.of(2019, 7, 3);          // 2019-07-03

LocalDate date1 = date.withYear(2018);              // 修改为 2018-07-03
LocalDate date2 = date.withMonth(2);                // 修改为 2019-02-03
LocalDate date3 = date.withDayOfMonth(1);           // 修改为 2019-07-01

LocalDate date4 = date.plusYears(1);                // 增加一年 2020-07-03
LocalDate date5 = date.minusMonths(2);              // 减少两个月 2019-05-03
LocalDate date6 = date.plus(5, ChronoUnit.DAYS);    // 增加5天 2019-07-08

上面例子中对于日期的操作比较简单，但是有些时候我们要面临更复杂的时间操作，比如将时间调到下一个工作日，或者是下个月的最后一天，这时候我们可以使用with()方法的另一个重载方法，它接收一个TemporalAdjuster参数，可以使我们更加灵活的调整日期：

1
2

LocalDate date7 = date.with(TemporalAdjusters.nextOrSame(DayOfWeek.SUNDAY));      // 返回下一个距离当前时间最近的星期日
LocalDate date9 = date.with(TemporalAdjusters.lastInMonth(DayOfWeek.SATURDAY));   // 返回本月最后一个星期六

如果上面表格中列出的方法不能满足你的需求，你还可以创建自定义的TemporalAdjuster接口的实现，TemporalAdjuster也是一个函数式接口，所以我们可以使用Lambda表达式：

@FunctionalInterface
public interface TemporalAdjuster {
    Temporal adjustInto(Temporal temporal);
}

比如给定一个日期，计算该日期的下一个工作日（不包括星期六和星期天）：

LocalDate date = LocalDate.of(2019, 7, 3);
date.with(temporal -> {
    // 当前日期
    DayOfWeek dayOfWeek = DayOfWeek.of(temporal.get(ChronoField.DAY_OF_WEEK));

    // 正常情况下，每次增加一天
    int dayToAdd = 1;

    // 如果是星期五，增加三天
    if (dayOfWeek == DayOfWeek.FRIDAY) {
        dayToAdd = 3;
    }

    // 如果是星期六，增加两天
    if (dayOfWeek == DayOfWeek.SATURDAY) {
        dayToAdd = 2;
    }

    return temporal.plus(dayToAdd, ChronoUnit.DAYS);
});

格式化日期

新的日期API中提供了一个DateTimeFormatter类用于处理日期格式化操作，它被包含在java.time.format包中，Java 8的日期类有一个format()方法用于将日期格式化为字符串，该方法接收一个DateTimeFormatter类型参数：

LocalDateTime dateTime = LocalDateTime.now(); // 2019-07-03T22:19:47.703
String strDate1 = dateTime.format(DateTimeFormatter.BASIC_ISO_DATE);    // 20190703
String strDate2 = dateTime.format(DateTimeFormatter.ISO_LOCAL_DATE);    // 2019-07-03
String strDate3 = dateTime.format(DateTimeFormatter.ISO_LOCAL_TIME);    // 22:19:47.703
String strDate4 = dateTime.format(DateTimeFormatter.ISO_LOCAL_DATE_TIME); // 2019-07-03T22:19:47.703
String strDate5 = dateTime.format(DateTimeFormatter.ofPattern("yyyy-MM-dd"));   // 2019-07-03
String strDate6 = dateTime.format(DateTimeFormatter.ofPattern("今天是：yyyy年 MM月 dd日 E", Locale.CHINESE)); // 今天是：2019年 07月 03日 星期三

同样，日期类也支持将一个字符串解析成一个日期对象，例如：

String strDate7 = "2019-07-03";
String strDate8 = "2019-07-03 22:19:47";

LocalDate date = LocalDate.parse(strDate7, DateTimeFormatter.ofPattern("yyyy-MM-dd"));
LocalDateTime dateTime1 = LocalDateTime.parse(strDate8, DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss"));

时区

Java 8中的时区操作被很大程度上简化了，新的时区类java.time.ZoneId是原有的java.util.TimeZone类的替代品。ZoneId对象可以通过ZoneId.of()方法创建，也可以通过ZoneId.systemDefault()获取系统默认时区：

1 2	ZoneId shanghaiZoneId = ZoneId.of("Asia/Shanghai"); ZoneId systemZoneId = ZoneId.systemDefault();

of()方法接收一个“区域/城市”的字符串作为参数，你可以通过getAvailableZoneIds()方法获取所有合法的“区域/城市”字符串：

1	Set<String> zoneIds = ZoneId.getAvailableZoneIds();

对于老的时区类TimeZone，Java 8也提供了转化方法：

1	ZoneId oldToNewZoneId = TimeZone.getDefault().toZoneId();

有了ZoneId，我们就可以将一个LocalDate、LocalTime或LocalDateTime对象转化为ZonedDateTime对象：

1 2	LocalDateTime localDateTime = LocalDateTime.now(); ZonedDateTime zonedDateTime = ZonedDateTime.of(localDateTime, ZoneId.of("Asia/Shanghai")); // 2019-07-03T22:31:04.952+08:00[Asia/Shanghai]

ZonedDateTime对象由两部分构成，LocalDateTime和ZoneId，其中2019-07-03T22:31:04.952部分为LocalDateTime，+08:00[Asia/Shanghai]部分为ZoneId。

另一种表示时区的方式是使用ZoneOffset，它是以当前时间和世界标准时间（UTC）/格林威治时间（GMT）的偏差来计算，例如：

1
2
3

ZoneOffset zoneOffset = ZoneOffset.of("+09:00");
LocalDateTime localDateTime = LocalDateTime.now();
OffsetDateTime offsetDateTime = OffsetDateTime.of(localDateTime, zoneOffset);

其他历法

Java中使用的历法是ISO 8601日历系统，它是世界民用历法，也就是我们所说的公历。平年有365天，闰年是366天。闰年的定义是：非世纪年，能被4整除；世纪年能被400整除。为了计算的一致性，公元1年的前一年被当做公元0年，以此类推。

此外Java 8还提供了4套其他历法（很奇怪为什么没有汉族人使用的农历），每套历法都包含一个日期类，分别是

ThaiBuddhistDate：泰国佛教历
MinguoDate：中华民国历
JapaneseDate：日本历
HijrahDate：伊斯兰历
每个日期类都继承ChronoLocalDate类，所以可以在不知道具体历法的情况下也可以操作。不过这些历法一般不常用，除非是有某些特殊需求情况下才会使用。
这些不同的历法也可以用于向公历转换：
1
2
LocalDate date = LocalDate.now();
JapaneseDate jpDate = JapaneseDate.from(date);

由于它们都继承ChronoLocalDate类，所以在不知道具体历法情况下，可以通过ChronoLocalDate类操作日期：

1 2	Chronology jpChronology = Chronology.ofLocale(Locale.JAPANESE); ChronoLocalDate jpChronoLocalDate = jpChronology.dateNow();

我们在开发过程中应该尽量避免使用ChronoLocalDate，尽量用与历法无关的方式操作时间，因为不同的历法计算日期的方式不一样，比如开发者会在程序中做一些假设，假设一年中有12个月，如果是中国农历中包含了闰月，一年有可能是13个月，但开发者认为是12个月，多出来的一个月属于明年的。再比如假设年份是累加的，过了一年就在原来的年份上加一，但日本天皇在换代之后需要重新纪年，所以过了一年年份可能会从1开始计算。

在实际开发过程中建议使用LocalDate，包括存储、操作、业务规则的解读；除非需要将程序的输入或者输出本地化，这时可以使用ChronoLocalDate类。

Code Snippets

获取当前时间

// Old
Date now = new Date();  // Wed Jul 03 22:45:55 CST 2019
 
// New
ZonedDateTime now = ZonedDateTime.now(); // 2019-07-03T22:45:55.434+08:00[Asia/Shanghai]
LocalDateTime now = LocalDateTime.now(); // 2019-07-03T22:45:55.453
LocalDate now = LocalDate.now(); // 2019-07-03
LocalTime now = LocalTime.now(); // 22:45:55.453

表示特定时间

// Old
Date birthDay = new GregorianCalendar(1990, Calendar.DECEMBER, 15).getTime(); // Sat Dec 15 00:00:00 CST 1990
 
// New
LocalDate birthDay = LocalDate.of(1990, Month.DECEMBER, 15); // 1990-12-15

提取时间中特定部分

// Old
int month = new GregorianCalendar().get(Calendar.MONTH); // 6
 
// New
Month month = LocalDateTime.now().getMonth(); // JULY
int valueOfMonth = LocalDateTime.now().getMonth().getValue(); // 7

加减时间

// Old
GregorianCalendar calendar = new GregorianCalendar();
calendar.add(Calendar.HOUR_OF_DAY, -5);
Date fiveHoursBefore = calendar.getTime();
 
// New
LocalDateTime fiveHoursBefore = LocalDateTime.now().minusHours(5);

调整特定部分

// Old
GregorianCalendar calendar = new GregorianCalendar();
calendar.set(Calendar.MONTH, Calendar.JUNE);
Date inJune = calendar.getTime();
 
// New
LocalDateTime inJune = LocalDateTime.now().withMonth(Month.JUNE.getValue());

截取
截断重置小于指定字段的所有时间字段。在下面的示例中，分钟和下面的所有内容都将设置为零：

// Old
Calendar now = Calendar.getInstance();
now.set(Calendar.MINUTE, 0);
now.set(Calendar.SECOND, 0);
now.set(Calendar.MILLISECOND, 0);
Date truncated = now.getTime();  // Wed Jul 03 22:00:00 CST 2019
 
// New
LocalTime truncated = LocalTime.now().truncatedTo(ChronoUnit.HOURS); // 22:00

时区转换

// Old
GregorianCalendar calendar = new GregorianCalendar();
calendar.setTimeZone(TimeZone.getTimeZone("CET"));
Date centralEastern = calendar.getTime(); // Wed Jul 03 22:56:29 CST 2019
 
// New
ZonedDateTime centralEastern = LocalDateTime.now().atZone(ZoneId.of("CET")); // 2019-07-03T22:56:30.005+02:00[CET]

获得两个时间点之间的时间跨度

// Old
GregorianCalendar calendar = new GregorianCalendar();
Date now = new Date();
calendar.add(Calendar.HOUR, 1);
Date hourLater = calendar.getTime();
long elapsed = hourLater.getTime() - now.getTime();
 
// New
LocalDateTime now = LocalDateTime.now();
LocalDateTime hourLater = LocalDateTime.now().plusHours(1);
Duration span = Duration.between(now, hourLater);  // span.toMillis()

时间格式化及解析
DateTimeFormatter是旧的SimpleDateFormat的替代品，它是线程安全的并提供其他功能。

// Old
SimpleDateFormat dateFormat = new SimpleDateFormat("yyyy-MM-dd");
Date now = new Date();
String formattedDate = dateFormat.format(now); // 2019-07-03
Date parsedDate = dateFormat.parse(formattedDate); // Wed Jul 03 00:00:00 CST 2019
 
// New
LocalDate now = LocalDate.now();
DateTimeFormatter formatter = DateTimeFormatter.ofPattern("yyyy-MM-dd");
String formattedDate = now.format(formatter); // 2019-07-03
// or String formattedDate = now.format(DateTimeFormatter.ISO_LOCAL_DATE) 
LocalDate parsedDate = LocalDate.parse(formattedDate, formatter); // 2019-07-03

一个月的天数

// Old
Calendar calendar = new GregorianCalendar(1990, Calendar.FEBRUARY, 20);
int daysInMonth = calendar.getActualMaximum(Calendar.DAY_OF_MONTH);
 
// New
int daysInMonth = YearMonth.of(1990, 2).lengthOfMonth();

与旧代码交互

Instant instantFromCalendar = GregorianCalendar.getInstance().toInstant();

ZonedDateTime zonedDateTimeFromCalendar = new GregorianCalendar().toZonedDateTime();

// Instant转Date
Date dateFromInstant = Date.from(Instant.now());

// Date转LocalDate
LocalDate localDate = new Date().toInstant().atZone(ZoneId.systemDefault()).toLocalDate();

// LocalDate转Date
Date date = Date.from(LocalDate.now().atStartOfDay(ZoneId.systemDefault()).toInstant());

GregorianCalendar calendarFromZonedDateTime = GregorianCalendar.from(ZonedDateTime.now());

// Date转Instant
Instant instantFromDate = new Date().toInstant();

ZoneId zoneIdFromTimeZone = TimeZone.getTimeZone("PST").toZoneId();

[1]JAVA 8：健壮、易用的时间/日期API
[2]Java 8 学习之——时间日期API
[3]Java 8新特性（四）：新的时间和日期API
[4]Guide to DateTimeFormatter
[5]Introduction to Joda-Time
[6]Get the Current Date, Time and Timestamp in Java 8
[7]Introduction to the Java 8 Date/Time API
[8]Migrating to the New Java 8 Date Time API
[9]LocalDate、LocalDateTime与timestamp、Date的转换

Java8新的时间和日期API

Java8新的时间和日期API

旧的缺陷

Java 8日期/时间类

综述

LocalDate和LocalTime

LocalDateTime

Instant

Duration

Period

操作日期

增加和减少日期

格式化日期

时区

其他历法

Code Snippets

与旧代码交互

Read More