doc(common): 优化注释说明

2026-01-06 15:06:23 +08:00
parent 8622891dbb
commit 6840d4a366
2 changed files with 237 additions and 24 deletions
--- a/spring-boot-service-template-common/src/main/java/com/lanyuanxiaoyao/service/template/common/controller/GlobalResponse.java
+++ b/spring-boot-service-template-common/src/main/java/com/lanyuanxiaoyao/service/template/common/controller/GlobalResponse.java
@@ -2,56 +2,208 @@ package com.lanyuanxiaoyao.service.template.common.controller;

 import java.util.Map;

-public record GlobalResponse<T>(
-    Integer status,
-    String message,
-    T data
-) {
+/**
+ * 全局响应对象
+ * <p>
+ * 该类用于统一封装API接口的响应结果，提供标准化的响应格式。
+ * 通过状态码、消息和数据三个字段，清晰地表达请求的处理结果。
+ * </p>
+ *
+ * <p>
+ * 响应格式示例:
+ * <pre>
+ * {
+ *   "status": 0,
+ *   "message": "OK",
+ *   "data": {
+ *     "items": [...],
+ *     "total": 10
+ *   }
+ * }
+ * </pre>
+ * </p>
+ *
+ * <p>
+ * 使用说明:
+ * <ul>
+ *   <li>成功响应: 使用 responseSuccess() 系列方法</li>
+ *   <li>错误响应: 使用 responseError() 系列方法</li>
+ *   <li>CRUD操作: 使用 responseCrudData() 方法返回列表数据</li>
+ *   <li>详情查询: 使用 responseDetailData() 方法返回单条记录</li>
+ * </ul>
+ * </p>
+ *
+ * @param <T>     响应数据的类型
+ * @param status  响应状态码，0表示成功，500表示错误，其他值可根据业务需求扩展
+ * @param message 响应消息，对状态码的简短描述，如"OK"、"ERROR"或具体的错误信息
+ * @param data    响应数据，具体的业务数据，可以是任意类型。对于列表查询，通常封装为包含items和total的Map；对于详情查询，直接返回对象或Map
+ */
+public record GlobalResponse<T>(Integer status, String message, T data) {
+  /**
+   * 成功状态码
+   */
  private static final int SUCCESS_STATUS = 0;
+
+  /**
+   * 错误状态码
+   */
  private static final int ERROR_STATUS = 500;
+
+  /**
+   * 成功默认消息
+   */
  private static final String SUCCESS_MESSAGE = "OK";
+
+  /**
+   * 错误默认消息
+   */
  private static final String ERROR_MESSAGE = "ERROR";

+  /**
+   * 返回默认错误响应
+   * <p>
+   * 使用默认错误消息"ERROR"，状态码500，数据为null
+   * </p>
+   *
+   * @return 错误响应对象
+   */
  public static GlobalResponse<Object> responseError() {
    return responseError(ERROR_MESSAGE);
  }

+  /**
+   * 返回指定错误消息的响应
+   * <p>
+   * 使用指定的错误消息，状态码500，数据为null
+   * </p>
+   *
+   * @param message 错误消息内容
+   * @return 错误响应对象
+   */
  public static GlobalResponse<Object> responseError(String message) {
    return new GlobalResponse<>(ERROR_STATUS, message, null);
  }

+  /**
+   * 返回默认成功响应
+   * <p>
+   * 使用默认成功消息"OK"，状态码0，数据为null
+   * </p>
+   *
+   * @return 成功响应对象
+   */
  public static GlobalResponse<Object> responseSuccess() {
    return responseSuccess(SUCCESS_MESSAGE);
  }

+  /**
+   * 返回指定成功消息的响应
+   * <p>
+   * 使用指定的成功消息，状态码0，数据为null
+   * </p>
+   *
+   * @param message 成功消息内容
+   * @return 成功响应对象
+   */
  public static GlobalResponse<Object> responseSuccess(String message) {
    return responseSuccess(message, null);
  }

+  /**
+   * 返回包含数据的成功响应
+   * <p>
+   * 使用默认成功消息"OK"，状态码0，包含指定数据
+   * </p>
+   *
+   * @param <E>  数据类型
+   * @param data 业务数据
+   * @return 成功响应对象
+   */
  public static <E> GlobalResponse<E> responseSuccess(E data) {
    return responseSuccess(SUCCESS_MESSAGE, data);
  }

+  /**
+   * 返回包含指定消息和数据的成功响应
+   * <p>
+   * 使用指定的成功消息，状态码0，包含指定数据
+   * </p>
+   *
+   * @param <E>     数据类型
+   * @param message 成功消息内容
+   * @param data    业务数据
+   * @return 成功响应对象
+   */
  public static <E> GlobalResponse<E> responseSuccess(String message, E data) {
    return new GlobalResponse<>(SUCCESS_STATUS, message, data);
  }

+  /**
+   * 返回Map类型数据的成功响应
+   * <p>
+   * 适用于需要返回结构化数据的场景，如分页查询结果
+   * </p>
+   *
+   * @param data Map格式的业务数据
+   * @return 成功响应对象
+   */
  public static GlobalResponse<Map<String, Object>> responseMapData(Map<String, Object> data) {
    return responseSuccess(data);
  }

+  /**
+   * 返回单个键值对的成功响应
+   * <p>
+   * 将单个键值对封装为Map后返回
+   * </p>
+   *
+   * @param key   数据键名
+   * @param value 数据值
+   * @return 成功响应对象
+   */
  public static GlobalResponse<Map<String, Object>> responseMapData(String key, Object value) {
    return responseMapData(Map.of(key, value));
  }

+  /**
+   * 返回CRUD列表数据的成功响应（Integer类型总数）
+   * <p>
+   * 适用于分页查询，将数据列表和总数封装为Map格式
+   * </p>
+   *
+   * @param <T>   数据项类型
+   * @param data  数据列表
+   * @param total 总记录数
+   * @return 成功响应对象
+   */
  public static <T> GlobalResponse<Map<String, Object>> responseCrudData(Iterable<T> data, Integer total) {
    return responseCrudData(data, total.longValue());
  }

+  /**
+   * 返回CRUD列表数据的成功响应（Long类型总数）
+   * <p>
+   * 适用于分页查询，将数据列表和总数封装为Map格式
+   * </p>
+   *
+   * @param <T>   数据项类型
+   * @param data  数据列表
+   * @param total 总记录数
+   * @return 成功响应对象
+   */
  public static <T> GlobalResponse<Map<String, Object>> responseCrudData(Iterable<T> data, Long total) {
    return responseMapData(Map.of("items", data, "total", total));
  }

+  /**
+   * 返回详情数据的成功响应
+   * <p>
+   * 适用于详情查询，将单条记录封装为Map格式
+   * </p>
+   *
+   * @param detail 详情数据
+   * @return 成功响应对象
+   */
  public static GlobalResponse<Map<String, Object>> responseDetailData(Object detail) {
    return responseMapData("detail", detail);
  }
--- a/spring-boot-service-template-common/src/main/java/com/lanyuanxiaoyao/service/template/common/controller/Query.java
+++ b/spring-boot-service-template-common/src/main/java/com/lanyuanxiaoyao/service/template/common/controller/Query.java
@@ -5,7 +5,10 @@ import java.util.Map;

 /**
 * 查询条件封装类，用于构建复杂的查询条件
- * 包含查询条件、排序条件和分页条件
+ * <p>
+ * 该类统一封装了查询条件、排序条件和分页条件，支持多种复杂的查询场景。
+ * 通过JSON格式传递查询参数，后端自动解析并转换为数据库查询条件。
+ * </p>
 *
 * <p>前端传入的JSON格式示例:</p>
 * <pre>
@@ -45,23 +48,33 @@ import java.util.Map;
 *
 * <p>查询条件说明:</p>
 * <ul>
- *   <li>nullEqual: 字段值为null的条件</li>
- *   <li>notNullEqual: 字段值不为null的条件</li>
- *   <li>empty: 字段值为空的条件</li>
- *   <li>notEmpty: 字段值不为空的条件</li>
- *   <li>equal: 字段值相等的条件</li>
- *   <li>notEqual: 字段值不相等的条件</li>
- *   <li>like: 字段值模糊匹配的条件</li>
- *   <li>notLike: 字段值不模糊匹配的条件</li>
- *   <li>great: 字段值大于的条件</li>
- *   <li>less: 字段值小于的条件</li>
- *   <li>greatEqual: 字段值大于等于的条件</li>
- *   <li>lessEqual: 字段值小于等于的条件</li>
- *   <li>in: 字段值在指定范围内的条件</li>
- *   <li>notIn: 字段值不在指定范围内的条件</li>
- *   <li>between: 字段值在指定区间内的条件</li>
- *   <li>notBetween: 字段值不在指定区间内的条件</li>
+ *   <li><b>nullEqual</b>: 字段值为null的条件列表</li>
+ *   <li><b>notNullEqual</b>: 字段值不为null的条件列表</li>
+ *   <li><b>empty</b>: 字段值为空的条件列表（如空字符串、空集合等）</li>
+ *   <li><b>notEmpty</b>: 字段值不为空的条件列表</li>
+ *   <li><b>equal</b>: 字段值相等的条件映射（字段名 -> 值）</li>
+ *   <li><b>notEqual</b>: 字段值不相等的条件映射（字段名 -> 值）</li>
+ *   <li><b>like</b>: 字段值模糊匹配的条件映射（字段名 -> 匹配值）</li>
+ *   <li><b>notLike</b>: 字段值不模糊匹配的条件映射（字段名 -> 匹配值）</li>
+ *   <li><b>contain</b>: 字段包含指定字符串的条件映射（字段名 -> 包含值）</li>
+ *   <li><b>notContain</b>: 字段不包含指定字符串的条件映射（字段名 -> 不包含值）</li>
+ *   <li><b>startWith</b>: 字段以指定字符串开头的条件映射（字段名 -> 开头值）</li>
+ *   <li><b>notStartWith</b>: 字段不以指定字符串开头的条件映射（字段名 -> 不开头值）</li>
+ *   <li><b>endWith</b>: 字段以指定字符串结尾的条件映射（字段名 -> 结尾值）</li>
+ *   <li><b>notEndWith</b>: 字段不以指定字符串结尾的条件映射（字段名 -> 不结尾值）</li>
+ *   <li><b>great</b>: 字段大于条件的映射（字段名 -> 值）</li>
+ *   <li><b>less</b>: 字段小于条件的映射（字段名 -> 值）</li>
+ *   <li><b>greatEqual</b>: 字段大于等于条件的映射（字段名 -> 值）</li>
+ *   <li><b>lessEqual</b>: 字段小于等于条件的映射（字段名 -> 值）</li>
+ *   <li><b>inside</b>: 字段值在指定范围内的条件映射（字段名 -> 值列表）</li>
+ *   <li><b>notInside</b>: 字段值不在指定范围内的条件映射（字段名 -> 值列表）</li>
+ *   <li><b>between</b>: 字段值在指定区间内的条件映射（字段名 -> 区间范围）</li>
+ *   <li><b>notBetween</b>: 字段值不在指定区间内的条件映射（字段名 -> 区间范围）</li>
 * </ul>
+ *
+ * @param query 查询条件对象，包含所有查询条件的封装
+ * @param sort 排序条件列表，支持多字段排序
+ * @param page 分页条件对象，指定页码和每页大小
 */
 public record Query(
    Queryable query,
@@ -70,6 +83,33 @@ public record Query(
 ) {
  /**
   * 可查询条件类，封装各种查询条件
+   * <p>
+   * 该类包含了所有支持的查询条件类型，每个字段对应一种查询条件。
+   * 字段名即为JSON中的键名，字段类型决定了查询条件的值类型。
+   * </p>
+   *
+   * @param nullEqual 字段值为null的条件列表，列表中的每个元素都是一个字段名
+   * @param notNullEqual 字段值不为null的条件列表，列表中的每个元素都是一个字段名
+   * @param empty 字段值为空的条件列表（如空字符串、空集合等），列表中的每个元素都是一个字段名
+   * @param notEmpty 字段值不为空的条件列表，列表中的每个元素都是一个字段名
+   * @param equal 字段值相等的条件映射，键为字段名，值为要相等的值
+   * @param notEqual 字段值不相等的条件映射，键为字段名，值为要不相等的值
+   * @param like 字段值模糊匹配的条件映射，键为字段名，值为模糊匹配的模式（支持%通配符）
+   * @param notLike 字段值不模糊匹配的条件映射，键为字段名，值为不匹配的模式
+   * @param contain 字段包含指定字符串的条件映射，键为字段名，值为要包含的字符串
+   * @param notContain 字段不包含指定字符串的条件映射，键为字段名，值为不包含的字符串
+   * @param startWith 字段以指定字符串开头的条件映射，键为字段名，值为开头字符串
+   * @param notStartWith 字段不以指定字符串开头的条件映射，键为字段名，值为不开头的字符串
+   * @param endWith 字段以指定字符串结尾的条件映射，键为字段名，值为结尾字符串
+   * @param notEndWith 字段不以指定字符串结尾的条件映射，键为字段名，值为不结尾的字符串
+   * @param great 字段大于条件的映射，键为字段名，值为比较的阈值
+   * @param less 字段小于条件的映射，键为字段名，值为比较的阈值
+   * @param greatEqual 字段大于等于条件的映射，键为字段名，值为比较的阈值
+   * @param lessEqual 字段小于等于条件的映射，键为字段名，值为比较的阈值
+   * @param inside 字段值在指定范围内的条件映射，键为字段名，值为允许的值列表
+   * @param notInside 字段值不在指定范围内的条件映射，键为字段名，值为不允许的值列表
+   * @param between 字段值在指定区间内的条件映射，键为字段名，值为区间范围对象
+   * @param notBetween 字段值不在指定区间内的条件映射，键为字段名，值为区间范围对象
   */
  public record Queryable(
      List<String> nullEqual,
@@ -97,6 +137,12 @@ public record Query(
  ) {
    /**
     * 区间范围类，用于表示起始值和结束值
+     * <p>
+     * 主要用于 between 和 notBetween 查询条件，表示一个数值或时间的区间范围。
+     * </p>
+     *
+     * @param start 区间起始值（包含）
+     * @param end 区间结束值（包含）
     */
    public record Between(
        Object start,
@@ -106,17 +152,26 @@ public record Query(
  }


+  /**
+   * 排序条件类，用于指定排序字段和排序方向
+   *
+   * @param column 排序字段名，对应数据库表的列名或实体类的属性名
+   * @param direction 排序方向，ASC表示升序，DESC表示降序
+   */
  public record Sortable(
      String column,
      Direction direction
  ) {
+    /**
+     * 排序方向枚举
+     */
    public enum Direction {
      /**
-       * 升序排列
+       * 升序排列（从小到大）
       */
      ASC,
      /**
-       * 降序排列
+       * 降序排列（从大到小）
       */
      DESC,
    }
@@ -124,6 +179,12 @@ public record Query(

  /**
   * 可分页条件类，用于指定分页参数
+   * <p>
+   * 页码从0开始计数，即第一页的索引为0。
+   * </p>
+   *
+   * @param index 页码索引，从0开始（0表示第一页）
+   * @param size 每页大小，即每页显示的记录数
   */
  public record Pageable(
      Integer index,