111

snailmall-user-service/src/main/java/com/njupt/swg/common/utils/DateTimeUtil.java

@@ -13,21 +13,45 @@ import java.util.Date;
  * @DESC 时间转换的工具类
  */
 public class DateTimeUtil {
+    // 这里的注释表明该工具类可能使用了joda-time库来进行日期时间相关的操作，joda-time是一个功能强大的处理日期、时间的第三方库，相比于Java原生的日期时间API，它提供了更方便、易用且功能丰富的方法来操作日期时间数据。
     //joda-time
 
+    // 以下注释说明了这个工具类主要实现的两个功能方向，即把字符串类型的日期时间表示转换为Date类型（str->Date），以及把Date类型的日期时间转换为字符串类型（Date->str），方便在不同的业务场景中对日期时间数据进行格式转换，以满足存储、展示等各种需求。
     //str->Date
     //Date->str
+    // 定义一个公共静态常量字符串STANDARD_FORMAT，用于指定一种标准的日期时间格式，这里设置为"yyyy-MM-dd HH:mm:ss"，也就是年-月-日 时:分:秒的格式，在一些方法中如果没有指定具体的日期时间格式参数时，会默认使用这个标准格式来进行日期时间和字符串之间的转换操作。
     public static final String STANDARD_FORMAT = "yyyy-MM-dd HH:mm:ss";
 
 
 
+    /**
+     * 这个静态方法用于将给定的日期时间字符串（dateTimeStr）按照指定的格式（formatStr）转换为Java的Date类型对象。
+     * 它借助joda-time库中的DateTimeFormatter和DateTime类来实现转换功能。
+     * 首先，根据传入的格式字符串（formatStr）创建一个DateTimeFormatter对象，这个对象用于解析指定格式的日期时间字符串。
+     * 然后，使用创建好的DateTimeFormatter对象去解析传入的日期时间字符串（dateTimeStr），得到一个DateTime类型的对象，DateTime类型是joda-time库中对日期时间的一种表示形式，功能更丰富、操作更便捷。
+     * 最后，将DateTime对象转换为Java原生的Date类型对象并返回，这样就完成了从特定格式字符串到Date类型的转换，方便后续在需要使用Date类型日期时间数据的地方进行使用，比如存储到数据库等操作。
+     *
+     * @param dateTimeStr 要转换的日期时间字符串，其格式需要与传入的formatStr参数指定的格式相匹配，否则会解析失败抛出异常。
+     * @param formatStr 用于指定日期时间字符串的格式，例如"yyyy-MM-dd HH:mm:ss"等，根据实际传入的格式来解析对应的日期时间字符串。
+     * @return 返回解析后的Java Date类型对象，如果解析过程中出现问题则会抛出相应的异常（由joda-time库的解析逻辑决定）。
+     */
     public static Date strToDate(String dateTimeStr, String formatStr){
         DateTimeFormatter dateTimeFormatter = DateTimeFormat.forPattern(formatStr);
         DateTime dateTime = dateTimeFormatter.parseDateTime(dateTimeStr);
         return dateTime.toDate();
     }
 
-    public static String dateToStr(Date date,String formatStr){
+    /**
+     * 此静态方法用于将给定的Java Date类型的日期时间对象转换为指定格式的字符串表示形式。
+     * 如果传入的Date对象为null，则直接返回一个空字符串（StringUtils.EMPTY，通常是工具类中定义的表示空字符串的常量），避免出现空指针异常等问题。
+     * 若Date对象不为null，则先基于传入的Date对象创建一个joda-time库中的DateTime对象，DateTime类提供了更方便的格式化输出等功能。
+     * 最后，使用DateTime对象的toString方法，按照传入的格式字符串（formatStr）将日期时间转换为相应格式的字符串并返回，这样就可以方便地将Date类型的日期时间以期望的格式展示出来，比如在界面上显示给用户或者存储到文本文件等场景中使用。
+     *
+     * @param date 要转换的Java Date类型的日期时间对象，如果为null则返回空字符串。
+     * @param formatStr 用于指定转换后的字符串的日期时间格式，例如"yyyy-MM-dd HH:mm:ss"等，根据这个格式将Date对象转换为相应格式的字符串。
+     * @return 返回转换后的日期时间字符串，如果传入的Date对象为null则返回空字符串，否则返回按照指定格式转换后的字符串。
+     */
+    public static String dateToStr(Date date, String formatStr){
         if(date == null){
             return StringUtils.EMPTY;
         }
@@ -35,6 +59,13 @@ public class DateTimeUtil {
         return dateTime.toString(formatStr);
     }
 
+    /**
+     * 这个静态方法用于将给定的日期时间字符串（dateTimeStr）按照类中定义的标准格式（STANDARD_FORMAT，即"yyyy-MM-dd HH:mm:ss"）转换为Java的Date类型对象。
+     * 其实现逻辑与strToDate(String dateTimeStr, String formatStr)方法类似，只是这里固定使用了类中定义好的标准格式来创建DateTimeFormatter对象进行字符串解析，无需外部传入格式参数，适用于那些明确知道日期时间字符串是按照标准格式编写的情况，简化了调用方式，方便在统一格式要求的场景下快速进行转换操作。
+     *
+     * @param dateTimeStr 要转换的日期时间字符串，其格式需要符合类中定义的标准格式（"yyyy-MM-dd HH:mm:ss"），否则会解析失败抛出异常。
+     * @return 返回解析后的Java Date类型对象，如果解析过程中出现问题则会抛出相应的异常（由joda-time库的解析逻辑决定）。
+     */
     //固定好格式
     public static Date strToDate(String dateTimeStr){
         DateTimeFormatter dateTimeFormatter = DateTimeFormat.forPattern(STANDARD_FORMAT);
@@ -42,6 +73,13 @@ public class DateTimeUtil {
         return dateTime.toDate();
     }
 
+    /**
+     * 此静态方法用于将给定的Java Date类型的日期时间对象转换为类中定义的标准格式（STANDARD_FORMAT，即"yyyy-MM-dd HH:mm:ss"）的字符串表示形式。
+     * 实现逻辑与dateToStr(Date date, String formatStr)方法类似，当传入的Date对象为null时返回空字符串，不为null时基于该Date对象创建DateTime对象，然后按照标准格式将其转换为字符串并返回，方便在统一格式要求下将Date类型的日期时间转换为字符串进行展示等操作。
+     *
+     * @param date 要转换的Java Date类型的日期时间对象，如果为null则返回空字符串。
+     * @return 返回转换后的日期时间字符串，按照类中定义的标准格式（"yyyy-MM-dd HH:mm:ss"）进行转换，如果传入的Date对象为null则返回空字符串。
+     */
     public static String dateToStr(Date date){
         if(date == null){
             return StringUtils.EMPTY;
@@ -50,6 +88,15 @@ public class DateTimeUtil {
         return dateTime.toString(STANDARD_FORMAT);
     }
 
+    /**
+     * 这个静态方法用于将给定的Java Date类型的日期时间对象转换为时间戳（从1970年1月1日00:00:00 UTC到指定日期时间的毫秒数）。
+     * 如果传入的Date对象为null，则直接返回null，避免后续操作出现空指针异常等问题。
+     * 对于不为null的Date对象，先创建一个SimpleDateFormat对象，指定其格式为类中常用的标准格式（"yyyy-MM-dd HH:mm:ss"），用于将Date对象转换为字符串形式，再通过SimpleDateFormat的parse方法将该字符串解析为Date类型（这里虽然看起来多此一举，但实际上是为了获取到正确格式对应的时间戳，因为直接从Date对象获取时间戳可能不符合期望的格式要求），最后获取解析后的Date对象对应的时间戳（通过getTime方法获取到从1970年1月1日00:00:00 UTC到该日期时间的毫秒数）并返回，方便在一些需要使用时间戳进行时间比较、存储等场景中使用。
+     *
+     * @param date 要转换的Java Date类型的日期时间对象，如果为null则返回null。
+     * @return 返回对应的时间戳（以毫秒为单位），如果传入的Date对象为null则返回null，否则返回根据指定格式转换后的日期时间对应的时间戳。
+     * @throws ParseException 如果在使用SimpleDateFormat的parse方法解析字符串时出现格式不匹配等解析问题，则会抛出该异常，调用者需要进行相应的异常处理。
+     */
     //Date -> 时间戳
     public static Long dateToChuo(Date date) throws ParseException {
         if(date == null){
@@ -59,10 +106,18 @@ public class DateTimeUtil {
         return format.parse(String.valueOf(date)).getTime();
     }
 
+    /**
+     * 这是一个Java程序的主方法，通常用于测试类中的其他方法或者进行一些简单的示例操作。
+     * 在这里，它创建了一个SimpleDateFormat对象，指定格式为"yyyy-MM-dd HH:mm:ss"，然后定义了一个日期时间字符串"1970-01-06 11:45:55"，通过SimpleDateFormat的parse方法将该字符串解析为Date类型对象，最后打印出该Date对象对应的时间戳（通过getTime方法获取），主要用于验证日期时间转换为时间戳的功能是否正常，方便在开发过程中进行简单的自测等操作。
+     * 不过需要注意，在实际应用中，这种测试代码可以放在单元测试类中会更加规范，而不是直接放在工具类的主方法里，但这里可能只是为了简单快速地验证一些逻辑。
+     *
+     * @param args 命令行参数，在这个简单示例中并没有实际使用到。
+     * @throws ParseException 如果在使用SimpleDateFormat的parse方法解析字符串时出现格式不匹配等解析问题，则会抛出该异常，这里由于是简单测试示例，没有做更详细的异常处理，只是按照Java主方法的基本要求声明抛出该异常。
+     */
     public static void main(String[] args) throws ParseException {
         SimpleDateFormat format =   new SimpleDateFormat( "yyyy-MM-dd HH:mm:ss" );
         String time="1970-01-06 11:45:55";
         Date date = format.parse(time);
         System.out.print("Format To times:"+date.getTime());
     }
-}
+}