From 6840d4a3667a80f78a267b185ee59cabb3b8ae7c Mon Sep 17 00:00:00 2001 From: lanyuanxiaoyao Date: Tue, 6 Jan 2026 15:06:23 +0800 Subject: [PATCH] =?UTF-8?q?doc(common):=20=E4=BC=98=E5=8C=96=E6=B3=A8?= =?UTF-8?q?=E9=87=8A=E8=AF=B4=E6=98=8E?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../common/controller/GlobalResponse.java | 162 +++++++++++++++++- .../template/common/controller/Query.java | 99 +++++++++-- 2 files changed, 237 insertions(+), 24 deletions(-) diff --git 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 index 0a579a2..1c5ae17 100644 --- 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( - Integer status, - String message, - T data -) { +/** + * 全局响应对象 + *

+ * 该类用于统一封装API接口的响应结果，提供标准化的响应格式。 + * 通过状态码、消息和数据三个字段，清晰地表达请求的处理结果。 + *

+ * + *

+ * 响应格式示例: + * 

+ * {
+ *   "status": 0,
+ *   "message": "OK",
+ *   "data": {
+ *     "items": [...],
+ *     "total": 10
+ *   }
+ * }
+ *
+ *

+ * + *

+ * 使用说明: + *

+ *

+ * + * @param 响应数据的类型 + * @param status 响应状态码，0表示成功，500表示错误，其他值可根据业务需求扩展 + * @param message 响应消息，对状态码的简短描述，如"OK"、"ERROR"或具体的错误信息 + * @param data 响应数据，具体的业务数据，可以是任意类型。对于列表查询，通常封装为包含items和total的Map；对于详情查询，直接返回对象或Map + */ +public record GlobalResponse(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"; + /** + * 返回默认错误响应 + *

+ * 使用默认错误消息"ERROR"，状态码500，数据为null + *

+ * + * @return 错误响应对象 + */ public static GlobalResponse responseError() { return responseError(ERROR_MESSAGE); } + /** + * 返回指定错误消息的响应 + *

+ * 使用指定的错误消息，状态码500，数据为null + *

+ * + * @param message 错误消息内容 + * @return 错误响应对象 + */ public static GlobalResponse responseError(String message) { return new GlobalResponse<>(ERROR_STATUS, message, null); } + /** + * 返回默认成功响应 + *

+ * 使用默认成功消息"OK"，状态码0，数据为null + *

+ * + * @return 成功响应对象 + */ public static GlobalResponse responseSuccess() { return responseSuccess(SUCCESS_MESSAGE); } + /** + * 返回指定成功消息的响应 + *

+ * 使用指定的成功消息，状态码0，数据为null + *

+ * + * @param message 成功消息内容 + * @return 成功响应对象 + */ public static GlobalResponse responseSuccess(String message) { return responseSuccess(message, null); } + /** + * 返回包含数据的成功响应 + *

+ * 使用默认成功消息"OK"，状态码0，包含指定数据 + *

+ * + * @param 数据类型 + * @param data 业务数据 + * @return 成功响应对象 + */ public static GlobalResponse responseSuccess(E data) { return responseSuccess(SUCCESS_MESSAGE, data); } + /** + * 返回包含指定消息和数据的成功响应 + *

+ * 使用指定的成功消息，状态码0，包含指定数据 + *

+ * + * @param 数据类型 + * @param message 成功消息内容 + * @param data 业务数据 + * @return 成功响应对象 + */ public static GlobalResponse responseSuccess(String message, E data) { return new GlobalResponse<>(SUCCESS_STATUS, message, data); } + /** + * 返回Map类型数据的成功响应 + *

+ * 适用于需要返回结构化数据的场景，如分页查询结果 + *

+ * + * @param data Map格式的业务数据 + * @return 成功响应对象 + */ public static GlobalResponse> responseMapData(Map data) { return responseSuccess(data); } + /** + * 返回单个键值对的成功响应 + *

+ * 将单个键值对封装为Map后返回 + *

+ * + * @param key 数据键名 + * @param value 数据值 + * @return 成功响应对象 + */ public static GlobalResponse> responseMapData(String key, Object value) { return responseMapData(Map.of(key, value)); } + /** + * 返回CRUD列表数据的成功响应（Integer类型总数） + *

+ * 适用于分页查询，将数据列表和总数封装为Map格式 + *

+ * + * @param 数据项类型 + * @param data 数据列表 + * @param total 总记录数 + * @return 成功响应对象 + */ public static GlobalResponse> responseCrudData(Iterable data, Integer total) { return responseCrudData(data, total.longValue()); } + /** + * 返回CRUD列表数据的成功响应（Long类型总数） + *

+ * 适用于分页查询，将数据列表和总数封装为Map格式 + *

+ * + * @param 数据项类型 + * @param data 数据列表 + * @param total 总记录数 + * @return 成功响应对象 + */ public static GlobalResponse> responseCrudData(Iterable data, Long total) { return responseMapData(Map.of("items", data, "total", total)); } + /** + * 返回详情数据的成功响应 + *

+ * 适用于详情查询，将单条记录封装为Map格式 + *

+ * + * @param detail 详情数据 + * @return 成功响应对象 + */ public static GlobalResponse> responseDetailData(Object detail) { return responseMapData("detail", detail); } diff --git 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 index be34952..c395358 100644 --- 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; /** * 查询条件封装类，用于构建复杂的查询条件 - * 包含查询条件、排序条件和分页条件 + *

+ * 该类统一封装了查询条件、排序条件和分页条件，支持多种复杂的查询场景。 + * 通过JSON格式传递查询参数，后端自动解析并转换为数据库查询条件。 + *

* *

前端传入的JSON格式示例:

* 
@@ -45,23 +48,33 @@ import java.util.Map;
  *
  * 
查询条件说明:

  * 
    
- *   
  • nullEqual: 字段值为null的条件
    • 
- *   
  • notNullEqual: 字段值不为null的条件
    • 
- *   
  • empty: 字段值为空的条件
    • 
- *   
  • notEmpty: 字段值不为空的条件
    • 
- *   
  • equal: 字段值相等的条件
    • 
- *   
  • notEqual: 字段值不相等的条件
    • 
- *   
  • like: 字段值模糊匹配的条件
    • 
- *   
  • notLike: 字段值不模糊匹配的条件
    • 
- *   
  • great: 字段值大于的条件
    • 
- *   
  • less: 字段值小于的条件
    • 
- *   
  • greatEqual: 字段值大于等于的条件
    • 
- *   
  • lessEqual: 字段值小于等于的条件
    • 
- *   
  • in: 字段值在指定范围内的条件
    • 
- *   
  • notIn: 字段值不在指定范围内的条件
    • 
- *   
  • between: 字段值在指定区间内的条件
    • 
- *   
  • notBetween: 字段值不在指定区间内的条件
    • 
+ *   
  • nullEqual: 字段值为null的条件列表
    • 
+ *   
  • notNullEqual: 字段值不为null的条件列表
    • 
+ *   
  • empty: 字段值为空的条件列表（如空字符串、空集合等）
    • 
+ *   
  • notEmpty: 字段值不为空的条件列表
    • 
+ *   
  • equal: 字段值相等的条件映射（字段名 -> 值）
    • 
+ *   
  • notEqual: 字段值不相等的条件映射（字段名 -> 值）
    • 
+ *   
  • like: 字段值模糊匹配的条件映射（字段名 -> 匹配值）
    • 
+ *   
  • notLike: 字段值不模糊匹配的条件映射（字段名 -> 匹配值）
    • 
+ *   
  • contain: 字段包含指定字符串的条件映射（字段名 -> 包含值）
    • 
+ *   
  • notContain: 字段不包含指定字符串的条件映射（字段名 -> 不包含值）
    • 
+ *   
  • startWith: 字段以指定字符串开头的条件映射（字段名 -> 开头值）
    • 
+ *   
  • notStartWith: 字段不以指定字符串开头的条件映射（字段名 -> 不开头值）
    • 
+ *   
  • endWith: 字段以指定字符串结尾的条件映射（字段名 -> 结尾值）
    • 
+ *   
  • notEndWith: 字段不以指定字符串结尾的条件映射（字段名 -> 不结尾值）
    • 
+ *   
  • great: 字段大于条件的映射（字段名 -> 值）
    • 
+ *   
  • less: 字段小于条件的映射（字段名 -> 值）
    • 
+ *   
  • greatEqual: 字段大于等于条件的映射（字段名 -> 值）
    • 
+ *   
  • lessEqual: 字段小于等于条件的映射（字段名 -> 值）
    • 
+ *   
  • inside: 字段值在指定范围内的条件映射（字段名 -> 值列表）
    • 
+ *   
  • notInside: 字段值不在指定范围内的条件映射（字段名 -> 值列表）
    • 
+ *   
  • between: 字段值在指定区间内的条件映射（字段名 -> 区间范围）
    • 
+ *   
  • notBetween: 字段值不在指定区间内的条件映射（字段名 -> 区间范围）
    • 
  * 

+ *
+ * @param query 查询条件对象，包含所有查询条件的封装
+ * @param sort 排序条件列表，支持多字段排序
+ * @param page 分页条件对象，指定页码和每页大小
  */
 public record Query(
     Queryable query,
@@ -70,6 +83,33 @@ public record Query(
 ) {
   /**
    * 可查询条件类，封装各种查询条件
+   * 

+   * 该类包含了所有支持的查询条件类型，每个字段对应一种查询条件。
+   * 字段名即为JSON中的键名，字段类型决定了查询条件的值类型。
+   * 

+   *
+   * @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 nullEqual,
@@ -97,6 +137,12 @@ public record Query(
   ) {
     /**
      * 区间范围类，用于表示起始值和结束值
+     * 

+     * 主要用于 between 和 notBetween 查询条件，表示一个数值或时间的区间范围。
+     * 

+     *
+     * @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(
 
   /**
    * 可分页条件类，用于指定分页参数
+   * 

+   * 页码从0开始计数，即第一页的索引为0。
+   * 

+   *
+   * @param index 页码索引，从0开始（0表示第一页）
+   * @param size 每页大小，即每页显示的记录数
    */
   public record Pageable(
       Integer index,