已上传 2018.1.0 版本

mrzhqiang · Oct 19, 2018 · dea283e · dea283e
1 parent a8d1394
commit dea283e
Show file tree

Hide file tree

Showing 6 changed files with 153 additions and 134 deletions.
diff --git a/helper/pom.xml b/helper/pom.xml
@@ -11,8 +11,7 @@
   </parent>
 
   <artifactId>helper</artifactId>
-  <name>Helper: Helper tools for Java</name>
-  <description>Helper is a common code library.</description>
+  <name>Helper</name>
 
   <dependencies>
     <dependency>
@@ -40,53 +39,17 @@
         <groupId>org.apache.maven.plugins</groupId>
         <artifactId>maven-source-plugin</artifactId>
         <version>2.2.1</version>
-        <executions>
-          <execution>
-            <id>attach-sources</id>
-            <goals>
-              <goal>jar-no-fork</goal>
-            </goals>
-          </execution>
-        </executions>
       </plugin>
       <plugin>
         <groupId>org.apache.maven.plugins</groupId>
         <artifactId>maven-javadoc-plugin</artifactId>
-        <version>2.10.4</version>
-        <executions>
-          <execution>
-            <id>attach-javadocs</id>
-            <goals>
-              <goal>jar</goal>
-            </goals>
-          </execution>
-        </executions>
+        <version>2.9.1</version>
       </plugin>
+
       <plugin>
         <groupId>org.apache.maven.plugins</groupId>
         <artifactId>maven-gpg-plugin</artifactId>
         <version>1.5</version>
-        <executions>
-          <execution>
-            <id>sign-artifacts</id>
-            <phase>verify</phase>
-            <goals>
-              <goal>sign</goal>
-            </goals>
-          </execution>
-        </executions>
-      </plugin>
-      <plugin>
-        <groupId>org.apache.maven.plugins</groupId>
-        <artifactId>maven-jar-plugin</artifactId>
-        <version>3.0.2</version>
-        <configuration>
-          <archive>
-            <manifestEntries>
-              <Automatic-Module-Name>helper</Automatic-Module-Name>
-            </manifestEntries>
-          </archive>
-        </configuration>
       </plugin>
     </plugins>
   </build>

diff --git a/helper/src/main/java/helper/DateTimeHelper.java b/helper/src/main/java/helper/DateTimeHelper.java
@@ -19,10 +19,10 @@
 /**
  * 日期时间助手。
  * <p>
- * 这是为了兼容与 {@link Date 日期类} 相关的逻辑，比如数据库时间戳。
+ * 这是为了兼容与 {@link Date Date} 相关的逻辑，比如数据库时间戳。
  * <p>
  * 关于格式化：
- * 习惯上，我们使用 <code>yyyy-MM-dd HH:mm:ss</code> 格式，通过 {@link Config 安全配置}
+ * 习惯上，我们使用 yyyy-MM-dd HH:mm:ss 格式，通过 {@link Config Config}
  * 你将获得更加灵活的格式设定，另外还可以格式化为：仅日期、仅时间、仅 HTTP，等等。
  * <p>
  * 关于解析：
@@ -111,13 +111,18 @@ private DateTimeHelper() {
   private static final List<String> DISPLAY_PREFIX = DISPLAY.getStringList("prefix");
 
   /**
-   * 默认格式为：yyyy-MM-dd HH:mm:ss。
+   * 格式化日期时间方法。
    * <p>
-   * 可以通过在 resources 目录下添加 reference.conf 文件，并设置以下内容：
+   * 默认为 yyyy-MM-dd HH:mm:ss 格式，比如 1970-01-01 00:00:00。
+   * <p>
+   * 通过在 resources 目录下添加 reference.conf 文件，并增加以下内容：
    * <pre>
    *   helper.datetime.local.datetime = "****"
    * </pre>
-   * 来修改默认的日期时间格式。
+   * 即可修改为你希望的日期时间格式。
+   *
+   * @param value {@link Date Date}，非 Null。
+   * @return 格式化后的字符串。
    */
   public static String format(Date value) {
     Preconditions.checkNotNull(value);
@@ -130,51 +135,73 @@ public static String format(Date value) {
   }
 
   /**
-   * 默认格式为：yyyy-MM-dd。
+   * 格式化日期方法。
    * <p>
-   * 可以通过在 resources 目录下添加 reference.conf 文件，并设置以下内容：
+   * 默认为 yyyy-MM-dd 格式，比如：1970-01-01。
+   * <p>
+   * 通过在 resources 目录下添加 reference.conf 文件，并增加以下内容：
    * <pre>
    *   helper.datetime.local.date = "****"
    * </pre>
-   * 来修改默认的日期格式。
+   * 即可修改为你希望的日期格式。
+   *
+   * @param value {@link Date Date}，非 Null。
+   * @return 格式化后的字符串。
    */
   public static String formatDate(Date value) {
     Preconditions.checkNotNull(value);
     return LOCAL_DATE.get().format(value);
   }
 
   /**
-   * 默认格式为：HH:mm:ss。
+   * 格式化时间方法。
    * <p>
-   * 可以通过在 resources 目录下添加 reference.conf 文件，并设置以下内容：
+   * 默认为 HH:mm:ss 格式，比如：00:00:00。
+   * <p>
+   * 通过在 resources 目录下添加 reference.conf 文件，并增加以下内容：
    * <pre>
    *   helper.datetime.local.time = "****"
    * </pre>
-   * 来修改默认的时间格式。
+   * 即可修改为你希望的时间格式。
+   *
+   * @param value {@link Date Date}，非 Null。
+   * @return 格式化后的字符串。
    */
   public static String formatTime(Date value) {
     Preconditions.checkNotNull(value);
     return LOCAL_TIME.get().format(value);
   }
 
   /**
-   * HTTP 日期 + 时间，比如：Thu, 05 Jul 2018 14:50:45 GMT
+   * 格式化 HTTP 日期时间方法。
+   * <p>
+   * 默认为 EEE, dd MMM yyyy HH:mm:ss 'GMT' 格式，比如：Thu, 05 Jul 2018 14:50:45 GMT。
+   * <p>
+   * 这个方法拷贝自 okhttp，因此不具备从配置文件修改的能力。
+   *
+   * @param value {@link Date Date}，非 Null。
+   * @return 格式化后的字符串。
    */
   public static String formatHTTP(Date value) {
     Preconditions.checkNotNull(value);
     return HttpDate.format(value);
   }
 
   /**
-   * 默认解析：yyyy-MM-dd HH:mm:ss, Locale.getDefault() and TimeZone.getDefault().
+   * 解析时间日期方法。
+   * <p>
+   * 格式：yyyy-MM-dd HH:mm:ss，默认使用系统语言和系统时区。
    * <p>
    * 可以通过在 resources 目录下添加 reference.conf 文件，并设置以下内容：
    * <pre>
    *   helper.datetime.local.datetime = "****"
    * </pre>
    * 来修改默认的日期时间格式。
    * <p>
-   * 如果失败，尝试使用 HTTP 格式进行解析。
+   * 注意：首次解析失败将尝试使用 HTTP 格式进行解析，以降低返回 Null 值的可能。
+   *
+   * @param source 字符串表示的时间。
+   * @return {@link Date Date}，如果解析失败则返回 Null。
    */
   @Nullable
   public static Date parse(String source) {
@@ -189,6 +216,9 @@ public static Date parse(String source) {
 
   /**
    * Returns the date for {@code value}. Returns null if the value couldn't be parsed.
+   *
+   * @param value 字符串表示的时间。
+   * @return {@link Date Date}，如果解析失败则返回 Null。
    */
   @Nullable
   public static Date parseHTTP(String value) {

diff --git a/helper/src/main/java/helper/NameHelper.java b/helper/src/main/java/helper/NameHelper.java
@@ -100,9 +100,9 @@ public static boolean checkName(@Nullable String value) {
   /**
    * 检查 Username 是否为字母或数字，并位于指定范围内。
    *
-   * @param min 最小长度。<= 0 表示不做长度检测。
-   * @param max 最大长度。<= 0 表示不做长度检测，并且必须 >= min。
    * @param value Username，如果是 Null 或者空串则返回 false。
+   * @param min 最小长度。小于等于 0 表示不做长度检测。
+   * @param max 最大长度。小于等于 0 表示不做长度检测，并且必须大于等于 min。
    * @return true 符合规则；false 字符串值为 Null 或者不符合规则。
    */
   public static boolean checkName(@Nullable String value, int min, int max) {
@@ -138,8 +138,8 @@ public static boolean checkChinese(@Nullable String value) {
    * 检查 Username 是否为中文，并且是否在指定长度范围内。
    *
    * @param value Username，如果是 Null 或者空串则返回 false。
-   * @param min 最小长度。<= 0 表示不做长度检测。
-   * @param max 最大长度。<= 0 表示不做长度检测，并且必须 >= min。
+   * @param min 最小长度。小于等于 0 表示不做长度检测。
+   * @param max 最大长度。小于等于 0 表示不做长度检测，并且必须大于等于 min。
    * @return true 符合规则；false 字符串值为 Null 或者不符合规则。
    */
   public static boolean checkChinese(@Nullable String value, int min, int max) {
@@ -151,8 +151,8 @@ public static boolean checkChinese(@Nullable String value, int min, int max) {
    *
    * @param regex 正则表达式。
    * @param value Username，如果是 Null 或者空串则返回 false。
-   * @param min 最小长度。<= 0 表示不做长度检测。
-   * @param max 最大长度。<= 0 表示不做长度检测，并且必须 >= min。
+   * @param min 最小长度。小于等于 0 表示不做长度检测。
+   * @param max 最大长度。小于等于 0 表示不做长度检测，并且必须大于等于 min。
    * @return true 符合规则；false 字符串值为 Null 或者不符合规则。
    */
   public static boolean checkString(@RegEx String regex, @Nullable String value, int min, int max) {

diff --git a/helper/src/main/java/helper/RandomHelper.java b/helper/src/main/java/helper/RandomHelper.java
@@ -90,8 +90,8 @@ public static String getString(int length) {
   /**
    * 通过指定最小长度和最大长度范围，生成随机字符序列。
    *
-   * @param min 最小长度，必须 > 0。
-   * @param max 最大长度，必须 > 0，并且必须 >= min。
+   * @param min 最小长度，必须大于 0。
+   * @param max 最大长度，必须大于 0，并且必须大于等于 min。
    * @return 随机字符串，范围：大小写字母，数字，特殊字符。
    */
   public static String getString(int min, int max) {
@@ -127,8 +127,8 @@ public static String getChinese(int length) {
   /**
    * 通过指定最小长度和最大长度范围，生成随机汉字序列。
    *
-   * @param min 最小长度，必须 > 0。
-   * @param max 最大长度，必须 > 0，并且必须 >= min。
+   * @param min 最小长度，必须大于 0。
+   * @param max 最大长度，必须大于 0，并且必须大于等于 min。
    * @return 随机汉字，范围：常用汉字 3500 个。
    */
   public static String getChinese(int min, int max) {
@@ -155,7 +155,7 @@ public static String getSurname() {
   /**
    * 通过指定长度，生成随机数字序列的字符串。
    *
-   * @param length 指定长度，必须 > 0。
+   * @param length 指定长度，必须大于 0。
    * @return 随机字符串，仅包含：数字。
    */
   public static String getNumber(int length) {
@@ -174,8 +174,8 @@ public static String getNumber(int length) {
   /**
    * 通过指定长度范围，生成随机数字序列的字符串。
    *
-   * @param min 最小长度，必须 > 0。
-   * @param max 最大长度，必须 > 0，并且必须 >= min。
+   * @param min 最小长度，必须大于 0。
+   * @param max 最大长度，必须大于 0，并且必须大于等于 min。
    * @return 随机字符串，仅包含：数字。
    */
   public static String getNumber(int min, int max) {
@@ -193,7 +193,7 @@ public static String getNumber(int min, int max) {
   /**
    * 通过指定长度，生成随机小写字母序列的字符串。
    *
-   * @param length 指定长度，必须 > 0。
+   * @param length 指定长度，必须大于 0。
    * @return 随机字符串，仅包含：小写字母。
    */
   public static String getLowerCase(int length) {
@@ -210,8 +210,8 @@ public static String getLowerCase(int length) {
   /**
    * 通过指定长度范围，生成随机小写字母序列的字符串。
    *
-   * @param min 最小长度，必须 > 0。
-   * @param max 最大长度，必须 > 0，并且必须 >= min。
+   * @param min 最小长度，必须大于 0。
+   * @param max 最大长度，必须大于 0，并且必须大于等于 min。
    * @return 随机字符串，仅包含：小写字母。
    */
   public static String getLowerCase(int min, int max) {
@@ -229,7 +229,7 @@ public static String getLowerCase(int min, int max) {
   /**
    * 通过指定长度，生成随机大写字母序列的字符串。
    *
-   * @param length 指定长度，必须 > 0。
+   * @param length 指定长度，必须大于 0。
    * @return 随机字符串，仅包含：大写字母。
    */
   public static String getUpperCase(int length) {
@@ -246,8 +246,8 @@ public static String getUpperCase(int length) {
   /**
    * 通过指定长度范围，生成随机大写字母序列的字符串。
    *
-   * @param min 最小长度，必须 > 0。
-   * @param max 最大长度，必须 > 0，并且必须 >= min。
+   * @param min 最小长度，必须大于 0。
+   * @param max 最大长度，必须大于 0，并且必须大于等于 min。
    * @return 随机字符串，仅包含：大写字母。
    */
   public static String getUpperCase(int min, int max) {