本文旨在解决在 java `java.time` api 中解析形如 "yyyy-mm-ddthh:mm:ss.sss+hhmm" 格式时间戳时遇到的常见 `datetimeparseexception` 错误。核心问题在于默认解析器无法直接识别不带冒号的数字时区偏移量。教程将详细介绍如何通过自定义 `datetimeformatter` 模式（特别是使用 `xx` 符号）结合 `offsetdatetime` 进行正确解析，并演示如何将其转换为 `instant`。
理解 java.time API 与时间戳解析问题
Java 8 引入的 java.time 包提供了一套现代化的日期和时间 API，旨在解决旧 java.util.Date 和 java.util.Calendar 的痛点。它提供了不可变、线程安全的类，如 Instant、LocalDateTime、OffsetDateTime 和 ZonedDateTime，以及强大的格式化和解析工具 DateTimeFormatter。
当尝试解析一个包含数字时区偏移量（例如 +0100 或 +0800）的时间戳字符串时，例如 "2022-12-12T09:51:09.681+0100"，直接使用 Instant.parse() 或 OffsetDateTime.parse() 方法通常会导致 java.time.format.DateTimeParseException 异常。这是因为这些类的默认 parse() 方法遵循 ISO 8601 标准的严格子集，其中对于时区偏移量，通常期望的形式是 Z (UTC)、+HH:MM 或 +HHMM (带冒号)。而 +HHMM (不带冒号) 的格式，虽然在某些上下文中是有效的 ISO 8601 变体，但并非 java.time 默认解析器直接支持。异常信息中的 at index 23 正好指向时区偏移量的起始位置，表明解析器在此处遇到了无法识别的字符序列。
核心解决方案：自定义 DateTimeFormatter
解决此问题的关键是使用 DateTimeFormatter.ofPattern() 方法自定义一个解析模式，明确指定如何识别字符串中的各个日期时间部分，特别是时区偏移量。
选择合适的模式符号解析时区偏移量
DateTimeFormatter 提供了多种模式符号来处理时区偏移量：
立即学习“Java免费学习笔记（深入）”；
- Z, ZZ, ZZZ: 用于解析 +0000 格式，通常用于旧版 java.util.TimeZone 兼容。
- X: 表示一个字母的时区偏移量，例如 Z。
- XX: 表示 +HHMM 格式，例如 +0100。
- XXX: 表示 +HH:MM 格式，例如 +01:00。
- x: 表示一个字母的时区偏移量，例如 Z。
- xx: 表示 +HHMM 格式，例如 +0100。
- xxx: 表示 +HH:MM 格式，例如 +01:00。
对于我们遇到的 +0100 这种不带冒号的四位数字时区偏移量，最合适的模式符号是 xx (或 XX)。
构建解析器并解析
结合日期时间的其他部分，我们可以构建一个完整的 DateTimeFormatter 模式字符串："uuuu-MM-dd'T'HH:mm:ss.SSSxx"。
- uuuu: 年份（四位数）。
- MM: 月份（两位数）。
- dd: 日期（两位数）。
- 'T': 字面量字符 'T'，需要用单引号括起来。
- HH: 小时（0-23，两位数）。
- mm: 分钟（两位数）。
- ss: 秒（两位数）。
- .SSS: 毫秒（三位数）。
- xx: 时区偏移量，如 +0100。
使用这个自定义的 DateTimeFormatter 来解析字符串，并将其解析为 java.time.OffsetDateTime 对象。OffsetDateTime 是一个带有 UTC 偏移量的日期时间对象，非常适合处理这类带有明确偏移量的时间戳。
示例代码
以下是完整的 Java 代码示例，演示如何正确解析此类时间戳，并将其转换为 Instant：
import java.time.Instant;
import java.time.OffsetDateTime;
import java.time.format.DateTimeFormatter;
import java.time.format.DateTimeParseException;
public class TimestampParser {
public static void main(String[] args) {
String timestampString = "2022-12-12T09:51:09.681+0100";
try {
// 1. 定义自定义 DateTimeFormatter
// uuuu-MM-dd'T'HH:mm:ss.SSS 用于日期时间部分
// xx 用于解析 +HHMM 格式的时区偏移量
DateTimeFormatter parser = DateTimeFormatter.ofPattern("uuuu-MM-dd'T'HH:mm:ss.SSSxx");
// 2. 使用自定义解析器解析字符串到 OffsetDateTime
OffsetDateTime odt = OffsetDateTime.parse(timestampString, parser);
System.out.println("解析后的 OffsetDateTime: " + odt);
// 3. 如果需要，将 OffsetDateTime 转换为 Instant
// Instant 表示时间线上的一个瞬时点，始终是 UTC 时间
Instant instant = odt.toInstant();
System.out.println("转换为 Instant (UTC): " + instant);
} catch (DateTimeParseException e) {
System.err.println("解析时间戳失败: " + e.getMessage());
e.printStackTrace();
}
}
}输出结果：
解析后的 OffsetDateTime: 2022-12-12T09:51:09.681+01:00 转换为 Instant (UTC): 2022-12-12T08:51:09.681Z
从输出可以看出，OffsetDateTime 保留了原始的日期时间信息和时区偏移量。当转换为 Instant 时，时间被调整为 UTC（即 +01:00 偏移量的时间 09:51 对应 UTC 时间 08:51），并以 Z 结尾表示 UTC。
注意事项与最佳实践
-
选择合适的日期时间类型:
- Instant: 表示时间线上的一个瞬时点，不包含任何时区信息，始终是 UTC 时间。适用于存储和比较时间。
- OffsetDateTime: 包含日期、时间以及与 UTC 的偏移量。适用于需要保留原始偏移量信息的情况。
- ZonedDateTime: 包含日期、时间以及完整的时区信息（例如 America/New_York），适用于处理特定地理区域的时间。
- LocalDateTime: 只有日期和时间，不包含任何时区或偏移量信息。适用于不关心时区的本地日期时间。 在选择解析目标类型时，应根据实际需求来决定。对于带偏移量的时间戳，OffsetDateTime 通常是首选。
理解 DateTimeFormatter 模式符号: 熟悉 java.time.format.DateTimeFormatter 中所有模式符号的含义及其对大小写的敏感性至关重要。例如，HH 表示 0-23 小时制，hh 表示 1-12 小时制，MM 表示月份，mm 表示分钟。错误的模式符号会导致解析失败或结果不准确。
错误处理: 在实际应用中，解析用户输入或外部系统提供的时间戳时，应始终使用 try-catch 块捕获 DateTimeParseException。这可以提高程序的健壮性。
ISO 8601 标准: java.time API 大力支持 ISO 8601 标准。尽管某些格式可能需要自定义 DateTimeFormatter，但了解 ISO 8601 的不同表示方法有助于更好地构建和理解日期时间字符串。
总结
在 Java java.time API 中解析带数字时区偏移量（如 +HHMM）的时间戳时，不能直接依赖 Instant.parse() 或 OffsetDateTime.parse() 的默认行为。通过自定义 DateTimeFormatter，并使用 xx 模式符号来精确匹配 +HHMM 格式的时区偏移量，可以有效地解决 DateTimeParseException。将字符串解析为 OffsetDateTime 是处理此类带偏移量时间戳的推荐方式，之后可以根据需要将其转换为 Instant 或其他日期时间类型。掌握 DateTimeFormatter 的灵活运用是高效处理各种日期时间格式的关键。
