写日期格式化这个主题我想先从一张截图说起。上个月我帮朋友排查一个线上问题他负责的报表系统突然有一天所有时间字段都对不上数据库里存的是2026-01-01导出的Excel里却变成了2026-00-01。他找了一圈最后发现代码里有人把格式化pattern随手写成了yyyy-MM-dd但实际执行解析和格式化的是两个不同的工具类其中一个把MM写成了mm月份直接变成了分钟。类似这种从Date到String的转换问题几乎每个Java开发都遇到过所以我决定把这条链路上所有值得注意的细节完整梳理一遍。这篇文章会围绕Java日期格式化展开重点讲java.util.Date体系下如何安全地格式化成String以及JDK 8之后java.time包带来的全新处理方式。也就是把从Date到String、再从String到Date的完整双向转换讲透包括格式化pattern的选择、线程安全问题的根源、新旧两套API的桥接方法、常见的坑和面试题避雷点。不管你是刚学Java基础的新手还是已经在写业务代码一两年的开发者这篇文章都能帮你省下不少排查时间。1. 日期格式化不只是ToString那么简单1.1 为什么Java的日期格式化特别容易踩坑我在带新人或者帮同事review代码的时候发现一个现象很多Java开发者对日期格式化的理解停留在“会用SimpleDateFormat写个pattern”这个层面一旦遇到线程安全、时区转换、新旧API混用的问题就开始到处复制代码出了bug也不知道怎么排查。这类问题在Java面试题里也是高频考点尤其是“SimpleDateFormat为什么线程不安全”这一问能答清楚的人其实不多。先说一个最基本的认知Date这个对象本质上是“一个时间戳的容器”。它内部保存的是从1970年1月1日0点0分0秒UTC开始到某个时刻的毫秒数这个毫秒数本身和“年月日时分秒”没有任何直接关系。要把它变成人类能看懂的字符串比如2025-06-01 10:30:00就必须按照某种规则去拆解这个毫秒数这个拆解规则就是DateFormat要做的事。反过来要把一个字符串还原成Date本质上就是按同样的规则去组装一个毫秒数。听起来很简单对吧但真正容易踩坑的地方在于不同地区、不同时区、不同历法下同一个毫秒数对应的年月日是不一样的。这就是为什么Java提供了一套看起来并不简单的日期时间处理API而不是一上来就给Date加一个toString()就完事了。Date.toString()确实能输出字符串但它的格式是Sat Jun 01 10:30:00 CST 2025这种既不符合大部分业务系统的展示需求也不利于日志重分析和跨系统交互所以才有接下来要讲的种种格式化和解析手段。1.2 从Date到String这条链路需要理解的基础概念在正式讲格式化方法之前我先把几个绕不开的基础概念摆出来这些虽然不是主角但搞不懂它们后面看什么代码都会觉得隔了一层。时间戳Epoch Millis也就是System.currentTimeMillis()返回的那个数字。它是机器眼中的“当前时间”。几乎所有日期时间操作的第一步都是和这个数字打交道。时区Time Zone同样一个毫秒数在UTC8时区显示是08:00在UTC时区显示就是00:00。格式化过程中如果没有明确指定时区Java会使用JVM默认时区这会导致同一套代码部署到不同时区的服务器上输出的字符串各不相同。这是一个非常重要但经常被忽视的变量。Locale地区/语言它影响月份名称、星期的显示语言以及某些地区的日期排列习惯。比如英文环境下Jun、July中文环境下六月、七月。如果只做数字格式的yyyy-MM-ddLocale影响不大但如果输出yyyy年M月d日或者EEE, d MMM yyyy这种格式Locale就直接决定结果。年中的周与周的年份这个是Java里最阴间的概念之一。YYYY大写代表“Week Year”也就是和ISO周数对应的年份它不一定等于自然年yyyy。每年跨年附近几天用YYYY格式化经常得到“错误”的年份。这个坑我在第四部分会专门展开讲。把上面几个概念刻在脑子之后再去看SimpleDateFormat和DateTimeFormatter的源码和行为就会觉得它们的设计其实很有逻辑只是一般人没时间细看。2. 核心方案选型JDK 8前后两套API怎么选2.1 SimpleDateFormat老项目绕不开的“老朋友”在JDK 8之前Java世界唯一的格式化工具就是SimpleDateFormat它继承自抽象类DateFormat。这个类用起来很简单SimpleDateFormat sdf new SimpleDateFormat(yyyy-MM-dd HH:mm:ss); Date now new Date(); String formatted sdf.format(now); // 2025-06-01 10:30:00 Date parsed sdf.parse(2025-06-01 10:30:00); // 还原回Date几乎所有从java.util.Date到String、再从String到java.util.Date的转换都靠它完成。它的核心概念是“pattern模式串”由英文字母和符号组成每个字母代表一项日历字段。比如yyyy代表4位年份MM代表月份dd代表日HH代表24小时制的小时mm代表分钟ss代表秒SSS代表毫秒。但SimpleDateFormat最大的问题不在功能而在线程安全。这个类内部有一个Calendar成员变量在整个format和parse过程中都用它来做临时计算。当多个线程共享同一个SimpleDateFormat实例时线程A在设置Calendar的年月日线程B也在设置两个操作交叉执行就会互相污染最终结果可能是完全错乱的时间而且错乱值每次运行可能还不一样非常难排查。很多老项目为了性能喜欢把SimpleDateFormat定义成static final常量全局共用这就为线上偶发的时间错乱埋下了雷。我见过一个定时任务系统偶尔出现日志时间凭空后移好几个小时的情况查了半天最后定位到就是这个静态共享的SimpleDateFormat被并发调用导致的。所以旧代码里凡是看到静态的SimpleDateFormat基本可以认定是一个安全隐患。2.2 DateTimeFormatter新代码的“正确打开方式”JDK 8开始Java引入了全新的java.time时间API同时带来了线程安全且功能更强大的DateTimeFormatter。和SimpleDateFormat最大的区别是DateTimeFormatter是不可变immutable且线程安全的能在多线程环境下放心共享同一个实例。用法上同样支持pattern模式串但对应的是java.time包下的新时间类DateTimeFormatter formatter DateTimeFormatter.ofPattern(yyyy-MM-dd HH:mm:ss); LocalDateTime now LocalDateTime.now(); String formatted now.format(formatter); // 2025-06-01 10:30:00 LocalDateTime parsed LocalDateTime.parse(2025-06-01 10:30:00, formatter);从这里能看到一个明显差异新API把“待格式化的时间对象”和“格式化器”彻底剥离了formatter只负责定义规则不保存任何中间状态。这就像你拿一个刻好模板的印章去盖戳盖章过程中印章本身不会被修改随便多少人轮流用它盖章都安全。另外DateTimeFormatter对运行环境要求高制定接口规范也更严格。比如解析字符串时如果字符串和pattern不匹配它会明确告诉你第几个位置出了问题而不是像SimpleDateFormat那样常常给出一个看起来能用的垃圾值。我在新项目里一律推荐团队成员使用DateTimeFormatter甚至可以在代码规范层面禁止新增SimpleDateFormat的用法。旧代码暂时没时间重构没关系但新代码一定不要再引入旧类的并发风险了。2.3 新旧API的桥接从Date到LocalDateTime再到String有一个现实问题是现在大量项目里数据库实体、历史接口、第三方SDK用的都还是java.util.Date你不能因为想用新API就把所有Date类型的字段都改掉改动成本太高而且很多框架底层对Date有特殊处理。所以学会在Date和java.time之间切换是每个Java开发者的必备基本功。从Date转到LocalDateTime的标准姿势是Date date new Date(); Instant instant date.toInstant(); // 先转成Instant时间戳对象 LocalDateTime localDateTime instant.atZone(ZoneId.systemDefault()).toLocalDateTime();反过来从LocalDateTime转回DateLocalDateTime localDateTime LocalDateTime.now(); Date date Date.from(localDateTime.atZone(ZoneId.systemDefault()).toInstant());这里面的关键是Instant——它是新API里表示“某一个绝对时间点”的类和旧的Date非常类似本身不携带时区信息。atZone是往这个绝对时间点上附加一个时区规则得到带时区的ZonedDateTime再根据需求提取成无时区的LocalDateTime用于格式化展示。这样一套流程下来既能享受新API的线程安全和丰富功能又能兼容老代码里的Date类型字段。我在实际项目里最常用的一种做法是实体类里继续保持Date类型写一个单独的工具类负责把Date和格式化字符串互转工具类内部全部用DateTimeFormatter实现只在边界处做一次Date和java.time对象的转换。这样既不会破坏既有代码结构又能大幅减少格式化相关的并发风险。3. 实操日期格式化的完整实现方案3.1 基础款线程不安全的SimpleDateFormat先给一个“反面教材”因为很多老系统里现在就是这么写的。你需要能看出来问题在哪。假设我们有一个DateUtils工具类public class DateUtils { private static final SimpleDateFormat SDF new SimpleDateFormat(yyyy-MM-dd HH:mm:ss); public static String format(Date date) { return SDF.format(date); } public static Date parse(String str) { try { return SDF.parse(str); } catch (ParseException e) { throw new RuntimeException(e); } } }这段代码看起来逻辑很清晰而且因为复用了同一个SimpleDateFormat还“省内存”。但在高并发场景下这个工具类输出的格式化结果随时可能错乱。原因前面已经说过了SimpleDateFormat的实例内部不是线程安全的它的Calendar字段在format过程中会先被clear然后塞入待格式化的时间。假设线程A刚刚塞入2025-06-01这个时间还没读取完线程B过来把Calendar塞成了2025-12-31线程A读到的数据就可能是错乱的甚至会出现月份为0、日期为负数这种诡异结果。我自己实测过在100个线程同时调用这个工具类的场景大约有百分之几的概率出现时间小时数异常或者年份被篡改的情况。线上流量一大这种概率就会变成实实在在的偶发故障。所以用完就扔、每次new SimpleDateFormat虽然性能差一点但至少安全共享实例则必须配合ThreadLocal或加锁。3.2 升级款用ThreadLocal抱一个线程安全的SimpleDateFormat如果不升级到JDK 8的新API仍然想用SimpleDateFormat推荐用ThreadLocal给每个线程一个独立实例。这样既避免了频繁创建对象的开销又隔绝了线程间共享导致的污染。public class DateUtils { private static final ThreadLocalSimpleDateFormat SDF_HOLDER ThreadLocal.withInitial(() - new SimpleDateFormat(yyyy-MM-dd HH:mm:ss)); public static String format(Date date) { return SDF_HOLDER.get().format(date); } public static Date parse(String str) { try { return SDF_HOLDER.get().parse(str); } catch (ParseException e) { throw new RuntimeException(e); } } }ThreadLocal.withInitial的意思是每个线程第一次调用get()时会自动执行括号里的Supplier方法生成一个全新的SimpleDateFormat实例。之后这个线程再调用拿到的都是自己专属的那个实例。相当于每个线程有自己的一支笔和一个草稿本内容互不干扰。这个方案是网上流传最广的“线程安全版SimpleDateFormat”也是很多老项目改造的过渡方案。它的好处是不用改动业务代码里已有的大量Date相关调用只要把工具类内部实现换一下就完事。缺点也很明显ThreadLocal在Web容器线程池环境里会一直存活如果项目里到处用这种ThreadLocal存对象内存里会积累很多单线程专属的实例而且它依然没有解决SimpleDateFormat本身对ISO8601字符串、对多时区转换支持不完善的问题。所以只能算“升级”不算“终极方案”。3.3 终极方案全套基于DateTimeFormatter的格式化工具在新项目里我更推荐直接写一套基于DateTimeFormatter的工具类。不仅线程安全还覆盖了带时区、带毫秒、ISO标准字符串等更丰富的格式化场景。import java.time.Instant; import java.time.LocalDateTime; import java.time.ZoneId; import java.time.ZonedDateTime; import java.time.format.DateTimeFormatter; import java.util.Date; public class DateUtils { private static final DateTimeFormatter DATETIME_FORMATTER DateTimeFormatter.ofPattern(yyyy-MM-dd HH:mm:ss); private static final DateTimeFormatter DATETIME_MS_FORMATTER DateTimeFormatter.ofPattern(yyyy-MM-dd HH:mm:ss.SSS); private static final DateTimeFormatter ISO_FORMATTER DateTimeFormatter.ofPattern(yyyy-MM-ddTHH:mm:ss.SSSXXX); private DateUtils() { } public static String format(Date date) { return date.toInstant().atZone(ZoneId.systemDefault()).format(DATETIME_FORMATTER); } public static String format(Date date, String pattern) { DateTimeFormatter formatter DateTimeFormatter.ofPattern(pattern); return date.toInstant().atZone(ZoneId.systemDefault()).format(formatter); } public static String formatMs(Date date) { return date.toInstant().atZone(ZoneId.systemDefault()).format(DATETIME_MS_FORMATTER); } public static String formatIso(Date date) { return date.toInstant().truncatedTo(java.time.temporal.ChronoUnit.MILLIS).atZone(ZoneId.systemDefault()).format(ISO_FORMATTER); } public static Date parse(String str) { LocalDateTime ldt LocalDateTime.parse(str, DATETIME_FORMATTER); return Date.from(ldt.atZone(ZoneId.systemDefault()).toInstant()); } public static Date parse(String str, String pattern) { DateTimeFormatter formatter DateTimeFormatter.ofPattern(pattern); LocalDateTime ldt LocalDateTime.parse(str, formatter); return Date.from(ldt.atZone(ZoneId.systemDefault()).toInstant()); } }这套工具类有几个设计上的细节值得注意第一所有的DateTimeFormatter实例都是static final的可以直接被多个线程共享。因为DateTimeFormatter是不可变类没有内部状态会被修改。第二format和parse都显式经过了ZoneId.systemDefault()也就是用JVM默认时区来桥接。假如你有特殊需求要“无论服务器在哪个时区都按北京时间格式化输出”那段代码就要把ZoneId.systemDefault()替换成ZoneId.of(Asia/Shanghai)。第三formatIso里我加了一个truncatedTo(ChronoUnit.MILLIS)目的是把低于毫秒的精度截断掉。因为Date本身只精确到毫秒但Instant可以精确到纳秒如果不截断直接格式化出来的SSS部分可能带出微小误差导致的奇怪数字。不要小看这套代码它就是现代Java日期格式化的“标准答案”可以直接从这篇博文抄进项目里用。3.4 场景实战时间戳、带时区字符串、批量解析光有工具类还不够我列三个最常遇到的业务场景直接把代码摆出来各位可以对着自己的需求改。场景一把当前时间格式化后写入文件名String fileName report_ DateUtils.format(new Date(), yyyyMMdd_HHmmss) .csv;输出类似report_20250601_103000.csv。在文件命名、日志文件名、批处理标记这些场景里用yyyyMMdd_HHmmss这种紧凑格式比带横线和冒号的格式更友好不会被操作系统当作非法字符。场景二解析带时区信息的ISO字符串如果一个字段来自第三方接口传来的是2025-06-01T10:30:0008:00这种带偏移的字符串就不能直接用LocalDateTime.parse了因为LocalDateTime本身没有时区概念解析不了偏移量。这时需要String input 2025-06-01T10:30:0008:00; OffsetDateTime odt OffsetDateTime.parse(input); Date date Date.from(odt.toInstant());OffsetDateTime.parse默认就能解析ISO格式的偏移量。拿到OffsetDateTime之后调用toInstant()得到标准UTC时间点再转成Date。这个方案处理跨时区对接特别实用因为字符串里的08:00已经被程序正确读取了不需要你手动去掉偏移再解析。场景三批量解析日志里的日期字符串日志分析工具经常要从几万行文本里提取日期。如果每一行都走一次LocalDateTime.parse性能上稍微有点损失但完全可以接受。更需要注意的是日志里提取出来的字符串可能带有额外字符比如2025-06-01 10:30:00,123这里的逗号后面是毫秒。这种格式建议先做预处理// 把逗号替换成点让默认pattern能识别 String cleaned logLine.substring(0, 19) . logLine.substring(20, 23); LocalDateTime ldt LocalDateTime.parse(cleaned, DateTimeFormatter.ofPattern(yyyy-MM-dd HH:mm:ss.SSS));LocalDateTime.parse默认要求字符串与pattern完全匹配多一个空格都会报错。所以在处理脏数据之前先清理字符串是每个做日志解析的人都会遇到的常规操作。4. 常见问题与排查技巧实录4.1 YYYY与yyyy害我在跨年周翻车这个坑我必须要放到最前面讲因为它的“隐蔽性”极高而且只在每年元旦前后那几天爆发。有一个老业务系统在2024年12月29日生成的订单报表里年份显示成了2025。客户为此专门提了工单。我拿到代码一看格式化pattern写的是YYYY-MM-dd而不是yyyy-MM-dd。这两者有什么区别yyyy是自然年也就是1月到12月对应的年份YYYY是“Week Year”它属于ISO周日期系统用于与“一年中的第几周”配套使用。在ISO规则里一年的第一周是包含该年首个星期四的那一周。这就导致2024年最后几天可能已经被划进2024年的第52周而这一周对应的“Week Year”已经是2025了。简单说YYYY-MM-dd格式化2024-12-31极大概率会输出2025-12-31。年份对、日期对但两者拼在一起是个不存在的错误日期。所以我的规则特别简单做日期展示永远只用yyyy不要用YYYY。如果确实需要算“哪一年第几周”这种业务再去用WeekFields和YYYY。4.2 MM和mm差一个字线上时间全乱套有一次排查导出的Excel数据发现所有时间的小时数变成了月份比如下午3点变成了2025-06-01 15:00:00里的03:00。一开始怀疑是时区问题结果查到最后发现格式化pattern写的是yyyy-mm-dd HH:mm:ss。这个pattern里第一个mm代表分钟而不是月份于是格式化出来的字符串就变成了2025-06-01 03:00:00——注意这里不是“下午3点被格式化成03”而是这个字符串的“月”位置被塞进了一个分钟数1月份被格式成了06当1月份时MM是01mm也是01所以月初月份和分钟恰好相同能掩蔽这个问题但12月时MM12mm可能是00到59就会输出类似的离奇结果。排查思路非常朴素先确认数据库原始值有没有问题如果数据库里存的时间是对的那就是格式化环节出错了。然后逐个检查pattern字母特别注意大小写。MM是月mm是分HH是24小时制小时hh是12小时制小时dd是日DD是一年中的第几天。把这些对照表记牢可以少走很多弯路。我顺手整理了一份最常用的pattern字母对照表贴在这里供参考Pattern字母含义示例输出yyyy四位年份2025yy两位年份25MM两位月份06M月份不补零6dd两位日期01HH24小时制小时14hh12小时制小时02mm分钟30ss秒05SSS毫秒123E星期简称周日EEEE星期全称星期日XXXISO时区偏移08:004.3 SimpleDateFormat并发错乱偶发且恶心前面已经详细说过SimpleDateFormat线程不安全的问题这里补一个具体复现方法。假设有一个共享的SimpleDateFormat实例开两个线程分别格式化2025-01-01和2025-06-30你有机会看到类似2025-00-30这种日期。原因是Calendar对象的字段被两个线程互相覆盖。这种bug最大的特点是没有规律在低并发场景可能永远不触发一旦高峰期流量上来就会偶发而且难以稳定复现。排查的时候光看代码很难一眼定位所以最好的策略就是防患于未然——不要共享SimpleDateFormat不要共享Calendar。如果你在面试中遇到“SimpleDateFormat线程安全问题怎么解决”这种Java面试题标准的回答框架是先说明原因SimpleDateFormat内部依赖可变共享状态Calendar再给出三个方案分别是加锁、ThreadLocal、改用DateTimeFormatter最后表达个人倾向新代码直接用不可变且线程安全的DateTimeFormatter。这套回答在面试里属于高分答案因为既讲了原理又给了对比和选型思路。4.4 解析时松散模式导致的假数据还有一个让新手困惑的问题SimpleDateFormat.parse默认是宽松解析Lenient也就是允许2025-02-30这种不存在的日期被“自动修正”成2025-03-02。很多人在做日期校验时踩过这个坑用户输入了一个明显不合法的日期程序却接受了还在后续流程里生成了错误数据。解决方法是把SimpleDateFormat设置为strict模式SimpleDateFormat sdf new SimpleDateFormat(yyyy-MM-dd); sdf.setLenient(false);设置之后parse(2025-02-30)会直接抛出ParseException程序立刻就能得知输入非法。新API里对应的做法是DateTimeFormatter formatter DateTimeFormatter.ofPattern(yyyy-MM-dd).withResolverStyle(ResolverStyle.STRICT);ResolverStyle有三种STRICT、SMART、LENIENT。默认是SMART它会对2025-02-30报错但允许2025-02-28这种整体表现比较合理。如果做合规要求特别严格的解析就用STRICT。顺带说一句用redisson或Spring这类框架处理时间参数时很多框架内部也是按严格模式来解析的所以用户从前端传入的字符串非法时后台服务能第一时间报参数错误这个机制和这里说的原理是相通的。4.5 时区问题同一个字符串读出来差8小时最后聊一个地域色彩极强的坑。有一回一个在新加坡机房部署的服务把2025-06-01 10:30:00通过LocalDateTime.parse解析然后转成Date再传给一个老接口老接口拿到Date后调用旧工具类格式化成字符串发现时间变成了2025-06-01 18:30:00。两边都没错问题出在默认时区不同。在新加坡机房JVM默认时区是Asia/SingaporeUTC8LocalDateTime表示“没有时区的本地时间”它只是年月日时分秒的容器。当它被atZone(ZoneId.systemDefault())转换成Instant时会被按照当前默认时区解释成绝对时间点。如果服务器时区和字符串原本所代表的时区不一致这十分钟就会被“平移”掉对不上。这里的原则是解析时首先要想清楚字符串的时区语义是什么。如果确定是东八区的时间而服务器跑在UTC时区就要显式指定ZoneId.of(Asia/Shanghai)不能依赖systemDefault()。反过来格式化输出的时候也要先明确目标时区再决定是用ZoneId.systemDefault()还是固定时区。现在很多团队在这个问题上的统一做法是接口交互一律用ISO8601带偏移格式数据库存储一律UTC展示层才按照用户时区做格式化。这套规则可以从源头上消灭八小时误差问题。4.6 常见问题速查表我把文章里所有提到的问题统一收进一张表方便各位存档查阅问题现象根本原因解决思路跨年附近日期年份错误pattern误用YYYYWeek Year一律使用小写yyyy月份显示成分钟数MM错写成mm熟记pattern字母大小写含义并发下时间错乱、字段串位共享SimpleDateFormat实例ThreadLocal包裹或改用DateTimeFormatter非法日期被自动修正宽松解析Lenient默认开启setLenient(false)或ResolverStyle.STRICT服务器时区不同导致时间偏移依赖JVM默认时区解析/格式化显式指定ZoneId统一UTC或固定业务时区字符串与pattern无法匹配多空格、多字符、格式不一致先做字符串清洗再解析Date与LocalDateTime转换出错没有经过Instant中转date.toInstant().atZone(zone)或反方向Date.from(instant)毫秒数显示异常Instant精度高于Date格式化前truncatedTo(ChronoUnit.MILLIS)这张表里的每一项都是我或者身边同事在真实项目中踩过的没有一条是我从文档里空想出来的。你在自己项目里排查日期问题时优先对着表格一个个排除大概率能快速定位到症结。我个人现在的习惯是凡是新写的格式化相关代码一律使用DateTimeFormatter和java.time凡是接手的遗留代码先查有没有静态共享的SimpleDateFormat凡是涉及外部接口传参统一ISO8601带偏移格式。这套习惯帮我少加了很多班也希望能帮你省下一些本来要花在排查上的时间。