111

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

@@ -13,20 +13,42 @@ import java.util.Date;
  * @DESC 时间转换的工具类
  */
 public class DateTimeUtil {
+    // 这里注释表明代码中使用了joda-time这个日期时间处理的库，它提供了更方便、强大的日期时间操作功能，相比于Java原生的日期时间API在某些方面更易用。
     //joda-time
 
+    // 以下注释说明了这个工具类主要提供的两个功能方向，即把字符串类型的日期时间表示转换为Date类型，以及把Date类型转换为字符串类型的日期时间表示，方便在不同的业务场景下进行日期时间格式的转换操作。
     //str->Date
     //Date->str
+    // 定义了一个静态的常量字符串，用于表示标准的日期时间格式，采用"yyyy-MM-dd HH:mm:ss"这种常见的格式，方便在一些方法中作为默认的格式来进行日期时间的转换操作。
     public static final String STANDARD_FORMAT = "yyyy-MM-dd HH:mm:ss";
 
 
 
+    /**
+     * 将指定格式的字符串类型的日期时间转换为Date类型。
+     * 首先根据传入的格式字符串（formatStr）创建一个DateTimeFormatter对象，这个对象用于定义如何解析传入的日期时间字符串。
+     * 然后使用该DateTimeFormatter对象解析传入的日期时间字符串（dateTimeStr），得到一个DateTime类型的对象，DateTime是joda-time库中的日期时间表示类。
+     * 最后将DateTime对象转换为Java原生的Date类型并返回，这样就完成了从特定格式字符串到Date类型的转换。
+     *
+     * @param dateTimeStr 要转换的字符串类型的日期时间，其格式需要与传入的formatStr参数一致。
+     * @param formatStr   用于指定日期时间字符串的格式，例如"yyyy-MM-dd HH:mm:ss"等格式字符串。
+     * @return 转换后的Date类型的日期时间对象，如果解析出现问题可能会抛出异常（由joda-time库的解析逻辑决定）。
+     */
     public static Date strToDate(String dateTimeStr, String formatStr){
         DateTimeFormatter dateTimeFormatter = DateTimeFormat.forPattern(formatStr);
         DateTime dateTime = dateTimeFormatter.parseDateTime(dateTimeStr);
         return dateTime.toDate();
     }
 
+    /**
+     * 将Date类型的日期时间对象转换为指定格式的字符串表示形式。
+     * 首先判断传入的Date对象是否为null，如果是null则直接返回一个空字符串（StringUtils.EMPTY，可能是自定义的表示空字符串的常量，一般用于避免返回null导致的空指针问题等情况）。
+     * 如果Date对象不为null，则使用它创建一个joda-time库中的DateTime对象，然后调用toString方法并传入指定的格式字符串（formatStr），将Date对象按照指定格式转换为字符串并返回。
+     *
+     * @param date      要转换的Date类型的日期时间对象。
+     * @param formatStr 用于指定转换后的字符串的日期时间格式，例如"yyyy-MM-dd HH:mm:ss"等格式字符串。
+     * @return 转换后的字符串类型的日期时间表示，如果传入的Date对象为null则返回空字符串。
+     */
     public static String dateToStr(Date date,String formatStr){
         if(date == null){
             return StringUtils.EMPTY;
@@ -35,6 +57,14 @@ public class DateTimeUtil {
         return dateTime.toString(formatStr);
     }
 
+    /**
+     * 将字符串类型的日期时间转换为Date类型，使用类中定义的标准格式（STANDARD_FORMAT）进行解析。
+     * 先根据标准格式创建一个DateTimeFormatter对象，然后用它解析传入的日期时间字符串（dateTimeStr）得到DateTime对象，最后将其转换为Date类型并返回。
+     * 这个方法适用于传入的日期时间字符串符合标准格式的情况，简化了调用，无需每次都传入格式字符串参数。
+     *
+     * @param dateTimeStr 要转换的字符串类型的日期时间，其格式需要符合STANDARD_FORMAT定义的格式。
+     * @return 转换后的Date类型的日期时间对象，如果解析出现问题可能会抛出异常（由joda-time库的解析逻辑决定）。
+     */
     //固定好格式
     public static Date strToDate(String dateTimeStr){
         DateTimeFormatter dateTimeFormatter = DateTimeFormat.forPattern(STANDARD_FORMAT);
@@ -42,6 +72,14 @@ public class DateTimeUtil {
         return dateTime.toDate();
     }
 
+    /**
+     * 将Date类型的日期时间对象转换为使用标准格式（STANDARD_FORMAT）表示的字符串形式。
+     * 先判断传入的Date对象是否为null，若是则返回空字符串，若不为null则基于该Date对象创建一个DateTime对象，再按照标准格式将其转换为字符串并返回。
+     * 这个方法方便在需要按照统一标准格式输出日期时间字符串的场景下使用，无需每次指定格式字符串。
+     *
+     * @param date 要转换的Date类型的日期时间对象。
+     * @return 转换后的字符串类型的日期时间表示，如果传入的Date对象为null则返回空字符串。
+     */
     public static String dateToStr(Date date){
         if(date == null){
             return StringUtils.EMPTY;
@@ -50,6 +88,16 @@ public class DateTimeUtil {
         return dateTime.toString(STANDARD_FORMAT);
     }
 
+    /**
+     * 将Date类型的日期时间对象转换为时间戳（从1970年1月1日00:00:00 UTC到指定日期时间的毫秒数）。
+     * 首先判断传入的Date对象是否为null，如果是null则直接返回null。
+     * 如果Date对象不为null，则创建一个SimpleDateFormat对象，使用类中定义的标准格式（"yyyy-MM-dd HH:mm:ss"）来格式化日期时间，然后将Date对象转换为字符串后再解析为Date类型（这里感觉有点多余，其实可以直接获取Date对象的getTime方法获取时间戳，但可能是出于某些业务逻辑或者格式统一等考虑），最后获取其对应的时间戳（以毫秒为单位）并返回。
+     * 注意这个方法可能会抛出ParseException异常，在解析日期时间字符串出现问题时会抛出该异常，调用者需要进行相应的异常处理。
+     *
+     * @param date 要转换的Date类型的日期时间对象。
+     * @return 转换后的时间戳（以毫秒为单位），如果传入的Date对象为null则返回null，若解析出现问题会抛出ParseException异常。
+     * @throws ParseException 当解析日期时间字符串出现问题时抛出该异常，由SimpleDateFormat的解析逻辑决定。
+     */
     //Date -> 时间戳
     public static Long dateToChuo(Date date) throws ParseException {
         if(date == null){
@@ -59,10 +107,19 @@ public class DateTimeUtil {
         return format.parse(String.valueOf(date)).getTime();
     }
 
+    /**
+     * 这是类的主方法，是Java程序的入口点，在这里主要是进行了一个简单的日期时间转换示例操作。
+     * 首先创建一个SimpleDateFormat对象，使用"yyyy-MM-dd HH:mm:ss"格式来解析日期时间。
+     * 然后定义一个日期时间字符串（time），接着使用SimpleDateFormat对象解析该字符串得到一个Date对象，最后打印出该Date对象对应的时间戳（以毫秒为单位）。
+     * 这个主方法可以用于简单测试类中的日期时间转换相关方法的功能，不过在实际应用中可能不会这样直接写在工具类里，可以考虑单独写测试类等方式进行功能测试。
+     *
+     * @param args 命令行参数，在这里未使用到。
+     * @throws ParseException 当解析日期时间字符串出现问题时抛出该异常，由SimpleDateFormat的解析逻辑决定。
+     */
     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());
     }
-}
+}