Java毫秒转时间字符串教程

1. 引言：毫秒值转换为可读字符串的需求

在Java应用程序开发中，我们经常会遇到需要展示时间持续时长的情况。通常，系统内部会以毫秒（long类型）来存储这些持续时间。然而，直接显示一个巨大的毫秒数值对用户来说并不直观。例如，302000毫秒远不如“5 minutes 2 seconds”或“2 hours”来得清晰易懂。手动将毫秒值拆分为天、小时、分钟、秒并进行字符串拼接，不仅代码量大，而且容易出错，尤其是在处理零值或需要灵活格式化时。

2. 传统方法的局限性

许多开发者可能会尝试使用java.util.concurrent.TimeUnit或自定义逻辑来计算并格式化时间。例如：

long milliseconds = 302000; // 5 minutes and 2 seconds
long seconds = milliseconds / 1000;
long minutes = seconds / 60;
long remainingSeconds = seconds % 60;

String readableString = minutes + " minutes " + remainingSeconds + " seconds";
System.out.println(readableString); // 输出：5 minutes 2 seconds

这种方法在简单场景下尚可接受，但如果需要包含小时、天，并处理前导/后导零元素的抑制（例如，当小时数为0时不显示“0 hours”），代码将会变得冗长且难以维护。例如，要实现“2 hours”而不是“2 hours 0 minutes 0 seconds”，就需要复杂的条件判断。

3. 使用 DurationFormatUtils.formatDurationWords 的高效方案

为了解决上述问题，Apache Commons Lang库提供了一个非常实用的工具类org.apache.commons.lang3.time.DurationFormatUtils，其中的formatDurationWords方法能够简洁高效地将毫秒值转换为人类可读的字符串。

3.1 引入依赖

首先，确保你的项目中已引入Apache Commons Lang库。如果你使用Maven，可以在pom.xml中添加以下依赖：

    org.apache.commons
    commons-lang3
    3.12.0 

如果你使用Gradle，则在build.gradle中添加：

implementation 'org.apache.commons:commons-lang3:3.12.0' // 使用最新稳定版本

3.2 formatDurationWords 方法详解

formatDurationWords方法签名如下：

public static String formatDurationWords(long durationMillis, boolean suppressLeadingZeroElements, boolean suppressTrailingZeroElements)

• durationMillis: 要格式化的持续时间，以毫秒为单位。
• suppressLeadingZeroElements: 如果为true，则抑制前导零元素。例如，如果持续时间不足一天，则不会显示“0 days”。
• suppressTrailingZeroElements: 如果为true，则抑制后导零元素。例如，如果持续时间只有小时而没有分钟和秒，则不会显示“0 minutes 0 seconds”。

该方法返回的字符串格式通常为“X days Y hours Z minutes A seconds”，并根据suppressLeadingZeroElements和suppressTrailingZeroElements参数调整输出。

3.3 示例代码

以下是如何使用formatDurationWords的示例：

import org.apache.commons.lang3.time.DurationFormatUtils;

public class DurationConverter {

    public static void main(String[] args) {
        long milliseconds1 = 302000; // 5 minutes 2 seconds
        long milliseconds2 = 7200000; // 2 hours
        long milliseconds3 = 259200000; // 3 days
        long milliseconds4 = 123456789; // 1 day 10 hours 17 minutes 36 seconds
        long milliseconds5 = 0; // 0 seconds

        // 示例1：抑制前导和后导零元素
        // 期望输出: "5 minutes 2 seconds"
        String result1 = DurationFormatUtils.formatDurationWords(milliseconds1, true, true);
        System.out.println("302000 ms -> " + result1);

        // 示例2：仅有小时，抑制前导和后导零元素
        // 期望输出: "2 hours"
        String result2 = DurationFormatUtils.formatDurationWords(milliseconds2, true, true);
        System.out.println("7200000 ms -> " + result2);

        // 示例3：仅有天，抑制前导和后导零元素
        // 期望输出: "3 days"
        String result3 = DurationFormatUtils.formatDurationWords(milliseconds3, true, true);
        System.out.println("259200000 ms -> " + result3);

        // 示例4：包含天、小时、分钟、秒
        // 期望输出: "1 day 10 hours 17 minutes 36 seconds"
        String result4 = DurationFormatUtils.formatDurationWords(milliseconds4, true, true);
        System.out.println("123456789 ms -> " + result4);

        // 示例5：零毫秒
        // 期望输出: "0 seconds" (因为所有元素都是0，且suppressTrailingZeroElements为true，会显示最小单位的0)
        String result5 = DurationFormatUtils.formatDurationWords(milliseconds5, true, true);
        System.out.println("0 ms -> " + result5);

        // 示例6：不抑制前导零元素（仅为演示，通常不这么用）
        // 期望输出: "0 days 0 hours 5 minutes 2 seconds"
        String result6 = DurationFormatUtils.formatDurationWords(milliseconds1, false, true);
        System.out.println("302000 ms (no leading suppress) -> " + result6);
    }
}

输出结果:

302000 ms -> 5 minutes 2 seconds
7200000 ms -> 2 hours
259200000 ms -> 3 days
123456789 ms -> 1 day 10 hours 17 minutes 36 seconds
0 ms -> 0 seconds
302000 ms (no leading suppress) -> 0 days 0 hours 5 minutes 2 seconds

从输出可以看出，当suppressLeadingZeroElements和suppressTrailingZeroElements都设置为true时，方法会智能地生成最简洁且易读的字符串，自动省略不必要的零元素。

4. 注意事项与总结

• 依赖管理: 确保正确引入Apache Commons Lang库的依赖。
• 版本兼容性: DurationFormatUtils在Commons Lang 3.x版本中可用。如果你的项目仍在使用Commons Lang 2.x，可能需要升级或寻找其他解决方案。
• 输出格式: formatDurationWords的输出格式是固定的“X days Y hours Z minutes A seconds”模式。如果你需要高度自定义的格式（例如，使用逗号分隔，或者不同的单词），可能需要结合DurationFormatUtils.formatDuration方法和DateFormatUtils或其他自定义逻辑。
• 本地化: formatDurationWords生成的字符串是英文的。如果你的应用程序需要支持多语言，你需要考虑在UI层进行本地化，或者寻找支持本地化的时间格式库。

通过使用DurationFormatUtils.formatDurationWords，开发者可以显著简化Java中毫秒值到人类可读字符串的转换过程，提高代码的整洁性和可维护性，同时提供更友好的用户体验。