一、核心概念理解

1.1 两种时间类型的本质区别

MySQL 中的时间类型看起来相似，但行为完全不同：

特性 TIMESTAMP DATETIME
存储方式 UTC 时间戳（4字节） 字面量（8字节）
时区转换 ✅ 自动转换 ❌ 不转换
存储范围 1970-01-01 到 2038-01-19 1000-01-01 到 9999-12-31
时区感知 是 否
适用场景 跨时区业务 本地时间（如生日）
sql
-- 验证示例
CREATE TABLE time_test (
    ts TIMESTAMP,
    dt DATETIME
);

-- 插入相同的时间值
INSERT INTO time_test VALUES ('2024-01-01 10:00:00', '2024-01-01 10:00:00');

-- 修改会话时区
SET SESSION time_zone = '+00:00';  -- 改为 UTC
SELECT * FROM time_test;
-- 结果：ts 显示 '2024-01-01 02:00:00'，dt 仍显示 '2024-01-01 10:00:00'

1.2 JDBC URL 中 serverTimezone 的作用

java
// 连接 URL 示例
String url = "jdbc:mysql://localhost:3306/db?serverTimezone=UTC";

核心作用：告诉 JDBC 驱动如何将 Java 程序中的时间对象转换为数据库存储格式。

  • 对 TIMESTAMP 生效：自动进行时区转换
  • 对 DATETIME 无效：原样存储，不做任何转换

二、实战场景解析

2.1 场景一：中国用户发送消息给美国用户

java
// 配置
// MySQL 连接 URL: serverTimezone=UTC
// 服务器部署：中国 (UTC+8)
// A用户：中国（接收消息）
// B用户：美国（查看消息）

// 1. A发送消息（北京时间 2024-01-01 10:00:00）
Message msg = new Message();
msg.setContent("Hello");

// 2. JDBC 写入（自动转换）
// 北京时间 10:00 → UTC 02:00 存入 TIMESTAMP 字段

// 3. B用户查询（美国 UTC-8）
// JDBC 读取：UTC 02:00 → 返回 Timestamp 对象（内部为绝对时间）
Timestamp dbTime = rs.getTimestamp("send_time");

// 4. API 返回（推荐方式）
return dbTime.toInstant().toEpochMilli(); // 1704096000000

// 5. 客户端渲染
// 美国用户看到：2023-12-31 18:00:00
// 中国用户看到：2024-01-01 10:00:00

2.2 场景二：客户端是否需要传时区？

结论：不一定必须，但推荐标准做法。

javascript
// 推荐方案：客户端传 UTC 时间戳
{
  "content": "Hello",
  "clientTime": 1704096000000  // UTC 绝对时间戳
}

// 更推荐：不传时间，由服务器生成
{
  "content": "Hello"
  // 服务器自动添加 server_time
}

三、最佳实践方案

3.1 数据库设计规范

sql
CREATE TABLE im_message (
    id BIGINT PRIMARY KEY AUTO_INCREMENT,
    content TEXT NOT NULL,
    
    -- 标准时间字段
    created_at TIMESTAMP(3) DEFAULT CURRENT_TIMESTAMP(3),
    updated_at TIMESTAMP(3) DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3),
    
    -- 业务时间（可选）
    business_time TIMESTAMP(3) NULL COMMENT '业务时间，UTC',
    
    -- 跨2038年方案（如果需要）
    created_at_ms BIGINT NOT NULL DEFAULT (UNIX_TIMESTAMP() * 1000),
    
    INDEX idx_created_at (created_at)
);

3.2 应用层统一处理

java
// 配置类
@Configuration
public class TimeConfig {
    
    @Bean
    public Jackson2ObjectMapperBuilderCustomizer jacksonCustomizer() {
        return builder -> {
            builder.timeZone(TimeZone.getTimeZone("UTC"));
            builder.simpleDateFormat("yyyy-MM-dd'T'HH:mm:ss'Z'");
        };
    }
}

// 实体类
@Entity
public class Message {
    
    @Column(columnDefinition = "TIMESTAMP(3)")
    private Instant createdAt;  // 使用 Instant，自动处理时区
    
    // 或者使用 ZonedDateTime/OffsetDateTime
    private OffsetDateTime businessTime;
}

// Service 层
@Service
public class MessageService {
    
    public Message createMessage(String content) {
        Message msg = new Message();
        msg.setContent(content);
        msg.setCreatedAt(Instant.now()); // UTC 时间
        return messageRepository.save(msg);
    }
}

3.3 API 设计规范

java
@RestController
public class MessageController {
    
    @GetMapping("/messages")
    public List<MessageDTO> getMessages() {
        return messages.stream()
            .map(msg -> MessageDTO.builder()
                .content(msg.getContent())
                .createdAt(msg.getCreatedAt().toEpochMilli()) // 返回时间戳
                // 或返回 ISO 8601 格式
                .createdAtIso(msg.getCreatedAt().toString())
                .build())
            .collect(Collectors.toList());
    }
}

// DTO 示例
public class MessageDTO {
    private String content;
    private Long createdAt;      // 时间戳毫秒
    private String createdAtIso; // ISO 8601: "2024-01-01T02:00:00Z"
}

3.4 客户端处理

javascript
// JavaScript 客户端
class TimeHelper {
    // 渲染消息时间
    static formatMessageTime(timestamp) {
        const date = new Date(timestamp);
        const now = new Date();
        const diff = now - date;
        
        if (diff < 60000) return '刚刚';
        if (diff < 3600000) return `${Math.floor(diff / 60000)}分钟前`;
        if (diff < 86400000) return `${Math.floor(diff / 3600000)}小时前`;
        
        return date.toLocaleString(); // 自动转换到本地时区
    }
}

// 使用
<div class="message-time">
    {TimeHelper.formatMessageTime(message.createdAt)}
</div>

四、常见陷阱与解决方案

4.1 陷阱一：TIMESTAMP 的 2038 年问题

sql
-- 问题：TIMESTAMP 最大到 2038-01-19
-- 解决方案1：使用 DATETIME + 应用层统一 UTC
created_at DATETIME(3) DEFAULT CURRENT_TIMESTAMP(3)

-- 解决方案2：使用 BIGINT 存储毫秒时间戳
created_at_ms BIGINT NOT NULL

-- 解决方案3：升级到 MySQL 8.0+，但 TIMESTAMP 范围未变

4.2 陷阱二：错误的时区转换

java
// ❌ 错误：手动转换时区
LocalDateTime beijingTime = LocalDateTime.now();
String utcTime = beijingTime.atZone(ZoneId.of("Asia/Shanghai"))
    .withZoneSameInstant(ZoneId.of("UTC"))
    .format(DateTimeFormatter.ISO_LOCAL_DATE_TIME);
// 容易出错，且丢失精度

// ✅ 正确：使用 Instant
Instant now = Instant.now();  // UTC
Timestamp dbTime = Timestamp.from(now);

// ✅ 正确：使用 OffsetDateTime
OffsetDateTime utcTime = OffsetDateTime.now(ZoneOffset.UTC);

4.3 陷阱三：Jackson 序列化时区问题

java
// application.yml 配置
spring:
  jackson:
    time-zone: UTC
    date-format: yyyy-MM-dd'T'HH:mm:ss'Z'
    
// 或者在实体类上指定
@JsonFormat(timezone = "UTC", pattern = "yyyy-MM-dd'T'HH:mm:ss'Z")
private Instant createdAt;

4.4 陷阱四：MyBatis 时区处理

xml
<!-- MyBatis 配置 -->
<configuration>
    <settings>
        <setting name="mapUnderscoreToCamelCase" value="true"/>
        <!-- MyBatis 会使用 JDBC 连接的时区设置 -->
    </settings>
</configuration>
java
// TypeHandler 示例（如需自定义）
@MappedTypes(Instant.class)
@MappedJdbcTypes(JdbcType.TIMESTAMP)
public class InstantTypeHandler extends BaseTypeHandler<Instant> {
    
    @Override
    public void setNonNullParameter(PreparedStatement ps, int i, 
                                    Instant parameter, JdbcType jdbcType) 
                                    throws SQLException {
        ps.setTimestamp(i, Timestamp.from(parameter));
    }
    
    @Override
    public Instant getNullableResult(ResultSet rs, String columnName) 
                                    throws SQLException {
        Timestamp timestamp = rs.getTimestamp(columnName);
        return timestamp != null ? timestamp.toInstant() : null;
    }
}

五、生产环境检查清单

5.1 部署前检查

  • MySQL 服务器时区设置：
  • JDBC URL 明确指定
  • 应用服务器时区：

5.2 监控告警

sql
-- 监控时间字段异常
SELECT COUNT(*) FROM messages 
WHERE created_at < '2020-01-01' 
   OR created_at > '2030-01-01';

-- 检查时区配置
SHOW VARIABLES WHERE Variable_name LIKE '%time_zone%';

5.3 测试用例

java
@Test
public void testTimeZoneConsistency() {
    // 测试时区转换一致性
    Instant now = Instant.now();
    Message msg = new Message();
    msg.setCreatedAt(now);
    messageRepository.save(msg);
    
    Message saved = messageRepository.findById(msg.getId()).get();
    assertEquals(now.toEpochMilli(), saved.getCreatedAt().toEpochMilli());
}

@Test
public void testCrossTimeZone() {
    // 模拟不同时区查看同一条消息
    Message msg = messageService.createMessage("Test");
    Long timestamp = msg.getCreatedAt().toEpochMilli();
    
    // 北京用户
    String beijingTime = Instant.ofEpochMilli(timestamp)
        .atZone(ZoneId.of("Asia/Shanghai"))
        .format(DateTimeFormatter.ISO_LOCAL_DATE_TIME);
    
    // 纽约用户
    String newYorkTime = Instant.ofEpochMilli(timestamp)
        .atZone(ZoneId.of("America/New_York"))
        .format(DateTimeFormatter.ISO_LOCAL_DATE_TIME);
    
    assertNotEquals(beijingTime, newYorkTime);
    // 虽然是同一个时刻，显示的时间字符串不同
}

六、总结与建议

核心原则

  1. 统一标准：所有时间内部以 UTC 存储和处理
  2. 边界转换：只在系统边界（输入/输出）进行时区转换
  3. 类型选择：跨时区用 TIMESTAMP，本地时间用 DATETIME
  4. 避免手动转换：使用 Java 8+ 的 java.time 包

架构决策树

text
是否需要跨时区？
├─ 是 → 使用 TIMESTAMP 或 BIGINT 毫秒
│      └─ serverTimezone=UTC
│      └─ 统一返回时间戳
│
└─ 否 → 可使用 DATETIME
       └─ 确保服务器和数据库时区一致
       └─ 简单业务可直接存本地时间

快速配置模板

text
# application.properties
spring.datasource.url=jdbc:mysql://localhost:3306/db?serverTimezone=UTC&useSSL=false
spring.datasource.hikari.connection-init-sql=SET NAMES utf8mb4
spring.jackson.time-zone=UTC
sql
-- 初始化 SQL
SET GLOBAL time_zone = '+00:00';
SET SESSION time_zone = '+00:00';
ALTER DATABASE your_db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

参考资源

最后提醒：时区问题没有一劳永逸的解决方案，关键是在整个技术栈中保持一致性。建议在项目初期就明确时区处理策略，避免后期大规模重构。