Java里Date类和Calendar怎么用_Java旧版时间API说明

Java中应弃用Date和Calendar，改用Java 8的java.time包；Date仅包装毫秒值且方法废弃易错，Calendar笨重难用且时区处理不透明，而LocalDateTime、ZonedDateTime等类型职责清晰、线程安全、API直观。

Java里Date类为什么不能直接做日期计算

Date 类本质是毫秒时间戳的包装，它不提供年月日加减、获取星期几、计算两个日期差等能力。调用 date.getMonth() 或 date.getYear() 这类方法不仅已废弃（自 JDK 1.1），而且返回值还带偏移（比如月份是 0～11，年份是距 1900 的偏移量），极易出错。

• 不要用 date.setYear(2025) —— 实际设的是 2025 + 1900 = 3924 年
• 不要用 date.getDate() 取“几号”——它叫 getDate()，但其实是取“日”（day of month），命名和语义严重脱节
• 所有 getXXX()/setXXX() 方法在 JDK 1.1 就被标记为 @Deprecated，现代代码中应视为不可用

Calendar是Date的补丁，但用起来很重

Calendar 是为了弥补 Date 的缺陷而设计的，它支持时区、历法、字段增减等操作，但 API 设计笨重、线程不安全、易误用。

• 必须用 Calendar.getInstance() 获取实例，不能 new Calendar()
• 设置年月日要用 cal.set(Calendar.YEAR, 2025)，不能直接 cal.setYear(2025)
• 月份仍从 0 开始：cal.set(Calendar.MONTH, 0) 才是 1 月
• 获取时间戳要手动调用 cal.getTime().getTime()，绕一圈回到 long

Calendar cal = Calendar.getInstance();
cal.set(2025, Calendar.JANUARY, 15); // 注意：JANUARY = 0
Date date = cal.getTime(); // 转回 Date，仅用于兼容老接口

旧API在跨时区或夏令时场景下容易翻车

Calendar 默认使用 JVM 启动时加载的时区，且对夏令时过渡日处理隐式、不透明。例如在“2025-10-29 凌晨 2:00 欧洲中部时间进入冬令时”那天，把时间设为 2025-10-29 02:30

可能被自动跳到 03:30，或者抛 IllegalArgumentException，取决于 cal.isLenient() 设置。

• 默认 isLenient() == true：非法日期会被“纠正”，比如 2025-02-30 → 自动变成 2025-03-02
• 设为 false 后，cal.set(2025, 1, 30) 会直接抛异常
• 跨时区转换必须显式调用 cal.setTimeZone(TimeZone.getTimeZone("UTC"))，且需注意 setTime() 和 setTimeInMillis() 对时区的敏感性不同

现在该用什么替代

Java 8 引入的 java.time 包（JSR-310）才是正确答案：LocalDateTime、ZonedDateTime、Period、Duration 等类型职责清晰、不可变、线程安全、API 直观。

• 需要纯日期？用 LocalDate.of(2025, 1, 15)
• 要带时区的时间？用 ZonedDateTime.now(ZoneId.of("Asia/Shanghai"))
• 算两个日期差？用 Period.between(start, end) 或 ChronoUnit.DAYS.between(d1, d2)
• 和旧代码交互？用 date.toInstant().atZone(ZoneId.systemDefault()) 转换

真正棘手的不是“怎么用旧 API”，而是“怎么安全地从旧 API 迁移出来”——尤其当项目里大量存在 Date 字段、MyBatis 映射、JSON 序列化逻辑时，时区解释不一致是最隐蔽的坑。