diff --git a/tamguo-common/src/main/java/com/tamguo/common/utils/DateUtils.java b/tamguo-common/src/main/java/com/tamguo/common/utils/DateUtils.java index e89ff34..3ed911f 100644 --- a/tamguo-common/src/main/java/com/tamguo/common/utils/DateUtils.java +++ b/tamguo-common/src/main/java/com/tamguo/common/utils/DateUtils.java @@ -5,9 +5,21 @@ import java.text.SimpleDateFormat; import java.util.Calendar; import java.util.Date; +// DateUtils类用于提供一系列与日期处理相关的实用方法，包括日期格式化、日期解析、日期之间的差值计算以及在日期上进行增减操作等功能，方便在不同的业务场景中对日期进行操作和处理。 public class DateUtils { + + // 定义默认的日期格式字符串，格式为"yyyy-MM-dd"，在一些方法中若未指定具体格式时，会使用该默认格式进行日期相关的操作。 public static final String DEFAULT_PATTERN = "yyyy-MM-dd"; + /** + * 获取距离当前日期指定天数后的日期字符串，可指定日期格式。 + * 通过Calendar类获取当前日期实例，然后根据传入的天数参数对日期进行增减操作（正数表示增加天数，负数表示减少天数）， + * 最后使用指定的日期格式（若未传入格式则使用默认格式）将调整后的日期格式化为字符串并返回。 + * + * @param day 表示要在当前日期基础上增加或减少的天数，例如传入1表示获取明天的日期字符串，传入-1表示获取昨天的日期字符串。 + * @param pattern 用于指定日期格式化的格式字符串，如"yyyy-MM-dd HH:mm:ss"等，若为null或不传则使用默认格式（DEFAULT_PATTERN）。 + * @return 根据指定格式格式化后的日期字符串，代表距离当前日期指定天数后的日期。 + */ public static String getOneDayFromNow(int day, String pattern) { Calendar cal = Calendar.getInstance(); cal.setTime(new Date()); @@ -16,23 +28,30 @@ public class DateUtils { return sdf.format(cal.getTime()); } + /** + * 获取距离当前日期指定天数后的日期字符串，使用默认日期格式（"yyyy-MM-dd"）进行格式化。 + * 该方法是对getOneDayFromNow(int day, String pattern)方法的重载，在未传入日期格式参数时，默认调用使用默认格式的版本。 + * + * @param day 表示要在当前日期基础上增加或减少的天数，例如传入1表示获取明天的日期字符串，传入-1表示获取昨天的日期字符串。 + * @return 根据默认格式（"yyyy-MM-dd"）格式化后的日期字符串，代表距离当前日期指定天数后的日期。 + */ public static String getOneDayFromNow(int day) { return DateUtils.getOneDayFromNow(day, DEFAULT_PATTERN); } /** - * 计算两个日期之间相差的天数 - * - * @param smdate - * 较小的时间 - * @param bdate - * 较大的时间 - * @return 相差天数 - * @throws ParseException - * @throws java.text.ParseException + * 计算两个日期之间相差的天数。 + * 首先将传入的两个日期按照"yyyy-MM-dd"格式进行格式化并解析，确保日期的时间部分被重置为当天的起始时间（00:00:00）， + * 然后分别获取两个日期对应的时间戳（毫秒数），通过计算时间戳差值并换算为天数（除以一天对应的毫秒数，即1000 * 3600 * 24）， + * 最后将差值转换为整数并返回，表示两个日期之间相差的天数。 + * 注意，该方法会抛出ParseException异常，需要调用者进行处理，若在解析日期字符串过程中出现异常，将按照异常处理逻辑进行处理（当前代码中是打印堆栈信息并返回可能不正确的结果）。 + * + * @param smdate 表示较小的时间，即较早的日期，类型为Date，例如历史记录中的较早时间点对应的日期对象。 + * @param bdate 表示较大的时间，即较晚的日期，类型为Date，例如当前时间或者更晚的时间点对应的日期对象。 + * @return 两个日期之间相差的天数，正数表示bdate比smdate晚的天数，负数表示bdate比smdate早的天数。 + * @throws ParseException 如果在解析日期字符串过程中出现格式不匹配等问题，会抛出此异常，需要调用者进行捕获处理。 */ - public static int daysBetween(Date smdate, Date bdate) - throws ParseException { + public static int daysBetween(Date smdate, Date bdate) throws ParseException { SimpleDateFormat sdf = new SimpleDateFormat("yyyy-MM-dd"); smdate = sdf.parse(sdf.format(smdate)); bdate = sdf.parse(sdf.format(bdate)); @@ -46,83 +65,91 @@ public class DateUtils { return Integer.parseInt(String.valueOf(between_days)); } + // 以下是main方法，用于简单测试daysBetween方法，不过当前传入的参数为null，实际运行可能会出现空指针异常等问题，正常使用时应传入有效的日期对象进行测试。 public static void main(String[] args) throws ParseException { System.out.println(daysBetween(null, null)); } + // 定义一系列常用的日期格式字符串常量，方便在不同的日期格式化场景中使用，以下是各常量对应的格式说明： + /** - * 英文简写（默认）如：2010-12-01 + * 英文简写（默认）日期格式字符串，如：2010-12-01，表示年月日的格式，常用于简洁展示日期的场景。 */ public static String FORMAT_SHORT = "yyyy-MM-dd"; /** - * 英文全称 如：2010-12-01 23:15:06 + * 英文全称日期格式字符串，如：2010-12-01 23:15:06，表示包含年月日时分秒的完整日期时间格式，用于需要精确展示日期和时间的情况。 */ public static String FORMAT_LONG = "yyyy-MM-dd HH:mm:ss"; /** - * 精确到毫秒的完整时间 如：yyyy-MM-dd HH:mm:ss.S + * 精确到毫秒的完整时间格式字符串，如：yyyy-MM-dd HH:mm:ss.S，表示包含年月日时分秒以及毫秒的日期时间格式，适用于对时间精度要求较高的场景，比如记录详细的操作时间戳等。 */ public static String FORMAT_FULL = "yyyy-MM-dd HH:mm:ss.S"; /** - * 中文简写 如：2010年12月01日 + * 中文简写日期格式字符串，如：2010年12月01日，以中文形式展示年月日，符合中文习惯的简洁日期表示方式，多用于面向中文用户的界面展示等场景。 */ public static String FORMAT_SHORT_CN = "yyyy年MM月dd"; /** - * 中文全称 如：2010年12月01日 23时15分06秒 + * 中文全称日期格式字符串，如：2010年12月01日 23时15分06秒，用中文完整地展示了年月日时分秒，适用于在中文环境下需要详细展示日期时间的情况。 */ public static String FORMAT_LONG_CN = "yyyy年MM月dd日 HH时mm分ss秒"; /** - * 精确到毫秒的完整中文时间 + * 精确到毫秒的完整中文时间格式字符串，如：yyyy年MM月dd日 HH时mm分ss秒SSS毫秒，以中文形式完整展示包含毫秒的日期时间信息，用于对时间精度有要求且面向中文用户的场景。 */ public static String FORMAT_FULL_CN = "yyyy年MM月dd日 HH时mm分ss秒SSS毫秒"; /** - * 获得默认的 date pattern + * 获得默认的日期格式字符串，当前默认返回英文全称格式（"yyyy-MM-dd HH:mm:ss"），用于在一些需要默认格式进行日期操作的方法中获取格式信息。 + * + * @return 默认的日期格式字符串，类型为String，例如"yyyy-MM-dd HH:mm:ss"。 */ public static String getDatePattern() { return FORMAT_LONG; } /** - * 根据预设格式返回当前日期 - * - * @return + * 根据预设的默认日期格式（当前为"yyyy-MM-dd HH:mm:ss"）返回当前日期的字符串表示形式。 + * 内部调用了format(Date date)方法，将当前系统时间对应的Date对象按照默认格式进行格式化并返回格式化后的日期时间字符串。 + * + * @return 当前日期按照默认格式格式化后的字符串，例如"2024-12-15 12:30:00"（具体取决于当前系统时间）。 */ public static String getNow() { return format(new Date()); } /** - * 根据用户格式返回当前日期 - * - * @param format - * @return + * 根据用户指定的日期格式返回当前日期的字符串表示形式。 + * 通过调用format(Date date, String pattern)方法，将当前系统时间对应的Date对象按照传入的用户指定格式进行格式化，并返回格式化后的日期时间字符串。 + * + * @param format 用户指定的日期格式字符串，例如"yyyy-MM-dd"或者"yyyy年MM月dd日"等，用于决定如何格式化日期。 + * @return 当前日期按照用户指定格式格式化后的字符串，例如按照"yyyy-MM-dd"格式可能返回"2024-12-15"等（具体取决于当前系统时间）。 */ public static String getNow(String format) { return format(new Date(), format); } /** - * 使用预设格式格式化日期 - * - * @param date - * @return + * 使用预设的默认日期格式（当前为"yyyy-MM-dd HH:mm:ss"）对传入的日期对象进行格式化，返回格式化后的日期时间字符串。 + * 内部调用了format(Date date, String pattern)方法，并传入默认格式作为参数来实现日期的格式化操作。 + * + * @param date 要进行格式化的日期对象，代表一个具体的日期和时间点，例如通过new Date()获取的当前系统时间对应的日期对象。 + * @return 按照预设格式格式化后的日期字符串，例如"2024-12-15 12:30:00"（具体取决于传入的日期对象）。 */ public static String format(Date date) { return format(date, getDatePattern()); } /** - * 使用用户格式格式化日期 - * - * @param date - * 日期 - * @param pattern - * 日期格式 - * @return + * 使用用户指定的日期格式对传入的日期对象进行格式化，返回格式化后的日期时间字符串。 + * 首先判断传入的日期对象是否为null，如果不为null，则创建对应的SimpleDateFormat对象（使用传入的格式字符串）， + * 然后通过该对象的format方法将日期对象格式化为指定格式的字符串并返回；若日期对象为null，则返回空字符串。 + * + * @param date 要进行格式化的日期对象，类型为Date，代表一个具体的日期和时间点，例如通过new Date()获取的当前系统时间对应的日期对象。 + * @param pattern 用户指定的日期格式字符串，例如"yyyy-MM-dd"或者"yyyy年MM月dd日"等，用于决定如何格式化日期。 + * @return 按照用户指定格式格式化后的日期字符串，例如按照"yyyy-MM-dd"格式对某个日期对象格式化后可能返回"2024-12-15"等（具体取决于传入的日期对象和格式）；若date为null则返回空字符串。 */ public static String format(Date date, String pattern) { String returnValue = ""; - if (date != null) { + if (date!= null) { SimpleDateFormat df = new SimpleDateFormat(pattern); returnValue = df.format(date); } @@ -130,13 +157,13 @@ public class DateUtils { } /** - * 使用用户格式格式化时间戳 - * - * @param timestamp - * 时间戳 - * @param pattern - * 日期格式 - * @return + * 使用用户指定的日期格式对传入的时间戳字符串（表示从1970年1月1日0时0分0秒到某个时间点的毫秒数的字符串表示形式）进行格式化，返回格式化后的日期时间字符串。 + * 先将时间戳字符串转换为对应的Date对象（通过Long.parseLong方法将字符串转换为长整型的时间戳数值，再以此创建Date对象）， + * 然后使用指定的日期格式通过SimpleDateFormat对象将该Date对象格式化为相应格式的字符串并返回。 + * + * @param timestamp 表示时间戳的字符串，例如"1672809600000"（对应某个具体时间的毫秒数表示），需要能够正确转换为长整型数值的字符串形式。 + * @param pattern 用户指定的日期格式字符串，例如"yyyy-MM-dd"或者"yyyy年MM月dd日"等，用于决定如何格式化日期。 + * @return 按照用户指定格式格式化后的日期字符串，例如按照"yyyy-MM-dd"格式对某个时间戳对应的日期进行格式化后可能返回"2024-12-15"等（具体取决于传入的时间戳和格式）。 */ public static String format(String timestamp, String pattern) { SimpleDateFormat sdf = new SimpleDateFormat(pattern); @@ -144,24 +171,24 @@ public class DateUtils { } /** - * 使用预设格式提取字符串日期 - * - * @param strDate - * 日期字符串 - * @return + * 使用预设的默认日期格式（当前为"yyyy-MM-dd HH:mm:ss"）对传入的日期字符串进行解析，将其转换为对应的Date对象。 + * 内部调用了parse(String strDate, String pattern)方法，并传入默认格式作为参数来实现日期字符串的解析操作，若解析出现异常会按照异常处理逻辑进行处理（当前是打印堆栈信息并返回null）。 + * + * @param strDate 表示日期的字符串，例如"2024-12-15"或者"2024-12-15 12:30:00"等，需要符合默认格式要求，否则会解析失败。 + * @return 解析后的Date对象，如果解析过程中出现异常（如格式不匹配等）则返回null。 */ public static Date parse(String strDate) { return parse(strDate, getDatePattern()); } /** - * 使用用户格式提取字符串日期 - * - * @param strDate - * 日期字符串 - * @param pattern - * 日期格式 - * @return + * 使用用户指定的日期格式对传入的日期字符串进行解析，将其转换为对应的Date对象。 + * 通过创建对应的SimpleDateFormat对象（使用传入的格式字符串），然后调用其parse方法对日期字符串进行解析操作， + * 若解析出现异常（如格式不匹配等），会打印异常堆栈信息，并返回null，以便调用者进行相应的错误处理。 + * + * @param strDate 表示日期的字符串，例如"2024-12-15"或者"2024年12月15日"等，需要符合传入的格式要求，否则会解析失败。 + * @param pattern 用户指定的日期格式字符串，例如"yyyy-MM-dd"或者"yyyy年MM月dd日"等，用于解析日期字符串。 + * @return 解析后的Date对象，如果解析过程中出现异常（如格式不匹配等）则返回null。 */ public static Date parse(String strDate, String pattern) { SimpleDateFormat df = new SimpleDateFormat(pattern); @@ -174,13 +201,13 @@ public class DateUtils { } /** - * 在日期上增加数个整月 - * - * @param date - * 日期 - * @param n - * 要增加的月数 - * @return + * 在给定的日期基础上增加指定的月数，返回增加后的日期对象。 + * 通过Calendar类获取给定日期对应的实例，然后使用其add方法按照月为单位进行日期的增减操作（传入的参数n为正数表示增加月数，负数表示减少月数）， + * 最后返回调整后的日期对象，代表在原日期基础上增加或减少若干月后的日期。 + * + * @param date 表示要进行操作的基础日期对象，类型为Date，例如某个业务记录中的日期。 + * @param n 表示要增加或减少的月数，类型为整数，例如传入3表示在原日期基础上增加3个月，传入-2表示减少2个月。 + * @return 在原日期基础上增加或减少指定月数后的日期对象。 */ public static Date addMonth(Date date, int n) { Calendar cal = Calendar.getInstance(); @@ -190,13 +217,13 @@ public class DateUtils { } /** - * 在日期上增加天数 - * - * @param date - * 日期 - * @param n - * 要增加的天数 - * @return + * 在给定的日期基础上增加指定的天数，返回增加后的日期对象。 + * 与addMonth方法类似，通过Calendar类获取给定日期对应的实例，然后使用其add方法按照天为单位进行日期的增减操作（传入的参数n为正数表示增加天数，负数表示减少天数）， + * 最后返回调整后的日期对象，代表在原日期基础上增加或减少若干天后的日期。 + * + * @param date 表示要进行操作的基础日期对象，类型为Date，例如某个业务记录中的日期。 + * @param n 表示要增加或减少的天数，类型为整数，例如传入5表示在原日期基础上增加5天，传入-1表示减少1天。 + * @return 在原日期基础上增加或减少指定天数后的日期对象。 */ public static Date addDay(Date date, int n) { Calendar cal = Calendar.getInstance(); @@ -206,7 +233,10 @@ public class DateUtils { } /** - * 获取时间戳 + * 获取当前系统时间按照精确到毫秒的完整时间格式（"yyyy-MM-dd HH:mm:ss.S"）格式化后的字符串表示形式，常用于记录详细的操作时间戳等场景。 + * 通过创建对应的SimpleDateFormat对象（使用预设的精确到毫秒的格式字符串），获取当前系统时间对应的Calendar实例，然后将其格式化为相应格式的字符串并返回。 + * + * @return 当前系统时间按照精确到毫秒的完整时间格式格式化后的字符串，例如"2024-12-15 12:30:00.123"（具体取决于当前系统时间）。 */ public static String getTimeString() { SimpleDateFormat df = new SimpleDateFormat(FORMAT_FULL); @@ -214,6 +244,10 @@ public class DateUtils { return df.format(calendar.getTime()); } + /** + * 从给定的日期对象中提取年份信息，以字符串形式返回。 + * 先调用format(Date date)方法 + /** * 获取日期年份 * @@ -221,16 +255,28 @@ public class DateUtils { * 日期 * @return */ + /** + * 从给定的日期对象中提取年份信息，并以字符串形式返回。 + * 该方法先调用`format(Date date)`方法将传入的日期对象按照默认格式进行格式化，然后截取格式化后字符串的前4个字符， + * 这4个字符刚好对应日期中的年份部分（因为默认格式中年份占前4位，例如 "2024-12-15"），以此获取并返回年份信息。 + * + * @param date 要提取年份信息的日期对象，若为null会在`format`方法中按相应逻辑处理（返回空字符串）。 + * @return 表示年份的字符串，格式如 "2024" 等，取自传入日期对象对应的年份部分。 + */ public static String getYear(Date date) { return format(date).substring(0, 4); } /** - * 按默认格式的字符串距离今天的天数 - * - * @param date - * 日期字符串 - * @return + * 计算按照默认格式（由`getDatePattern`方法指定，当前为 "yyyy-MM-dd HH:mm:ss"）传入的日期字符串距离今天的天数。 + * 实现步骤如下： + * 1. 首先获取当前系统时间对应的毫秒数（通过 `Calendar.getInstance().getTime().getTime()`），记为 `t`。 + * 2. 接着将传入的日期字符串按照默认格式解析成对应的 `Date` 对象，再获取该 `Date` 对象对应的毫秒数（通过 `c.getTime().getTime()`），记为 `t1`。 + * 3. 然后计算两个时间点的毫秒数差值（`t - t1`），将其转换为秒数（除以1000），再进一步转换为天数（除以每小时的秒数3600以及每天的小时数24），最后将结果转换为整数类型返回，得到距离今天的天数。 + * 注意，如果传入的日期字符串无法按照默认格式正确解析，`parse` 方法会返回 `null`，后续操作可能出现异常情况（当前代码逻辑中未做额外处理）。 + * + * @param date 按照默认格式的日期字符串，例如 "2024-12-10"，需要符合默认格式要求，否则解析可能失败。 + * @return 传入日期字符串距离今天（当前系统时间对应的日期）的天数，正数表示传入日期在未来，负数表示传入日期在过去。 */ public static int countDays(String date) { long t = Calendar.getInstance().getTime().getTime(); @@ -241,13 +287,16 @@ public class DateUtils { } /** - * 按用户格式字符串距离今天的天数 - * - * @param date - * 日期字符串 - * @param format - * 日期格式 - * @return + * 计算按照用户指定格式传入的日期字符串距离今天的天数。 + * 具体实现过程如下： + * 1. 先获取当前系统时间对应的毫秒数（通过 `Calendar.getInstance().getTime().getTime()`），赋值给变量 `t`。 + * 2. 随后将传入的按照用户指定格式的日期字符串，通过 `parse(date, format)` 方法解析成对应的 `Date` 对象，再获取该 `Date` 对象对应的毫秒数（通过 `c.getTime().getTime()`），赋值给变量 `t1`。 + * 3. 接着计算两个时间点的毫秒数差值（`t - t1`），先将其转换为秒数（除以1000），再换算为天数（除以每小时的秒数3600以及每天的小时数24），最后把结果转换为整数类型返回，即得到距离今天的天数。 + * 同样要注意，如果传入的日期字符串无法按照指定格式正确解析，`parse` 方法会返回 `null`，后续操作可能出现异常情况（当前代码逻辑中未做额外处理）。 + * + * @param date 日期字符串，例如 "2024年12月10日"，需符合传入的 `format` 参数指定的格式要求，不然解析会失败。 + * @param format 用户指定的日期格式字符串，例如 "yyyy年MM月dd日"，用于解析传入的日期字符串。 + * @return 传入日期字符串距离今天（当前系统时间对应的日期）的天数，正数表示传入日期在未来，负数表示传入日期在过去。 */ public static int countDays(String date, String format) { long t = Calendar.getInstance().getTime().getTime(); @@ -256,19 +305,34 @@ public class DateUtils { long t1 = c.getTime().getTime(); return (int) (t / 1000 - t1 / 1000) / 3600 / 24; } - + + /** + * 根据传入的参数对给定日期进行格式化处理，并返回格式化后的日期字符串。 + * 具体逻辑如下： + * 1. 首先判断传入的日期对象是否为 `null`，若是，则将其设置为当前系统时间对应的新 `Date` 对象（通过 `new Date()`），确保后续操作有有效的日期数据。 + * 2. 接着获取一个 `Calendar` 实例，并将其时间设置为传入的日期对象对应的时间（通过 `cal.setTime(date)`）。 + * 3. 然后根据布尔类型的 `flag` 参数来决定是否对日期进行调整，如果 `flag` 为 `true`，则将日期往前推30天（通过 `cal.add(Calendar.DATE, -30)`）；若 `flag` 为 `false`，则不进行日期的增减操作（通过 `cal.add(Calendar.DATE, 0)`）。 + * 4. 最后使用传入的指定格式字符串创建 `SimpleDateFormat` 对象，将调整后的日期通过该对象格式化为字符串，并返回格式化后的结果。 + * 该方法常用于按照特定格式以及根据一定条件来输出日期字符串的场景，例如根据业务规则展示不同时间区间的日期情况等。 + * + * @param date 要进行格式化处理的日期对象，可以为 `null`，若为 `null` 则使用当前系统时间。 + * @param format 用于指定日期格式化的格式字符串，例如 "yyyy-MM-dd" 等，决定最终返回的日期字符串格式。 + * @param flag 布尔类型参数，用于控制是否对日期进行调整，`true` 表示往前推30天，`false` 表示不调整日期。 + * @param beforeDay 此参数在当前方法逻辑中未使用，可根据业务需求后续调整方法实现时加入相关逻辑（当前代码中无实际作用）。 + * @param nowDay 此参数在当前方法逻辑中未使用，可根据业务需求后续调整方法实现时加入相关逻辑（当前代码中无实际作用）。 + * @return 按照指定格式格式化后的日期字符串，格式取决于传入的 `format` 参数以及是否根据 `flag` 进行了日期调整。 + */ public static String timeFormat(Date date, String format, Boolean flag, int beforeDay, int nowDay) { - if(date == null) { + if (date == null) { date = new Date(); } Calendar cal = Calendar.getInstance(); cal.setTime(date); - if(flag) { - cal.add(Calendar.DATE,-30); + if (flag) { + cal.add(Calendar.DATE, -30); } else { - cal.add(Calendar.DATE,0); + cal.add(Calendar.DATE, 0); } SimpleDateFormat sdf = new SimpleDateFormat(format); return sdf.format(cal.getTime()); - } -} + } \ No newline at end of file