一、起源:两处隐形假设与四类线上事故
1.1 两处隐形假设
时间与编码这两类问题有共同的成因形态:代码在书写时依赖了没有写在代码里的假设,而这些假设在开发环境与生产环境、在不同主机之间、在不同进程之间并不一致。
假设一:默认时区。 只要调用 LocalDateTime.now()、new Date()、ZoneId.systemDefault(),代码就与运行环境的默认时区绑定。开发机上可能是 Asia/Shanghai,容器默认是 UTC,数据库实例配置为 +8:00,三方接口返回的是带偏移的字符串。四处的解释规则不同,同一个瞬间在不同位置被记录成不同数值。
假设二:默认字符集。 new String(bytes)、new FileReader(file)、new InputStreamReader(in)、FileWriter、PrintStream 在未显式指定字符集时使用 JVM 的默认字符集,而默认字符集又取决于系统属性 file.encoding 与 sun.jnu.encoding,进而取决于主机的区域设置。JDK 18 起 file.encoding 的默认值固定为 UTF-8,但更早的版本在容器中常取到 ANSI_X3.4-1968(ASCII),此时中文字符会被替换为 ?。
1.2 机器语义与人的语义不同
机器记录的是时刻:一条单调增长或可回拨的计数,没有"今天""上午"的概念。人描述的是日历时间:本地日期、本地时间、星期、节假日、自然月。两者之间存在三层映射:
本地时间(人读的) ←时区规则→ 偏移量(+08:00) ←线性偏移→ 时刻(UTC 时间轴)
↑ ↑
夏令时、政策变更 不含规则的固定偏移
三层中任何一层被省略或被替换,都会产生偏差。时间的复杂度不在于算术,而在于第一层的规则会变化:时区边界调整、夏令时启用或废止、偏移量变更,都由各地区的法规决定,并以时区数据库的形式独立发布。
编码同样存在两层映射:字符(抽象符号)与码点(编号)是一层,码点与字节序列(编码)是另一层。写代码时把"字符串"当作字符序列处理,运行时它实际是字节序列或 UTF-16 代码单元序列,长度、截断、比较的语义都建立在后两者之上。
1.3 为什么测试难以覆盖
| 原因 | 说明 |
|---|---|
| 环境一致性 | 开发机、CI、容器、数据库的时区与字符集往往被配置为同一套,掩盖了差异 |
| 时间相关性 | 只在跨日、跨月、跨年、夏令时切换当天等特定时刻暴露 |
| 数据相关性 | 只有包含四字节字符(emoji、生僻字)、增补字符、超长字符串的数据才会触发 |
| 路径相关性 | 只有走某个特定接口、某条数据链路(导出文件、消息队列、三方对接)才经过出问题的编解码步骤 |
| 时钟相关性 | 依赖时钟回拨、NTP 校准等外部事件,无法在测试中构造 |
1.4 四类典型事故形态
| 事故形态 | 现象 | 常见根因方向 |
|---|---|---|
| 跨时区时间偏移 | 同一笔记录在列表页与详情页相差整数小时;报表自然日统计错位;定时任务在预期之外的时间触发 | 写入与读取使用了不同的时区假设;TIMESTAMP 列与会话时区不匹配;默认值由数据库服务器生成而业务时间由应用生成 |
| 乱码 | 中文显示为 ???、锟斤拷、ä½ 等;JSON 解析报首字符非法;导出文件在 Excel 中打开乱码 | 编码与解码字符集不一致;字节流被当作字符处理;连接、表、列、终端默认字符集不统一 |
| 夏令时重复与跳过 | 任务在切换当天执行两次或一次都不执行;某一小时内的数据出现空缺或重复;时间戳相同的两条记录顺序颠倒 | 本地时间在切换当天存在重复区间与不存在区间;任务按本地时间而非 UTC 调度 |
| 排序错乱 | 中文列表顺序不符合预期;数据库排序结果与应用内排序结果不一致;大小写敏感判断前后不一致 | 应用层使用 String.compareTo(UTF-16 代码单元序)而数据库使用排序规则;两侧的排序规则或可空语义不同 |
二、原理
2.1 时间的语义层次
2.1.1 时刻、本地时间、偏移量与区域
四个概念构成了 java.time 的类型划分基础:
| 概念 | 含义 | 是否可定位到时间轴上的唯一瞬间 |
|---|---|---|
| 时刻(Instant) | 时间轴上的一个点,以 Unix 纪元(1970-01-01T00:00:00Z)起的秒与纳秒表示 | 是 |
| 本地日期时间(LocalDateTime) | 日历字段的组合:年、月、日、时、分、秒、纳秒 | 否,缺少与时间轴的对应关系 |
| 偏移量(Offset) | 相对 UTC 的固定差值,如 +08:00 | 结合本地时间后可定位 |
| 区域(Zone) | 偏移量的规则集合,包含历史与未来的偏移变更、夏令时切换点 | 结合本地时间后可定位,且随规则数据库更新而可能变化 |
关键区别在于偏移量与区域:+08:00 是一个数值,Asia/Shanghai 是一套规则。Asia/Shanghai 在东八区,历史上曾实行夏令时(1986 至 1991 年),未来也可能因政策调整而改变偏移。因此**"某个本地时间对应哪个时刻"只对区域成立,对偏移量只是查表结果**。
LocalDateTime 的常见误用是把它当作时刻参与存储与排序。它的字段本身不含时区信息,同一份 2026-09-23T12:00 在东京与上海对应两个不同的瞬间。
2.1.2 UTC、GMT 与偏移的差别
| 名称 | 性质 | 说明 |
|---|---|---|
| UTC | 时间标准 | 基于原子钟的国际协调时间,是当前时间戳的参考基准 |
| GMT | 时区名称 | 英国格林尼治的民用时区,实务中与 UTC 数值相同,但历史上为基于天文观测的时标 |
| 偏移量 | 相对量 | +08:00 表示比 UTC 快 8 小时,可以是非整小时(如 +05:30、+08:45) |
编码与传输中使用 Z 表示零偏移(2026-09-23T04:00:00Z)。Z 与 +00:00 语义相同,选择哪一种属于约定问题,重要的是同一系统中保持一致。
2.1.3 时区规则的来源与更新
时区规则来自 IANA 时区数据库(tzdb),由各地区法规变更驱动更新。JDK 内置一份 tzdb 快照,随版本发布更新。由此产生三类工程问题:
- JDK 版本决定规则新旧。 使用较旧 JDK 的实例,其规则快照可能不包含最新变更。地区废止或启用夏令时后,旧版本仍按旧规则换算,产生固定小时数的偏差。
- 主机与 JVM 的规则来源可能不同。 JVM 默认使用内置 tzdb,不读取主机
/usr/share/zoneinfo(除非显式配置),因此升级主机时区数据不等于 JVM 规则被更新。 - 规则的适用范围包含历史。 历史规则变更会影响对历史数据的换算。例如按当前规则去解释 1990 年上海的本地时间,会得到错误结果。
处理方式是把规则更新纳入变更管理:升级 JDK 时核对 tzdb 版本,需要在不升级 JDK 的前提下更新规则时使用 JDK 提供的时区数据更新工具。
2.2 java.time 的设计
2.2.1 不可变与线程安全
java.time 包中的核心类型均不可变:所有"修改"方法(plusDays、withYear、withZoneSameInstant)返回新实例,原对象不变。这带来两个直接结果:
- 线程安全。 实例可以自由共享、缓存、作为静态常量,不需要同步。
- 表达式语义清晰。 运算结果必须被接收,避免了"调用方法但忘记赋值"导致的静默失效——旧 API 的
Calendar.add()是原地修改,忘记接收返回值不报错但语义不同。
DateTimeFormatter 同样是不可变的,可以定义为静态常量并跨线程复用,这与旧 API 的 SimpleDateFormat 形成对比。java.time 常用类型的 API 清单见 java 完整手册 的新日期时间 API 一节,此处不重复罗列。
2.2.2 四类时间类型的语义与选择
// 时刻:时间轴上的点,无时区,适合存储与传输
Instant instant = Instant.now();
Instant parsed = Instant.parse("2026-09-23T04:00:00Z");
// 本地日期时间:无时区,适合表示墙上钟表读到的值或业务日期时间
LocalDateTime local = LocalDateTime.of(2026, 9, 23, 12, 0);
LocalDate date = LocalDate.of(2026, 9, 23);
// 带区域的日期时间:本地时间 + 区域规则,适合需要按某地日历理解与展示
ZonedDateTime zoned = ZonedDateTime.of(local, ZoneId.of("Asia/Shanghai"));
// 带偏移的日期时间:本地时间 + 固定偏移,适合只在传输层保留偏移信息
OffsetDateTime offset = local.atOffset(ZoneOffset.ofHours(8));
| 类型 | 含时区规则 | 可定位到瞬间 | 典型用途 |
|---|---|---|---|
Instant | 否(固定为 UTC) | 是 | 存储、传输、耗时计算、事件时间戳 |
OffsetDateTime | 仅含固定偏移 | 是 | 需要保留来源偏移的传输与日志 |
ZonedDateTime | 含完整规则 | 是 | 需要按地区日历做加减、判断是否处于夏令时的场景 |
LocalDateTime | 不含 | 否 | 本地时间字段、与数据库无时区列对应的映射 |
LocalDate / LocalTime | 不含 | 否 | 业务日期(生日、账单日)、营业时间 |
选择的原则是按语义而非按便利性:凡是描述"某个瞬间发生了什么",使用 Instant;凡是描述"某个地区的人看到的日期与钟点",使用 LocalDate、LocalTime 或 LocalDateTime;只有在明确需要区域规则参与运算时使用 ZonedDateTime,因为它携带的规则会在不同 JDK 版本下产生不同结果。
需要区分两种"未来时间":
- 固定瞬间,例如"活动在 2026-12-01T00:00:00Z 结束",使用
Instant存储,不受规则变更影响。 - 固定墙钟,例如"每天 09:00 触发",语义绑定在某个区域上,需要同时保存区域标识与本地时间,且必须接受规则变更带来的执行时刻变化。
2.2.3 Duration 与 Period
两者都表示"一段长度",但计量基准不同:
| 类型 | 计量基准 | 组成 | 跨夏令时的行为 |
|---|---|---|---|
Duration | 时间轴(秒、纳秒) | 秒数 + 纳秒数 | 精确,与规则无关 |
Period | 日历字段(年月日) | 年、月、日 | 按日历字段推进,实际经过的时间可能相差一小时 |
Duration d = Duration.between(startInstant, endInstant); // 精确经过的时间
Period p = Period.between(startDate, endDate); // 日历上的年月日差
LocalDate d1 = LocalDate.of(2026, 3, 1);
LocalDate d2 = d1.plusDays(1); // 加一天:日历语义
Duration d3 = Duration.ofDays(1); // 24 小时:时间轴语义
在夏令时切换日,"加一个日历日"与"加 24 小时"的结果可能相差 23 或 25 小时。涉及计费、保质期、有效期时,需要明确使用哪一种语义并写入文档。Duration 与 Period 之间不存在通用换算,因为月的长度不固定。
2.2.4 Clock 抽象与时区注入
Clock 是 java.time 提供的时钟抽象,Instant.now(clock)、LocalDate.now(clock) 都接受它。默认实现 Clock.systemUTC() 读取系统时钟,测试时可用固定时钟替换:
// 生产代码依赖注入的 Clock,而不是直接调用 Instant.now()
public class OrderService {
private final Clock clock;
private final ZoneId zone;
public OrderService(Clock clock, ZoneId zone) {
this.clock = clock;
this.zone = zone;
}
public Instant createdAt() {
return Instant.now(clock);
}
public LocalDate businessDate() {
return LocalDate.now(clock.withZone(zone));
}
}
// 测试:固定时刻与固定区域,结果可重现
Clock fixed = Clock.fixed(Instant.parse("2026-01-01T00:00:00Z"), ZoneOffset.UTC);
OrderService svc = new OrderService(fixed, ZoneId.of("Asia/Shanghai"));
Clock 还提供了三个常用派生实现:
| 方法 | 用途 |
|---|---|
Clock.fixed(instant, zone) | 时间停止在某一刻,用于断言结果 |
Clock.offset(base, duration) | 在基准时钟上偏移一个固定量,用于构造边界场景 |
Clock.tick(base, duration) | 降低精度,例如截断到毫秒或秒,用于对齐测试断言 |
时区同样需要注入:业务代码中出现 ZoneId.systemDefault() 意味着行为随部署环境变化,应改为从配置读取并注入的显式区域。
2.3 旧 API 的问题与迁移
java.util.Date 与 java.util.Calendar 的问题集中在三点:
- 可变形。
Date.setTime()、Calendar.add()、Calendar.set()都是原地修改。对象被当作值传递(放入集合、作为方法返回值)后,任意持有者都能改变其内容,等价于一个隐式的全局契约破裂点。 - 字段语义反直觉。
Calendar.MONTH从 0 开始(0 表示一月),Calendar.DAY_OF_WEEK从 1 开始且周日为 1,Date.getYear()返回"年份减 1900"。这类偏移直接导致逐月统计、星期判断的边界错误。 - 线程不安全。
Calendar的内部状态在调用过程中被改写;SimpleDateFormat内部持有Calendar并在format与parse中读写它,多线程共享同一实例会出现结果错乱,或抛出NumberFormatException、ArrayIndexOutOfBoundsException。这一缺陷在实测中表现为"偶发解析失败",与输入数据无明显相关性。
// 错误:静态共享,高并发下结果错乱或抛异常
private static final SimpleDateFormat SDF = new SimpleDateFormat("yyyy-MM-dd HH:mm:ss");
// 正确之一:使用不可变的 DateTimeFormatter
private static final DateTimeFormatter FMT =
DateTimeFormatter.ofPattern("uuuu-MM-dd HH:mm:ss");
// 正确之二:确实需要 SimpleDateFormat 时,按线程隔离
private static final ThreadLocal<SimpleDateFormat> TL =
ThreadLocal.withInitial(() -> new SimpleDateFormat("yyyy-MM-dd HH:mm:ss"));
新旧互转的入口与注意点:
| 转换方向 | 方式 | 注意点 |
|---|---|---|
Instant → Date | Date.from(instant) | 精度按毫秒取舍,见 2.5 |
Date → Instant | date.toInstant() | —— |
Instant → LocalDateTime | LocalDateTime.ofInstant(instant, zone) | 必须显式给区域 |
LocalDateTime → Instant | local.atZone(zone).toInstant() | 夏令时重叠与非存在区间的处理见 2.4 |
ZonedDateTime ↔ GregorianCalendar | GregorianCalendar.from(zdt) 与 cal.toZonedDateTime() | 保留时区信息 |
java.sql.Timestamp → LocalDateTime | ts.toLocalDateTime() | 丢弃时区信息,仅当列本身无时区语义时使用 |
迁移的常见策略是新代码全部使用 java.time,与既有 Date、Calendar 的边界集中在数据访问层与外部接口层,转换点使用上述显式方法,避免使用依赖默认时区的重载与已废弃的构造器。
2.4 夏令时
夏令时的规则是在切换日把当地时间整体前移或后移一小时,由此产生两个特殊区间。
不存在的本地时间(春季前移)。 本地时间从 02:00 直接跳到 03:00,01:00 至 01:59 的区间不存在。构造与解析都会遇到歧义:LocalDateTime 可以表示这个值,但它在时间轴上没有对应点,转换为 ZonedDateTime 时会被前移到偏移变更后的时刻。
ZoneId zone = ZoneId.of("America/New_York");
LocalDateTime gap = LocalDateTime.of(2026, 3, 8, 2, 30); // 该本地时间不存在
ZonedDateTime zdt = gap.atZone(zone); // 前移到 03:30
ZoneOffsetTransition t = zone.getRules().getTransition(gap);
boolean isGap = t != null && t.isGap(); // 判断是否落在空洞区间
重复的本地时间(秋季后移)。 本地时间从 02:00 回退到 01:00,01:00 至 01:59 出现两次,对应两个不同的偏移量。
ZoneId zone = ZoneId.of("America/New_York");
LocalDateTime overlap = LocalDateTime.of(2026, 11, 1, 1, 30); // 该本地时间出现两次
ZonedDateTime earlier = overlap.atZone(zone); // 默认取较早的偏移
ZonedDateTime later = earlier.withLaterOffsetAtOverlap(); // 显式取较晚的偏移
List<ZoneOffset> offsets = zone.getRules().getValidOffsets(overlap); // 长度为 2
处理方式分三个层面:
- 消歧。 对重叠区间必须显式选择偏移(
withEarlierOffsetAtOverlap或withLaterOffsetAtOverlap),或改用Instant、OffsetDateTime存储以消除歧义。默认行为在多数实现中取较早偏移,但不能依赖默认值表达业务意图。 - 调度。 按本地时间调度的定时任务在切换日会重复执行(秋季)或跳过(春季)。作为缓解,任务应按 UTC 调度或在任务内部按 UTC 判断是否已执行,并把执行记录写入带时区的时间戳用于去重。任务自身的时区执行环境需要核对:cron 与 systemd 单元执行环境中的
TZ、LANG等变量可能与登录会话不同,cron 调度的任务不加载登录环境的配置。 - 规则变更。 已存储的"本地时间 + 区域"在规则变更后可能对应到不同时刻。对历史事件应以
Instant为准;对未来的墙钟语义时间,需要在使用时重新按最新规则换算。
中国自 1991 年后不再实行夏令时,但跨境业务、云主机位于其他区域、或数据来自其他区域系统时,仍需按上述规则处理,不能假设所有时区都没有夏令时。
2.5 精度与时钟
2.5.1 精度层次
| 层次 | 精度 | 说明 |
|---|---|---|
| 秒 | 1 s | 部分旧表结构(无分数秒的 DATETIME)只保留到秒,且会做四舍五入 |
| 毫秒 | 10⁻³ s | System.currentTimeMillis()、JavaScript Date、多数 HTTP 接口 |
| 微秒 | 10⁻⁶ s | MySQL DATETIME(6) 与 PostgreSQL timestamp 的实际存储精度、Instant.now() 在多数平台的可用精度 |
| 纳秒 | 10⁻⁹ s | Instant 的内部表示与 System.nanoTime(),受硬件与操作系统实际分辨率限制 |
精度损失出现在每一层转换处,需要逐层核对:
Instant转 Java 毫秒时间戳(toEpochMilli())会截断亚毫秒部分。- 写入无分数秒的数据库列会丢失毫秒,且可能被四舍五入而非截断,导致写入值比预期大 1 秒。
- 出库后转回
Instant得到的值与原值不等,equals比较失败。时间戳字段的比较应基于截断后的精度,或统一在列精度上做截断后再比较。
2.5.2 系统时钟与单调时钟
Java 提供两个独立的时钟读取入口,语义完全不同:
| 入口 | 类型 | 特性 | 用途 |
|---|---|---|---|
System.currentTimeMillis() | 墙钟(wall clock) | 可被 NTP 校准、手动修改、虚拟机暂停调整,会向前或向后跳变 | 记录事件发生时刻 |
System.nanoTime() | 单调时钟(monotonic clock) | 只保证单调递增,起点任意,只在本 JVM 内可比较 | 测量耗时、实现超时 |
// 正确的耗时测量:单调时钟
long startNanos = System.nanoTime();
doWork();
long elapsedMillis = TimeUnit.NANOSECONDS.toMillis(System.nanoTime() - startNanos);
// 错误做法:墙钟差值,时间回拨时得到负数或错误的小值
long start = System.currentTimeMillis();
doWork();
long elapsed = System.currentTimeMillis() - start;
System.nanoTime() 的值不能用于日志、不能跨进程比较、不能持久化:不同 JVM 的起点不同,同一 JVM 重启后也不连续。
java.util.concurrent 中的超时实现(Object.wait(timeout)、Thread.sleep、Lock.tryLock(timeout)、Future.get(timeout)、CountDownLatch.await(timeout))基于单调时钟,因此不受系统时间调整影响。自实现的超时逻辑如果基于 System.currentTimeMillis() 计算截止时刻,则会出现两类异常:
- 时间向前跳变(NTP 校准或手动前调) 导致截止时刻提前到达,出现尚未超时就抛出超时异常的情况。
- 时间向后回拨 导致剩余时间被拉长,请求长时间挂起而不超时,连接与线程被占用。
时间回拨还会影响:以时间戳为前缀或组成部分的 ID 生成(回拨时可能生成重复 ID)、按时间戳排序的事件流(新事件排到旧事件之前)、基于"最后更新时间"的增量同步(回拨后一段时间内的数据被漏掉)。以时间戳为组成部分的全局唯一 ID 对时钟的依赖与应对方式见 分库分表与全局唯一 ID。
2.5.3 时间同步的必要性
时间同步的必要性来自四处依赖:
- 证书校验。 TLS 证书有效期判断依赖本地时间,偏移过大会导致证书被判定为未生效或已过期。
- 集群认证。 Kerberos 等协议对时间偏差有硬性窗口(通常数分钟),超窗直接认证失败。
- 日志时间线。 多节点日志需要按时间合并,偏移过大会使因果顺序错乱。
- 分布式一致性。 租约、选举、分布式事务的时间戳比较都假设节点时间接近。
主机的同步状态与偏移量属于常规巡检项,检查命令与判读标准(偏移超过 0.5 秒需处置,时区需为业务约定值,跨时区系统需明确时间戳统一为 UTC)见 Linux 主机巡检与健康检查 的时间同步一节;对应的监控指标与告警阈值(偏移连续 10 分钟超过 0.5 秒告警)见 监控与告警。时间与编码在容器中的不一致问题见 云原生部署 的时区与编码不一致一节。
2.6 格式与解析
2.6.1 格式符
| 格式符 | 含义 | 常见误用 |
|---|---|---|
u / y | 年(u 为 proleptic year,y 为 era year) | 严格模式下 yyyy 因缺少纪元信息而报错,宜用 uuuu |
M / L | 月(数字形式 / 文本形式) | MM 与 M 的补零差异影响格式对齐 |
d | 日 | —— |
H / h | 时(24 小时制 / 12 小时制) | 混用导致上午下午判断错误 |
m / s | 分 / 秒 | —— |
S | 秒的小数部分(毫秒、微秒) | 位数与实际精度不匹配时产生截断或补零 |
X / Z / z / VV | 偏移 / 区域 | z 输出的是区域显示名,不稳定,传输应使用 XXX 或 VV |
DateTimeFormatter 提供了预定义的 ISO 常量(ISO_INSTANT、ISO_OFFSET_DATE_TIME、ISO_LOCAL_DATE_TIME 等),传输格式应优先使用这些常量,而不是自定义 pattern,以减少跨系统约定成本。
2.6.2 严格与宽松解析
解析行为的宽松程度由 ResolverStyle 控制,默认值为 SMART:
| 策略 | 行为 | 示例 |
|---|---|---|
SMART(默认) | 对明显越界的字段做合理调整 | 2026-02-30 被调整为 2026-02-28 |
LENIENT | 按溢出规则推进 | 2026-02-30 被调整为 2026-03-02 |
STRICT | 越界即失败 | 2026-02-30 抛出 DateTimeParseException |
DateTimeFormatter strict = DateTimeFormatter.ofPattern("uuuu-MM-dd")
.withResolverStyle(ResolverStyle.STRICT);
LocalDate d = LocalDate.parse("2026-02-30", strict); // 抛出 DateTimeParseException
宽松解析的风险在于错误输入被静默接受:上游传入的日期字段越界后不会报错,而是被挪到相邻月份,产生难以追溯的数据偏差。对来自外部系统的输入,应使用 STRICT 并在解析失败时返回明确的错误信息。
旧 API 的宽松度更高:SimpleDateFormat 默认 lenient=true,2026-02-30 会被解析为 2026-03-02。使用旧 API 解析外部输入时必须调用 setLenient(false)。
2.6.3 序列化中的形态
时间在序列化格式中的形态需要在对立的两组属性之间取舍:
| 形态 | 示例 | 优点 | 缺点 |
|---|---|---|---|
| 时间戳(epoch 毫秒或秒) | 1790000000000 | 无歧义、跨语言、体积小、便于比较与索引 | 不可读、无时区信息、精度固定为毫秒(秒级时间戳会截断毫秒) |
| ISO 8601 字符串(带偏移) | 2026-09-23T12:00:00+08:00 | 可读、自描述、精度可表达 | 需约定格式与精度,解析成本高,字符串比较不等于时间比较 |
ISO 8601 字符串(UTC,Z) | 2026-09-23T04:00:00Z | 可读且统一 | 展示层必须做一次时区转换 |
| 不带偏移的本地时间字符串 | 2026-09-23T12:00:00 | 适合业务日期语义 | 作为时刻存储时会产生歧义,是最常见的错误来源 |
序列化层的配置决定了实际输出。Jackson 在处理 java.time 类型时默认启用 WRITE_DATES_AS_TIMESTAMPS,会把 Instant 输出为小数时间戳、把 LocalDateTime 输出为数值数组,需显式关闭后才输出 ISO 字符串。序列化格式的选型与版本兼容策略参见 序列化与反序列化 的技术对比与选型决策表。
2.6.4 区域化格式与用户展示
面向用户的展示与面向系统的传输是两件事。传输使用固定格式,展示使用区域化格式:
// 展示:按区域与格式风格本地化
DateTimeFormatter display = DateTimeFormatter
.ofLocalizedDateTime(FormatStyle.MEDIUM, FormatStyle.SHORT)
.withLocale(Locale.SIMPLIFIED_CHINESE);
// 展示时先把时刻转到用户所在区域
String text = display.format(instant.atZone(ZoneId.of("Asia/Shanghai")));
展示层的区域应来自用户设置而非部署环境。Locale.getDefault() 与 ZoneId.systemDefault() 在展示层使用是合理的(它们代表当前运行环境的默认值),但需要显式知晓这一依赖。
2.7 字符集与编码
2.7.1 字符、码点与编码
| 概念 | 定义 | 示例 |
|---|---|---|
| 字符(Character) | 抽象符号 | 汉字"中"、字母 A、表情符号 |
| 码点(Code Point) | 字符在 Unicode 中的编号 | 中 = U+4E2D,A = U+0041,😀 = U+1F600 |
| 代码单元(Code Unit) | 编码方案的最小存储单位 | UTF-16 中为 16 位,UTF-8 中为 8 位 |
| 编码(Encoding) | 码点到字节序列的映射 | UTF-8、GBK、UTF-16 |
Java 的 char 是一个 UTF-16 代码单元,String 是 UTF-16 代码单元序列,相关类型定义见 数据类型系统。这一事实带来三个后果:
String.length()返回代码单元数,不等于字符数。- 基本多文种平面(BMP,U+0000 至 U+FFFF)之外的字符(增补字符)占两个代码单元。
- 按代码单元做截断、反转、下标访问,都可能切开一个字符。
String emoji = "😀"; // U+1F600,UTF-16 表示为 "\uD83D\uDE00"
int codeUnits = emoji.length(); // 2
int codePoints = emoji.codePointCount(0, emoji.length()); // 1
String half = emoji.substring(0, 1); // 只取高位代理,得到非法序列
int next = emoji.offsetByCodePoints(0, 1); // 按码点推进,取到完整字符
两个代码单元中只有高位或只有低位时称为孤立代理(unpaired surrogate)。孤立代理不是合法字符,写出时会被替换为 ? 或替换字符,是"字符串长度与预期不符""末尾出现方块字符"这类问题的直接原因。
2.7.2 常见字符集对比
| 字符集 | 编码单元 | 变长范围 | 表示中文 | 表示增补字符 | 与 ASCII 兼容 |
|---|---|---|---|---|---|
| ASCII | 7 位 | 固定单字节 | 否 | 否 | 是 |
| ISO-8859-1(latin1) | 8 位 | 固定单字节 | 否 | 否 | 是(8 位范围内的超集) |
| GBK | 8 位 | 1 至 2 字节 | 是(含 GB2312 全部) | 否 | 是(单字节部分) |
| UTF-8 | 8 位 | 1 至 4 字节 | 是 | 是 | 是(单字节部分完全一致) |
| UTF-16 | 16 位 | 2 或 4 字节 | 是 | 是 | 否(需字节序标记或约定) |
三处需要特别注意:
- GBK 是有限集合。 它覆盖常用汉字但无法表示全部 Unicode 字符。把
😀编码为 GBK 时,Java 的getBytes会替换为?(0x3F),数据库写入则会报Incorrect string value或按sql_mode截断。 - UTF-8 的字节数与字符数不成正比。 一个汉字 3 字节,增补字符 4 字节,ASCII 1 字节。数据库列长度、接口字段长度限制、消息体积估算都建立在字节数上。
- UTF-16 需要字节序信息。 字节序标记(BOM,Byte Order Mark,码点 U+FEFF)用于区分 UTF-16LE 与 UTF-16BE。UTF-8 有一个不必须的 BOM(字节序列
EF BB BF),部分编辑器会写出它。
2.7.3 BOM 与字节序
BOM 在文件传输中的实际影响是隐蔽的:
- 以 UTF-8 读取的文件首部带
\uFEFF,内容看起来正常,但第一个字段带上不可见字符。 - JSON 解析失败并报首字符非法;CSV 表头与预期字段名不匹配;YAML 解析报首行非法。
- 以
text/csv导出的文件在部分表格软件中打开乱码,需要在文件首部写入 BOM 才能被识别为 UTF-8。
Java 的 InputStreamReader 在指定 UTF-8 时不会自动剥离 BOM。处理方式是在读取首字符时判断并跳过:
private static final char BOM = '\uFEFF';
String normalize(String firstLine) {
return firstLine.isEmpty() || firstLine.charAt(0) != BOM
? firstLine
: firstLine.substring(1);
}
解析外部文件(CSV、配置文件、导入数据)时,把 BOM 剥离作为固定步骤。
2.7.4 长度与截断陷阱
按字节截断。 需要限制字段字节数(数据库列长度、消息体积、短信长度)时,按字节切分 UTF-8 序列会产生非法序列,解码得到替换字符 U+FFFD,或抛 MalformedInputException。
// 错误:按字节数组直接切分,可能切断多字节序列
byte[] bytes = text.getBytes(StandardCharsets.UTF_8);
byte[] head = Arrays.copyOfRange(bytes, 0, limit); // 末尾可能是半个字符
// 正确:按码点累加字节数,保证不切断字符
static String truncateByUtf8Bytes(String s, int maxBytes) {
int bytes = 0;
int end = 0;
for (int i = 0; i < s.length(); ) {
int cp = s.codePointAt(i);
int len = cp < 0x80 ? 1 : cp < 0x800 ? 2 : cp < 0x10000 ? 3 : 4;
if (bytes + len > maxBytes) {
break;
}
bytes += len;
i += Character.charCount(cp);
end = i;
}
return s.substring(0, end);
}
按字符截断。 使用 substring 做摘要或预览时,下标是代码单元数,可能切开增补字符。需要按下标截取时使用 offsetByCodePoints。
长度校验。 校验规则需要与列定义一致:数据库列的上限通常是字节数(VARCHAR(N) 在 utf8mb4 下的行长度上限按字节计),而 String.length() 是代码单元数。仅校验字符数会在含多字节字符的输入上越过列上限。
2.7.5 编码转换的正确写法
// 编码:显式指定字符集,不使用平台默认值
byte[] bytes = text.getBytes(StandardCharsets.UTF_8);
// 解码:同样显式指定
String back = new String(bytes, StandardCharsets.UTF_8);
// 严格解码:遇到非法字节立即失败,而不是静默替换
CharsetDecoder decoder = StandardCharsets.UTF_8.newDecoder()
.onMalformedInput(CodingErrorAction.REPORT)
.onUnmappableCharacter(CodingErrorAction.REPORT);
CharBuffer buffer = decoder.decode(ByteBuffer.wrap(bytes));
// 错误示例:把 UTF-8 字节按 GBK 解读,得到的是乱码而不是等价的字符串
String wrong = new String(bytes, Charset.forName("GBK"));
需要强调的一点:不存在"把 UTF-8 字节直接转成 GBK 字节"的字节级操作。字符集转换必须经过"字节 → 解码 → 字符 → 编码 → 字节"的完整路径,中间必须经过字符层。任何绕过字符层的字节变换等同于按错误规则解读数据。
2.8 乱码的成因分类
乱码的形态由"用哪一种规则编码、又用哪一种规则解码"的组合决定。按成因分为五类:
| 类别 | 成因 | 典型表现 |
|---|---|---|
| 编解码不一致 | 以 A 编码写入、以 B 解码读取 | UTF-8 字节按 latin1 解读得到 测试;按 GBK 解读得到生僻字混杂的长串 |
| 字节流被按字符处理 | 用 new String(bytes) 与 getBytes() 做中转而未指定字符集,或在字节层做转换 | 表现为"多一次转换就多一层乱码",同一数据不同环节结果不同 |
| 链路默认值不统一 | 客户端、连接、表、列的字符集声明不同 | 写入成功但读出错字;关联查询报 Illegal mix of collations;写入报 Incorrect string value |
| 字符集表达能力不足 | 目标字符集无法表示输入字符 | 特定字符统一变成 ?(GBK 无法表示 emoji)或写入失败 |
| 数据类型被误判 | 压缩、加密、序列化后的二进制数据被当作文本编码或解码 | 解压失败、解析报错、内容全为替换字符 |
两类反复出现的具体形态:
- 替换字符链。 非法字节被解码为
U+FFFD(显示为�),若该字符再被编码为 GBK,可得到锟斤拷这类字样。字面内容只是表象,关键是字节序列在某一环节已被判定为非法,这一步转换不可逆。 - 双重编码。 UTF-8 字节被按 latin1 解码得到一组字符,再被按 UTF-8 编码写出,最终出现
ä½Â一类形态。双重编码可逆(按相反顺序操作即可还原),而替换字符链不可逆。
2.9 国际化与排序
2.9.1 区域对格式化与大小写的影响
区域(Locale)影响三类操作:日期时间格式、数字与货币格式、文本大小写与排序。大小写转换的经典坑是土耳其语:该区域中 i 的大写是 İ,I 的小写是 ı。
String s = "I";
s.toLowerCase(); // 使用默认区域,结果随环境变化
s.toLowerCase(Locale.ROOT); // 语言无关的转换,协议字段、键名、枚举值处理使用这一形式
s.toLowerCase(Locale.forLanguageTag("tr")); // 得到 "ı"
规则是:面向协议与内部的字符串处理使用 Locale.ROOT,面向用户展示的处理使用用户区域。
2.9.2 排序规则与比较器
Java 中可用的比较方式有三种,结果并不一致:
| 方式 | 依据 | 特点 |
|---|---|---|
String.compareTo | UTF-16 代码单元序 | 稳定、与语言无关;不等于字典序,中文按码点排列,大写字母排在小写之前 |
Collator | 语言相关的排序规则 | 接近目标语言的使用习惯,但结果依赖 JDK 中的排序规则数据版本 |
数据库 ORDER BY | 列的排序规则 | 与索引一致;与 Java 侧结果不一定相同 |
Collator collator = Collator.getInstance(Locale.SIMPLIFIED_CHINESE);
collator.setStrength(Collator.PRIMARY); // 忽略重音与大小写差异
List<String> sorted = new ArrayList<>(list);
sorted.sort(collator);
Collator 的强度决定"差异算不算差异":PRIMARY 忽略重音与大小写,SECONDARY 区分重音,TERTIARY(默认)区分大小写。去重、唯一性校验与排序需要选用同一强度,否则会出现"排序中视为相等、去重时视为不同"的不一致。
2.9.3 数据库与应用层排序不一致
数据库的排序规则同时决定了比较与排序行为,其与 Java 侧存在三处系统性差异:
| 差异点 | 数据库侧 | Java 侧 |
|---|---|---|
| 大小写敏感 | utf8mb4_general_ci、utf8mb4_0900_ai_ci 中的 ci 表示大小写不敏感,'a' = 'A' 为真 | String.equals 大小写敏感,需显式使用 equalsIgnoreCase |
| 尾空格处理 | 5.7 时代的 utf8mb4 排序规则为 PAD SPACE,比较时忽略尾部空格;8.0 的 utf8mb4_0900_ai_ci 为 NO PAD | String.equals 区分尾空格 |
| 重音与特殊字符 | general_ci 与 unicode_ci 的比较基准不同 | 默认不做归一化 |
由此产生的典型问题:唯一约束在数据库侧不允许、应用层校验通过(或相反);分页查询中数据库判定的"相同值"在应用去重时被当作不同值;升级 MySQL 版本后尾部空格的处理变化导致唯一约束判定结果改变。
字符集与排序规则的三层分布(服务端、连接层、列层)、不一致时的转换代价、统一推进方式与相关 SQL 见 MySQL 表结构变更与日常运维 的字符集与排序规则统一一节。
三、实现
3.1 时间处理实践
3.1.1 统一以 UTC 存储与传输
约定:存储与传输使用 UTC 时刻,展示与解释转换为目标区域。 具体落地为四条:
- 数据库连接显式设定时区(见 3.2),JVM 侧固定默认时区(
-Duser.timezone=UTC),避免依赖容器与服务端默认值。 - 事件时间字段一律存
Instant或对应的 UTC 表示,业务日期字段存LocalDate,两者不混用同一类型。 - 转换只发生在边界:入口(HTTP 请求、消息、文件、数据库读取)转成
Instant,出口(响应、展示、导出)转为目标区域。 - 转换点数量受控。业务代码内部只处理
Instant与LocalDate,不出现ZoneId.systemDefault()与无参now()。
public final class Times {
public static final ZoneId BUSINESS_ZONE = ZoneId.of("Asia/Shanghai");
// 入口:带偏移的字符串 → 时刻
public static Instant parse(String text) {
return OffsetDateTime.parse(text, DateTimeFormatter.ISO_OFFSET_DATE_TIME)
.toInstant();
}
// 出口:时刻 → 业务区域的带偏移字符串
public static String format(Instant instant) {
return DateTimeFormatter.ISO_OFFSET_DATE_TIME
.withZone(BUSINESS_ZONE)
.format(instant);
}
}
3.1.2 时间字段类型选择
| 业务语义 | Java 类型 | 数据库类型 | 说明 |
|---|---|---|---|
| 事件发生时刻 | Instant | TIMESTAMP、timestamptz 或 BIGINT(epoch 毫秒) | 需要排序、范围查询与比较 |
| 业务日期(生日、账单日、统计日) | LocalDate | DATE | 不带时区,不做时刻换算,否则跨时区会变日 |
| 本地钟点(营业时间、班次) | LocalTime | TIME | 与具体日期无关 |
| 定时生效的墙钟语义(每天 09:00) | LocalTime + ZoneId | TIME + 区域列 | 规则变更时执行时刻会随区域规则变化 |
| 需要保留来源偏移的时刻 | OffsetDateTime | TIMESTAMP + 偏移列,或字符串列 | 接口回传、审计日志 |
把业务日期当作时刻处理是最常见的日期错位来源:LocalDate.of(2026, 9, 23) 转为 UTC 时刻后,在西半球区域展示会变成 9 月 22 日。
3.1.3 耗时测量的正确写法
// 耗时(单调时钟,不受系统时间调整影响)
long start = System.nanoTime();
try {
doWork();
} finally {
long costMs = TimeUnit.NANOSECONDS.toMillis(System.nanoTime() - start);
log.info("doWork cost {} ms", costMs);
}
需要区分三种计时口径,并在监控中分别建立指标:
| 口径 | 实现 | 用途 |
|---|---|---|
| 耗时 | System.nanoTime() 差值 | 性能指标、超时判断 |
| 事件时刻 | Clock 与 Instant.now(clock) | 日志时间、数据时间戳 |
| 业务日历差 | Period.between、ChronoUnit.DAYS.between | 账期、天数、账龄 |
自实现超时时使用单调时钟的截止点,不使用 Instant.now() 或 System.currentTimeMillis():
long deadline = System.nanoTime() + TimeUnit.SECONDS.toNanos(3);
while (System.nanoTime() < deadline) {
if (ready()) {
return;
}
Thread.sleep(10);
}
throw new TimeoutException("等待就绪超时");
3.2 数据库与时间
3.2.1 字段类型的取舍
| 类型 | 是否携带时区语义 | 存储方式 | 注意点 |
|---|---|---|---|
MySQL DATETIME | 否 | 按写入的字面值存储 | 不随会话时区转换,适合存本地时间语义;无分数秒时丢弃毫秒并四舍五入 |
MySQL TIMESTAMP | 是(隐式为 UTC) | 写入时按会话 time_zone 转为 UTC 存储,读取时转回 | 取值范围受 32 位限制;行为受会话时区与 explicit_defaults_for_timestamp 影响 |
MySQL DATE | 否 | 年月日 | 适合业务日期 |
PostgreSQL timestamp | 否 | 按字面值 | 无时区语义 |
PostgreSQL timestamptz | 是 | 内部存 UTC,按会话时区显示 | 会话时区变化只影响显示与解释 |
BIGINT(epoch) | 是(约定为 UTC) | 整数 | 与数据库时区完全解耦,比较与索引直接,缺点是失去可读性与数据库端日期函数支持 |
VARCHAR 存 ISO 字符串 | 依约定 | 字符串 | 排序按字典序,仅在需要保留原始形态时使用 |
选择依据是该字段描述的是时刻还是本地时间。描述时刻时,TIMESTAMP(多数数据库中带时区语义的 timestamptz)与 BIGINT 均可;描述本地时间时使用 DATETIME、DATE、TIME,并且不参与任何时区换算。混合使用两种语义(同一个 DATETIME 列有时被当作 UTC、有时被当作本地时间)是无法通过配置修正的数据污染。
分数秒精度需要在建表时明确:MySQL 的 DATETIME(3)、DATETIME(6) 分别保留毫秒与微秒,默认(无括号)为秒级。
3.2.2 时区参数与连接参数
需要在四个位置保持一致:
# 1. 数据库服务端:默认为 UTC,避免依赖主机时区
# my.cnf
# default_time_zone = '+00:00'
# character-set-server = utf8mb4
# collation-server = utf8mb4_0900_ai_ci
# 2. 应用 JVM:固定默认时区与文件编码
# java -Duser.timezone=UTC -Dfile.encoding=UTF-8 -jar app.jar
# 3. 数据源连接串:显式声明会话时区与字符集
spring:
datasource:
url: jdbc:mysql://db:3306/app?connectionTimeZone=UTC&forceConnectionTimeZoneToSession=true&characterEncoding=UTF-8
hikari:
connection-init-sql: SET time_zone = '+00:00'
服务端的时区与字符集参数取值见 MySQL 服务配置。连接层的字符集变量(character_set_client、character_set_connection、character_set_results)与列层字符集的关系见 3.4。
JDBC 层还需注意两点:驱动读写 Timestamp 时的目标时区由连接的时区参数决定(connectionTimeZone,该参数在 8.0.23 之前名为 serverTimezone),与 JVM 默认时区无关;ResultSet.getTimestamp(String, Calendar) 会按传入的 Calendar 再做一次转换,与非 Calendar 版本取值不同。使用新 API 映射(getObject(col, Instant.class)、getObject(col, LocalDate.class))可减少这类隐式转换。
连接建立过程中的会话初始化(字符集、时区、隔离级别、会话变量)位于连接建立流程中,其位置与开销见 持久层 的连接建立过程一节。
高危 修改数据库实例或会话的时区参数(default_time_zone、SET GLOBAL time_zone、连接串中的时区参数)
- 影响范围:
TIMESTAMP列的读写解释全部随之改变,界面与报表上体现出固定小时数偏移;由CURRENT_TIMESTAMP生成的默认值与自动更新时间在切换窗口内与业务侧生成的时间语义不一致;不同实例配置不一致时,主从或分库之间的同一行数据显示不同。DATETIME列的存储值不随该参数变化,因此问题表现为"部分表偏移、部分表正常"。 - 回滚方式:恢复原参数并重启实例或恢复连接参数。已存储的
TIMESTAMP数据内部为 UTC,恢复参数后解释即恢复正确;但切换窗口内写入的、依赖CURRENT_TIMESTAMP的行需要按窗口起止时间单独核对。 - 前置要求:变更前统计
TIMESTAMP列清单与默认值使用位置,确认应用连接串未另行覆盖;变更需在业务低峰执行,并准备按时间窗口核对数据的比对 SQL。
3.2.3 默认值与自动更新
由数据库生成的默认值(DEFAULT CURRENT_TIMESTAMP、ON UPDATE CURRENT_TIMESTAMP)使用数据库服务器的时间与会话时区,由应用生成的时间使用应用主机的时钟与 JVM 时区。两者不一致时会出现"创建时间早于业务时间""更新时间落后于实际操作时间"这类难以解释的现象。
处理原则是确定唯一来源:
- 优先由应用生成时间戳并显式写入,数据库默认值仅作兜底,且值类型与语义与列定义一致。
- 保留数据库默认值时,把服务器时区与应用时区统一为 UTC,并对默认值所在列建立字段级的约定记录。
ON UPDATE CURRENT_TIMESTAMP会在所有更新语句中生效,包括不涉及业务字段的批量订正,导致更新时间被意外刷新。需要保留原始更新时间语义时,改用应用侧显式赋值。
3.2.4 时间范围查询与索引
时间范围查询的写法直接决定索引能否使用:
-- 可用索引:范围条件作用在列本身
SELECT id, order_no FROM orders
WHERE created_at >= '2026-09-01 00:00:00'
AND created_at < '2026-10-01 00:00:00';
-- 不可用索引:对列施加函数,索引的键序与函数结果无关
SELECT id FROM orders WHERE YEAR(created_at) = 2026;
-- 不可用索引:对列做运算或隐式类型转换
SELECT id FROM orders WHERE UNIX_TIMESTAMP(created_at) > 1790000000;
对应的规则与等价改写方式(含 YEAR(created_at) 的改写方案与函数索引的适用边界、隐式类型转换的影响)见 MySQL 索引与执行计划 的索引失效常见情形与函数索引两节。
范围条件使用左闭右开区间,而不是 BETWEEN:右端点若为当月最后一秒,会漏掉该秒内带毫秒的记录;使用 <= 与末秒边界同理。左闭右开同时避免了跨月统计中边界时刻被重复计入。
时间列上的范围条件会使其后的联合索引列失去定位能力,因此时间列在联合索引中的位置需要按"等值列在前、范围列在后"的原则确定,该规则同见上述索引文档的范围查询后列失效一节。
3.2.5 跨时区报表口径
报表的自然日与自然月必须绑定一个区域,并在需求与接口文档中写明。三种口径的做法与代价:
| 口径 | 实现 | 代价 |
|---|---|---|
| 按 UTC 自然日聚合 | 直接对 UTC 列做范围过滤与 GROUP BY | 与业务人员认知的自然日不一致,跨日时段的数据归属与预期不符 |
| 按业务区域聚合(数据库侧) | CONVERT_TZ(created_at, '+00:00', '+08:00') 后聚合 | 列上出现函数,无法使用索引;使用命名时区时需数据库已加载时区表,否则返回 NULL |
| 按业务区域聚合(应用侧) | 按区域计算 UTC 起止时刻,用范围条件查询后在应用内聚合 | 查询条件仍可用索引,聚合逻辑在代码中,需要保证与展示口径一致 |
推荐第三种:把"业务区域的自然日"换算成两个 UTC 瞬间,用左闭右开的范围条件查询,索引可用且口径显式。
高危 批量时间转换(对既有时间列做整体偏移,如一次性 UPDATE ... = CONVERT_TZ(...) 或 DATE_ADD)
- 影响范围:语句本身通常是全表更新,大事务会长时间持锁并放大复制延迟;缺少幂等保护时重复执行会造成二次偏移;偏移方向或时区参数判断错误会把正确数据改成错误数据,且无法从结果值反推原始值是否被改过。
- 回滚方式:执行前对目标列与主键做备份(临时表或数据快照),回滚通过备份恢复;只有在偏移量与执行窗口明确记录、且数据在窗口内未被再次写入时,才可用反向偏移回滚。
- 前置要求:明确受影响行数与判定条件,分批执行并记录每批的主键范围;执行前后各做一次抽样比对;确认复制延迟与磁盘余量可承受。
3.3 接口与前后端
3.3.1 传输格式约定
需要为每类时间字段固定唯一格式,并在接口文档中声明:
| 字段语义 | 推荐格式 | 示例 |
|---|---|---|
| 时刻 | ISO 8601 带偏移,或 UTC 时间戳(毫秒) | 2026-09-23T12:00:00+08:00、2026-09-23T04:00:00Z、1790000000000 |
| 业务日期 | yyyy-MM-dd(不带时间与偏移) | 2026-09-23 |
| 本地时间 | HH:mm:ss | 09:00:00 |
禁止在同一系统中混用秒级与毫秒级时间戳、混用带偏移与不带偏移的字符串。混用的后果是数值相差 1000 倍或解释相差整数小时,且往往在跨系统对接时才发现。
Java 侧的序列化配置需要显式设定,避免依赖框架默认值:
spring:
jackson:
serialization:
write-dates-as-timestamps: false # 关闭后 java.time 输出 ISO 字符串
date-format: "yyyy-MM-dd'T'HH:mm:ssXXX"
time-zone: UTC
write-dates-as-timestamps 为真时,Instant 输出为小数时间戳、LocalDateTime 输出为数值数组,两者都不符合前表的约定。
3.3.2 前端解析与展示的责任边界
责任划分的原则是:后端负责时刻的准确性与格式的稳定性,前端负责本地化展示。
前端解析的已知边界:
new Date("2026-09-23T12:00:00")这类不带偏移的字符串,会被按本地时间解释,不同时区的浏览器得到不同时刻。- 带偏移或
Z的字符串(2026-09-23T12:00:00+08:00、2026-09-23T04:00:00Z)解析结果与浏览器时区无关,是可预期的。 - 非 ISO 格式(
2026-09-23 12:00:00)的解析行为由具体实现决定,不应作为接口约定。
由此得到的约定是:时刻字段一律传带偏移或 Z 的 ISO 8601 字符串;前端在展示层做本地化,不把本地格式化后的字符串回传给后端。日期字段(yyyy-MM-dd)不在前端做时区转换,直接作为字符串展示,避免跨时区变日。
3.3.3 跨系统对接与兼容演进
对接场景需要额外约定三点:对方系统使用的时区与是否含夏令时、字段精度(秒或毫秒)、非法时间的处理方式(例如上游给出 2026-02-30 时的期望行为)。这三点需要落到接口文档中,而不是通过联调时的现象推断。
时间字段的兼容演进按以下顺序推进:
新增带时区的新字段 → 旧字段与新字段双写 → 消费方切换读取新字段 → 停止写入旧字段 → 观察一个业务周期后删除旧字段
删除前需要确认所有读写方已切换,包括报表 SQL、数据同步任务、导出文件与下游数仓。
3.4 编码实践
3.4.1 文件读写与网络传输显式指定字符集
// 文件读写:显式字符集
List<String> lines = Files.readAllLines(path, StandardCharsets.UTF_8);
Files.writeString(path, text, StandardCharsets.UTF_8);
try (BufferedReader reader = Files.newBufferedReader(path, StandardCharsets.UTF_8)) {
// ...
}
// 网络与转换流:显式字符集
try (InputStreamReader isr =
new InputStreamReader(socket.getInputStream(), StandardCharsets.UTF_8)) {
// ...
}
需要显式指定的入口清单:
| 入口 | 需要显式化的位置 |
|---|---|
| 文件 | FileReader、FileWriter、Files.newBufferedReader、Files.readString、Files.writeString |
| 网络 | InputStreamReader、OutputStreamWriter、Scanner、HTTP 客户端响应体解码 |
| 进程与终端 | ProcessBuilder 输出解码、标准输出重定向后的编码 |
| 字节与字符串 | String.getBytes()、new String(byte[])、ByteArrayOutputStream.toString() |
| 数据库 | 连接串字符集参数、SET NAMES、驱动配置 |
| HTTP 响应 | Content-Type: text/*; charset=UTF-8 |
HTTP 响应若未声明 charset,接收方只能按默认字符集猜测,是乱码的常见入口。服务端应始终在 Content-Type 中声明字符集。
3.4.2 字符集一致性的核查
数据库侧三层一致性的核查命令:
-- 服务端与连接层变量
SHOW VARIABLES LIKE 'character_set%';
SHOW VARIABLES LIKE 'collation%';
-- 库、表、列的字符集与排序规则
SELECT schema_name, default_character_set_name, default_collation_name
FROM information_schema.schemata WHERE schema_name = 'app';
SELECT table_name, table_collation
FROM information_schema.tables WHERE table_schema = 'app';
SELECT table_name, column_name, character_set_name, collation_name
FROM information_schema.columns
WHERE table_schema = 'app' AND character_set_name IS NOT NULL;
-- 会话时区与当前时间解释
SELECT @@global.time_zone, @@session.time_zone, NOW(), UTC_TIMESTAMP();
三项判读标准:character_set_server 与 character_set_database 一致;表与列的字符集为 utf8mb4,排序规则与实例默认一致;SHOW VARIABLES LIKE 'character_set%' 中 client、connection、results 三项与列字符集一致。
主机与进程侧的核查命令:
# 主机时区与同步状态
timedatectl
date -u
# 区域与字符映射
locale
locale charmap
# JVM 实际生效的属性
java -XshowSettings:properties -version 2>&1 \
| grep -E 'file.encoding|sun.jnu.encoding|user.timezone'
# 文件编码识别与转换
file -i data.csv
iconv -f GBK -t UTF-8 data.csv -o data_utf8.csv
file -i 给出的是启发式推测,仅作为定位线索;确定性判断需要依据协议的字符集声明或业务侧约定。
3.4.3 JVM、容器与终端的编码设置
# JVM 参数:显式固定文件编码与默认时区
java -Dfile.encoding=UTF-8 -Dsun.jnu.encoding=UTF-8 -Duser.timezone=UTC -jar app.jar
JDK 18 起 file.encoding 的默认值为 UTF-8(JEP 400),但 sun.jnu.encoding(文件名与命令行参数的编码)仍取决于系统区域设置,在容器中可能为 ASCII。容器镜像内的处理方式是在镜像中固定区域与编码,而不是依赖运行环境:
# 镜像内固定时区与字符编码,避免依赖运行环境
ENV TZ=UTC \
LANG=C.UTF-8 \
LC_ALL=C.UTF-8
容器默认使用 UTC,日志时间与业务本地时间会相差固定小时数;基础镜像未设置区域时,文件读写与日志输出可能使用非 UTF-8 编码。这两类现象的成因与处理方式见 云原生部署 的时区与编码不一致一节,容器日志中时间与编码问题的表现见 容器日志管理。
终端侧同样需要一致性:登录终端的 LANG 与 LC_ALL 决定 shell 输出与工具行为的编码,ssh 会话、cron 与 systemd 单元的执行环境各不相同,TZ、LANG 等变量在这些环境中未必与登录会话相同。以 cron 调度的导出任务若依赖环境变量决定编码,需要在任务中显式设置。
高危 修改数据库、表或列的字符集与排序规则(ALTER TABLE ... CONVERT TO CHARACTER SET、ALTER DATABASE ... CHARACTER SET、修改列字符集)
- 影响范围:
CONVERT TO CHARACTER SET会重建表并转换已有数据,执行期间持锁时间长、磁盘与tmpdir需要与表规模相当的额外空间,大表会显著放大复制延迟。转换在表达能力上是单向的:向表达能力更小的字符集转换(utf8mb4 转 utf8mb3)会造成四字节字符截断或写入失败,且无法通过再次转换恢复。字符集变更同时改变列长度的字节语义,索引前缀长度上限(InnoDB 为 3072 字节)可能因此被触碰。排序规则变更会改变比较与排序结果,可能触发唯一约束判定的变化。 - 回滚方式:结构转换不可通过逆向 DDL 回滚,只能通过变更前的逻辑备份或物理备份恢复;排序规则可以改回原规则,但变更期间产生的数据需要重新核对唯一性约束。
- 前置要求:变更前完成全量备份与恢复演练;用
information_schema核对受影响列清单与多字节字符的实际占用;把转换安排在维护窗口并按表分批执行;变更后核对抽样数据、唯一约束与关联查询的执行计划。在线变更工具的选型与代价来源见 MySQL 表结构变更与日常运维。
高危 修改连接字符集(连接串字符集参数、驱动字符集配置、SET NAMES)
- 影响范围:连接字符集决定服务端如何解释客户端发送的字节与如何编码返回结果。参数变更后,该连接上与数据库交换的全部字符串都按新规则解释;若应用发送的字节流编码与新声明不一致,原来能正常写入的内容会变为乱码或写入报错,已写入数据的字节序列不会随之改变,从而出现新旧数据表现不一致。
- 回滚方式:恢复连接参数并重建连接池(池内已建立的连接保留旧参数,仅改配置不生效);若已产生错误解释的数据,需要依据业务侧记录还原原始字符串后重写,无法直接从数据库中的字节恢复。
- 前置要求:变更前确认应用实际发送的字节编码(抓取单条写入语句的十六进制或核对客户端库行为),确保连接参数与之匹配;变更时完整重建连接;变更后核对含四字节字符与中文的读、写、关联查询三类路径。
3.4.4 编码转换与字节截断
编码与解码、字符集转换与安全截断的实现见 2.7.4 与 2.7.5。工程上补充两点约定:
- 转换只允许经过字符层。 需要把 UTF-8 数据写入只支持 GBK 的系统时,先在应用内解码为字符串,再按目标字符集编码,并对目标字符集的不可映射字符做显式处理(替换、剔除或拒绝),而不是在字节层做映射。
- 二进制数据不进入文本链路。 压缩、加密、序列化后的数据如需通过文本协议传输,使用文本编码方案(如 Base64)而不是直接以文本字符集编码字节;相关原理与适用场景见 Base64 编码。把压缩或加密结果按 UTF-8 编码还会造成体积膨胀与不可逆的数据损坏。
对于截断,需要明确策略并统一实现:按字节上限截断(数据库列、消息体积)、按字符数上限截断(产品规则)、截断后是否追加省略标记。三者需要在同一工具方法中实现,避免各处各写一份。
3.5 常见问题与排查
以下每一项给出定位步骤,按"先确认现象位置,再逐层收敛"的顺序展开。
3.5.1 时间少或多若干小时
现象:接口返回时间、页面展示时间、数据库中的值三者相差整数小时。
1. 确认偏差是否为整小时(1、2、8、13 等)
整小时偏差指向时区问题,非整小时偏差指向夏令时规则或精度问题
2. 读取链路上各环节的时间值:应用日志中的 Instant、接口返回的字符串、数据库中的列值
3. 核对数据库会话时区与服务器时区
SELECT @@global.time_zone, @@session.time_zone, NOW(), UTC_TIMESTAMP();
4. 核对 JVM 生效属性
java -XshowSettings:properties -version 2>&1 | grep user.timezone
5. 核对连接参数中的时区项(connectionTimeZone 或 serverTimezone)是否与上述两者一致
6. 核对列类型:TIMESTAMP 参与会话时区转换,DATETIME 不参与
若同一偏差只在部分表出现,先比较列类型
7. 核对默认值来源:对比 created_at 与应用写入的时间,判断是数据库默认值还是应用赋值
3.5.2 夏令时当天任务重复或跳过
1. 确认主机与任务执行环境的时区
timedatectl
crontab -l 与 systemd 单元中的 TZ、OnCalendar 设置
2. 确认该区域在当期是否发生夏令时切换,以及切换的具体时刻
查看区域规则:zone.getRules().getTransition(...) 或时区数据源的切换记录
3. 检查任务是否按本地时间调度:按本地时间调度的任务在秋季重复、春季跳过
4. 检查任务是否具备幂等性:以业务主键或日期做唯一约束,重复执行不产生重复数据
5. 检查任务的执行记录是否以 UTC 时间戳保存:以本地时间判断当天是否已执行会在切换日失效
6. 处理:任务改为按 UTC 调度,或保留本地调度但增加基于 UTC 的当天执行去重标记
3.5.3 字符串长度与预期不符
1. 区分三个长度口径:代码单元数(String.length)、码点数(codePointCount)、UTF-8 字节数(getBytes().length)
2. 若长度比预期小(中文按字符数计算):检查是否按字节做了截断或列长度限制
3. 若长度比预期大(含 emoji 的内容长度翻倍):内容含增补字符,占两个代码单元
4. 检查截断位置:substring 的下标为代码单元数,可能切开代理对
使用 s.codePointCount 与 s.offsetByCodePoints 复核
5. 检查校验规则与列定义是否同一口径:数据库列上限为字节数,应用校验若为字符数会越界
6. 检查输出端是否出现替换字符(U+FFFD)或孤立代理,定位截断发生的环节
3.5.4 数据库乱码与问号
1. 区分两种形态
问号(?)表示字符在某一字符集中不可表示而被替换
乱码字符(如 锟斤拷、测试)表示编解码规则不一致
2. 若为问号:确认列字符集是否支持输入字符(utf8mb3 无法存四字节字符)
核对写入语句是否报 Incorrect string value
3. 若为乱码:
a. 用 HEX() 查看列中实际字节,判断原始字节序列是否符合某个字符集的特征
SELECT HEX(name) FROM t WHERE id = ?;
b. 对照链路各环节声明的字符集:客户端连接、服务端变量、库、表、列
c. 用该字节序列依次按候选字符集解码,确认在哪一步引入了解码错误
4. 核对连接层三项变量与列字符集是否一致
SHOW VARIABLES LIKE 'character_set%';
5. 检查是否经过字节层转换环节(文件中转、消息队列、中间缓存)
6. 处理:修正声明与转换点后,已损坏的数据需依据业务侧记录或备份重写
替换字符链不可逆,无法从损坏后的字节恢复原始内容
3.5.5 日志时间与业务时间不一致
1. 确认日志中记录的是事件时刻还是格式化后的本地时间
2. 核对容器与主机时区(容器默认 UTC)
timedatectl
容器或 Pod 规格中的 TZ 环境变量
3. 核对日志框架的时间配置(pattern 中的时区、是否使用本地时间)
4. 核对 JVM 的 user.timezone 与业务代码使用的区域是否一致
java -XshowSettings:properties -version 2>&1 | grep user.timezone
5. 核对数据库中的时间与应用日志时间的差值,判断偏差发生在应用侧还是数据库侧
6. 处理:统一以 UTC 记录日志时间并附加时区标识,展示层再转换为本地时间
3.5.6 时间回拨导致超时异常
现象:偶发的超时异常、请求挂起不超时、定时任务在回拨后重复触发或漏触发。
1. 确认是否发生过系统时间调整
timedatectl show-timesync --all
chronyc tracking
检查系统日志中的时间调整记录
2. 检查超时判断实现:使用 System.currentTimeMillis() 或 Instant.now() 计算截止点的代码在回拨后失效
替换为 System.nanoTime() 的单调时钟实现
3. 检查以时间戳生成 ID 或排序的逻辑,回拨后是否可能产生重复或乱序
4. 检查依赖时间戳的增量同步与缓存过期逻辑,回拨窗口内的数据是否被漏处理
5. 长期措施:把时间偏移纳入监控与告警
检查命令与阈值见主机巡检与监控告警两处文档
3.6 规范与检查清单
3.6.1 编码规范条目
| 类别 | 规范 |
|---|---|
| 时间类型 | 业务代码禁止使用 java.util.Date、Calendar、SimpleDateFormat;时刻统一使用 Instant,业务日期使用 LocalDate |
| 时区 | 禁止在业务代码中调用 ZoneId.systemDefault() 与无参 now();区域从配置注入并在固定位置转换 |
| 计时 | 耗时测量使用 System.nanoTime();超时截止点同样使用单调时钟 |
| 格式 | 传输使用 ISO 常量格式;DateTimeFormatter 定义为静态不可变常量并复用;外部输入解析使用 ResolverStyle.STRICT |
| 序列化 | 时间字段格式在接口文档中声明;关闭框架的时间戳默认输出;同系统内不混用毫秒与秒级时间戳 |
| 编码 | 禁止无参 getBytes()、new String(byte[])、FileReader、FileWriter;所有编解码显式指定 StandardCharsets.UTF_8 |
| 大小写 | 面向协议与内部的字符串大小写转换使用 Locale.ROOT |
| 截断 | 字节截断与字符截断使用统一的工具方法,不使用裸 substring 或数组切分 |
| 二进制 | 压缩、加密、序列化数据不进入文本编码链路,需要文本化时使用 Base64 等文本编码 |
| 数据库 | 建库建表与连接串显式声明 utf8mb4 与排序规则;时间列按语义选择类型并记录在表结构说明中 |
3.6.2 可自动检查的规则
以下问题属于静态可判定的模式,可以配置到静态分析规则中,把缺陷暴露阶段前移到提交与构建环节(静态分析的价值定位与规则体系见 代码质量与静态分析):
- 调用 String.getBytes() 或 new String(byte[]) 而未传 Charset 参数
- 使用 FileReader、FileWriter、无字符集的 InputStreamReader、PrintWriter(File)
- 静态字段类型为 SimpleDateFormat 或 DateFormat
- 使用 Calendar.getInstance()、new Date()、System.currentTimeMillis() 参与的耗时或超时计算
- 使用 LocalDateTime.now()、Instant.now()、LocalDate.now() 且未传入 Clock
- 使用 ZoneId.systemDefault()、TimeZone.getDefault()
- 使用 new SimpleDateFormat(...) 而未调用 setLenient(false)
- 格式模式中使用 yyyy 而非 uuuu(严格解析场景)
- 使用 String.toLowerCase() 或 toUpperCase() 而未传 Locale
- SQL 文本中对时间列套用函数(YEAR(、MONTH(、DATE(、UNIX_TIMESTAMP()
3.6.3 上线前检查清单
| 检查项 | 判定标准 |
|---|---|
| JVM 时区与编码 | user.timezone、file.encoding、sun.jnu.encoding 有显式取值,与镜像及编排配置一致 |
| 容器环境 | 镜像内固定 TZ、LANG、LC_ALL;未设置时区数据的基础镜像已确认规则来源 |
| 数据库服务端 | character_set_server、collation_server、default_time_zone 有显式配置且与应用约定一致 |
| 连接参数 | 连接串显式声明字符集与时区;连接池重建后参数生效 |
| 表与列 | 目标表与列字符集为 utf8mb4;时间列类型与字段语义匹配;分数秒精度符合接口精度 |
| 默认值与自动更新 | 时间默认值的生成方(应用或数据库)唯一;ON UPDATE 的影响已评估 |
| 接口格式 | 时间字段的格式、精度、时区在接口文档中声明;毫秒与秒级时间戳未混用 |
| 序列化配置 | 框架的时间序列化开关已显式设定并经过序列化断言测试 |
| 定时任务 | 调度基准、幂等性与去重依据明确;执行环境中的 TZ、LANG 已显式设置 |
| 监测项 | 主机时间偏移纳入监控与告警;日志时间的时区标识明确 |
| 数据兼容 | 变更前的备份与恢复演练已完成;时间与字符集相关的数据订正脚本具备幂等性与分批能力 |
| 静态规则 | 3.6.2 的规则已启用,构建未产生新增告警 |
四、总结
时间和编码是同一类问题的两个面:代码中未显式声明的假设,必然由运行环境来填充,而运行环境之间的差异恰恰是缺陷的藏身处。
时间的核心是把"瞬间"与"日历读数"分开:时刻用 UTC 表示并存储,本地读取按显式区域解释,时区规则视为会变化的外部数据而非固定常量。
围绕这一条,具体结论是:
java.time的不可变类型让时间值具备值语义与线程安全,类型的选择应当由语义(是时刻还是本地读数)决定,而不是由调用便利性决定。- 旧 API 的可变性、零基月份与
SimpleDateFormat的线程不安全属于历史遗留,新代码不再使用,迁移的转换点收敛在数据访问层与外部接口层。 - 夏令时带来不存在的本地时间与重复的本地时间,前者必须在构造时判定,后者必须显式消歧;按本地时间调度的任务需要幂等性与 UTC 去重依据。
- 精度在每一层转换处被截断,比较与断言需要对齐到列精度;耗时与超时必须使用单调时钟,墙钟只用于记录事件时刻。
- 解析的宽松度需要在外部输入处收紧,序列化格式需要在系统内唯一,展示层的本地化与传输格式分离。
- 编码的本质是码点到字节的映射,字符、码点、代码单元三者不可混用;BOM、代理项与字节截断是长度类问题的主要来源。
- 乱码只有五类成因,排查手段是查看实际字节序列并逐环节核对声明的字符集;替换字符链不可逆,预防成本远低于修复成本。
- 排序在不同层有不同规则,应用层比较器与数据库排序规则需要显式对齐,尤其是大小写与尾空格的处理差异。
一句话记忆:时间问题源于边界没画清——哪一层用 UTC、哪一层用本地时间、规则由谁提供;编码问题源于声明不一致——谁按什么规则编码、谁按什么规则解码。两者的工程解法是同一件事:把隐含假设变成显式约定,并在检查清单里留下验证手段。