doc(common): 优化统一响应和工具类注释

2026-01-06 15:50:36 +08:00
parent d38196cb6e
commit 327e983c46
11 changed files with 510 additions and 302 deletions
--- a/spring-boot-service-template-jpa/src/main/java/com/lanyuanxiaoyao/service/template/jpa/controller/SimpleControllerSupport.java
+++ b/spring-boot-service-template-jpa/src/main/java/com/lanyuanxiaoyao/service/template/jpa/controller/SimpleControllerSupport.java
@@ -21,72 +21,21 @@ import org.springframework.web.bind.annotation.RequestBody;
 * 子类需要实现对应的Mapper函数来完成实体类与传输对象之间的转换。
 * </p>
 *
- * <p>
- * 前端传入的JSON格式示例:
- * <pre>
- * // 保存实体
- * POST /save
- * {
- *   // 保存项的具体字段
- *   "name": "示例名称",
- *   "description": "示例描述"
- * }
- *
- * // 查询列表（无条件）
- * GET /list
- *
- * // 查询列表（带条件）
- * POST /list
- * {
- *   "query": {
- *     "equal": {
- *       "status": "ACTIVE"
- *     },
- *     "like": {
- *       "name": "关键字"
- *     }
- *   },
- *   "sort": [
- *     {
- *       "column": "createTime",
- *       "direction": "DESC"
- *     }
- *   ],
- *   "page": {
- *     "index": 0,
- *     "size": 10
- *   }
- * }
- *
- * // 获取详情
- * GET /detail/1
- *
- * // 删除实体
- * GET /remove/1
- * </pre>
- * </p>
- *
- * <p>
- * 支持的查询条件说明:
+ * <h3>设计特点</h3>
 * <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>泛型设计，支持任意实体类型和数据转换</li>
+ *   <li>统一的异常处理和事务管理</li>
+ *   <li>支持条件查询、分页查询和详情查询</li>
+ *   <li>提供抽象的Mapper方法，便于子类实现数据转换逻辑</li>
+ * </ul>
+ *
+ * <h3>使用说明</h3>
+ * <p>子类需要实现以下抽象方法：</p>
+ * <ul>
+ *   <li>saveItemMapper(): 保存项到实体的转换函数</li>
+ *   <li>listItemMapper(): 实体到列表项的转换函数</li>
+ *   <li>detailItemMapper(): 实体到详情项的转换函数</li>
 * </ul>
- * </p>
 *
 * @param <ENTITY>      实体类型，必须继承SimpleEntity
 * @param <SAVE_ITEM>   保存项类型
@@ -108,9 +57,13 @@ public abstract class SimpleControllerSupport<ENTITY extends SimpleEntity, SAVE_

  /**
   * 保存实体对象
+   * <p>
+   * 将保存项转换为实体对象后保存，返回保存后的实体ID。
+   * 支持新增和更新操作，通过事务保证数据一致性。
+   * </p>
   *
   * @param item 需要保存的项
-   * @return GlobalResponse<Long> 返回保存后的实体ID
+   * @return 返回保存后的实体ID响应对象，格式：{status: 0, message: "OK", data: 实体ID}
   * @throws Exception 保存过程中可能抛出的异常
   */
  @Transactional(rollbackFor = Throwable.class)
@@ -123,8 +76,12 @@ public abstract class SimpleControllerSupport<ENTITY extends SimpleEntity, SAVE_

  /**
   * 获取所有实体列表
+   * <p>
+   * 查询所有记录，不带任何过滤条件，返回分页格式的数据。
+   * 将实体对象转换为列表项对象后返回。
+   * </p>
   *
-   * @return GlobalCrudResponse<LIST_ITEM> 返回实体列表
+   * @return 返回实体列表响应对象，格式：{status: 0, message: "OK", data: {items: [...], total: total}}
   * @throws Exception 查询过程中可能抛出的异常
   */
  @Transactional(readOnly = true)
@@ -150,9 +107,13 @@ public abstract class SimpleControllerSupport<ENTITY extends SimpleEntity, SAVE_

  /**
   * 根据查询条件获取实体列表
+   * <p>
+   * 支持复杂的查询条件、排序和分页，返回符合条件的数据。
+   * 将实体对象转换为列表项对象后返回。
+   * </p>
   *
-   * @param query 查询条件对象
-   * @return GlobalCrudResponse<LIST_ITEM> 返回符合条件的实体列表
+   * @param query 查询条件对象，包含过滤条件、排序规则和分页信息
+   * @return 返回符合条件的实体列表响应对象，格式：{status: 0, message: "OK", data: {items: [...], total: total}}
   * @throws Exception 查询过程中可能抛出的异常
   */
  @Transactional(readOnly = true)
@@ -180,9 +141,13 @@ public abstract class SimpleControllerSupport<ENTITY extends SimpleEntity, SAVE_

  /**
   * 根据ID获取实体详情
+   * <p>
+   * 根据主键ID查询单条记录的详细信息，转换为详情项对象后返回。
+   * 如果记录不存在则抛出异常。
+   * </p>
   *
-   * @param id 实体ID
-   * @return GlobalResponse<DETAIL_ITEM> 返回实体详情
+   * @param id 实体主键ID
+   * @return 返回实体详情响应对象，格式：{status: 0, message: "OK", data: 详情数据}
   * @throws Exception 查询过程中可能抛出的异常
   */
  @Transactional(readOnly = true)
@@ -195,9 +160,13 @@ public abstract class SimpleControllerSupport<ENTITY extends SimpleEntity, SAVE_

  /**
   * 根据ID删除实体对象
+   * <p>
+   * 根据主键ID删除指定的记录，执行成功后返回成功响应。
+   * 通过事务保证删除操作的一致性。
+   * </p>
   *
-   * @param id 需要删除的实体ID
-   * @return GlobalResponse<Object> 返回删除结果
+   * @param id 需要删除的实体主键ID
+   * @return 返回删除结果响应对象，格式：{status: 0, message: "OK", data: null}
   * @throws Exception 删除过程中可能抛出的异常
   */
  @Transactional(rollbackFor = Throwable.class)
@@ -210,6 +179,9 @@ public abstract class SimpleControllerSupport<ENTITY extends SimpleEntity, SAVE_

  /**
   * 保存项映射器，将保存项转换为实体对象
+   * <p>
+   * 子类需要实现此方法，定义保存项到实体的转换逻辑。
+   * </p>
   *
   * @return Function<SAVE_ITEM, ENTITY> 保存项到实体的转换函数
   */
@@ -217,6 +189,9 @@ public abstract class SimpleControllerSupport<ENTITY extends SimpleEntity, SAVE_

  /**
   * 列表项映射器，将实体对象转换为列表项
+   * <p>
+   * 子类需要实现此方法，定义实体到列表项的转换逻辑。
+   * </p>
   *
   * @return Function<ENTITY, LIST_ITEM> 实体到列表项的转换函数
   */
@@ -224,6 +199,9 @@ public abstract class SimpleControllerSupport<ENTITY extends SimpleEntity, SAVE_

  /**
   * 详情项映射器，将实体对象转换为详情项
+   * <p>
+   * 子类需要实现此方法，定义实体到详情项的转换逻辑。
+   * </p>
   *
   * @return Function<ENTITY, DETAIL_ITEM> 实体到详情项的转换函数
   */
--- a/spring-boot-service-template-jpa/src/main/java/com/lanyuanxiaoyao/service/template/jpa/service/SimpleServiceSupport.java
+++ b/spring-boot-service-template-jpa/src/main/java/com/lanyuanxiaoyao/service/template/jpa/service/SimpleServiceSupport.java
@@ -31,64 +31,28 @@ import org.springframework.data.domain.Sort;
 * 该类实现了SimpleService接口，提供实体的增删改查等基本操作。
 * 通过继承此类，可以快速实现常见的业务逻辑功能，包括：
 * <ul>
- *   <li>实体的保存和更新</li>
+ *   <li>实体的保存和更新（支持部分字段更新）</li>
 *   <li>实体的条件查询和分页查询</li>
 *   <li>实体的详情查询（多种方式）</li>
- *   <li>实体的删除操作</li>
+ *   <li>实体的删除操作（支持批量删除）</li>
+ *   <li>动态查询条件构建</li>
 * </ul>
 * </p>
 *
- * <p>
- * 查询条件说明:
+ * <h3>设计特点</h3>
 * <ul>
- *   <li>nullEqual: 指定字段值为null的条件列表</li>
- *   <li>notNullEqual: 指定字段值不为null的条件列表</li>
- *   <li>empty: 指定字段值为空的条件列表（如空字符串、空集合等）</li>
- *   <li>notEmpty: 指定字段值不为空的条件列表</li>
- *   <li>equal: 指定字段值相等的条件映射（字段名 -> 值）</li>
- *   <li>notEqual: 指定字段值不相等的条件映射（字段名 -> 值）</li>
- *   <li>contain: 指定字段包含指定字符串的条件映射（字段名 -> 包含值）</li>
- *   <li>notContain: 指定字段不包含指定字符串的条件映射（字段名 -> 不包含值）</li>
- *   <li>startWith: 指定字段以指定字符串开头的条件映射（字段名 -> 开头值）</li>
- *   <li>notStartWith: 指定字段不以指定字符串开头的条件映射（字段名 -> 不开头值）</li>
- *   <li>endWith: 指定字段以指定字符串结尾的条件映射（字段名 -> 结尾值）</li>
- *   <li>notEndWith: 指定字段不以指定字符串结尾的条件映射（字段名 -> 不结尾值）</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>泛型设计，支持任意实体类型</li>
+ *   <li>事务管理，确保数据一致性</li>
+ *   <li>动态查询条件，支持复杂的业务查询</li>
+ *   <li>部分更新，只更新非空字段</li>
+ *   <li>可扩展的查询条件构建</li>
 * </ul>
- * </p>
 *
- * <p>
- * 前端传入的JSON格式示例:
- * <pre>
- * {
- *   "query": {
- *     "equal": {
- *       "status": "ACTIVE"
- *     },
- *     "like": {
- *       "name": "关键字"
- *     }
- *   },
- *   "sort": [
- *     {
- *       "column": "createdTime",
- *       "direction": "DESC"
- *     }
- *   ],
- *   "page": {
- *     "index": 1,
- *     "size": 10
- *   }
- * }
- * </pre>
- * </p>
+ * <h3>使用说明</h3>
+ * <p>子类可以重写以下方法：</p>
+ * <ul>
+ *   <li>listPredicate(): 添加自定义的查询条件</li>
+ * </ul>
 *
 * @param <ENTITY> 实体类型，必须继承SimpleEntity
 */
@@ -116,7 +80,7 @@ public abstract class SimpleServiceSupport<ENTITY extends SimpleEntity> implemen
   * </p>
   *
   * @param entity 需要保存的实体对象
-   * @return Long 返回保存后的实体ID
+   * @return 返回保存后的实体ID
   */
  @Transactional(rollbackOn = Throwable.class)
  @Override
@@ -143,10 +107,10 @@ public abstract class SimpleServiceSupport<ENTITY extends SimpleEntity> implemen
  /**
   * 统计符合条件的实体数量
   * <p>
-   * 根据[listPredicate](file:///Users/lanyuanxiaoyao/Project/IdeaProjects/spring-boot-service-template/src/main/java/com/lanyuanxiaoyao/service/template/service/SimpleServiceSupport.java#L261-L263)方法构建的条件统计实体数量。
+   * 根据listPredicate方法构建的条件统计实体数量。
   * </p>
   *
-   * @return Long 返回符合条件的实体数量
+   * @return 返回符合条件的实体数量
   */
  @Override
  public Long count() {
@@ -156,10 +120,10 @@ public abstract class SimpleServiceSupport<ENTITY extends SimpleEntity> implemen
  /**
   * 获取所有符合条件的实体列表
   * <p>
-   * 根据[listPredicate](file:///Users/lanyuanxiaoyao/Project/IdeaProjects/spring-boot-service-template/src/main/java/com/lanyuanxiaoyao/service/template/service/SimpleServiceSupport.java#L261-L263)方法构建的条件查询所有实体。
+   * 根据listPredicate方法构建的条件查询所有实体。
   * </p>
   *
-   * @return List<ENTITY> 返回符合条件的实体列表
+   * @return 返回符合条件的实体列表
   */
  @Override
  public List<ENTITY> list() {
@@ -169,11 +133,11 @@ public abstract class SimpleServiceSupport<ENTITY extends SimpleEntity> implemen
  /**
   * 根据ID集合获取实体列表
   * <p>
-   * 根据提供的ID集合查询对应的实体列表，并结合[listPredicate](file:///Users/lanyuanxiaoyao/Project/IdeaProjects/spring-boot-service-template/src/main/java/com/lanyuanxiaoyao/service/template/service/SimpleServiceSupport.java#L261-L263)方法构建的条件。
+   * 根据提供的ID集合查询对应的实体列表，并结合listPredicate方法构建的条件。
   * </p>
   *
   * @param ids ID集合
-   * @return List<ENTITY> 返回ID集合对应的实体列表
+   * @return 返回ID集合对应的实体列表
   */
  @Override
  public List<ENTITY> list(Set<Long> ids) {
@@ -194,14 +158,14 @@ public abstract class SimpleServiceSupport<ENTITY extends SimpleEntity> implemen
  /**
   * 解析字段路径
   * <p>
-   * 支持多级字段路径解析，使用"/"分隔多级字段。
-   * 例如: "user/name" 表示实体的user属性的name字段。
+   * 支持多级字段路径解析，使用"."分隔多级字段。
+   * 例如: "user.name" 表示实体的user属性的name字段。
   * </p>
   *
   * @param root   JPA Criteria查询根节点
   * @param column 字段路径字符串
   * @param <Y>    字段类型
-   * @return Path<Y> 返回字段路径对象
+   * @return 返回字段路径对象
   * @throws IllegalArgumentException 当字段路径为空时抛出
   */
  private <Y> Path<Y> column(Root<ENTITY> root, String column) {
@@ -220,13 +184,14 @@ public abstract class SimpleServiceSupport<ENTITY extends SimpleEntity> implemen
   * 处理字段值
   * <p>
   * 对于枚举类型字段，将字符串值转换为对应的枚举值。
+   * 对于LocalDateTime类型字段，将字符串转换为时间对象。
   * 其他类型直接返回原值。
   * </p>
   *
   * @param column 字段路径
   * @param value  字段值
   * @param <Y>    字段类型
-   * @return Object 处理后的字段值
+   * @return 处理后的字段值
   * @throws IllegalArgumentException 当枚举类型字段的值不是字符串时抛出
   */
  @SuppressWarnings({"unchecked", "rawtypes"})
@@ -259,7 +224,7 @@ public abstract class SimpleServiceSupport<ENTITY extends SimpleEntity> implemen
   * @param root      JPA Criteria查询根节点
   * @param query     JPA Criteria查询对象
   * @param builder   JPA Criteria构建器
-   * @return List<Predicate> 返回构建的谓词列表
+   * @return 返回构建的谓词列表
   */
  @SuppressWarnings("unchecked")
  protected Predicate queryPredicates(Query.Queryable queryable, Root<ENTITY> root, CriteriaQuery<?> query, CriteriaBuilder builder) {
@@ -421,6 +386,7 @@ public abstract class SimpleServiceSupport<ENTITY extends SimpleEntity> implemen
   * 检查字段类型是否可比较
   *
   * @param path   字段路径
+   * @param value  比较值
   * @param column 字段名称
   * @throws NotComparableException 当字段类型不可比较时抛出
   */
@@ -433,6 +399,7 @@ public abstract class SimpleServiceSupport<ENTITY extends SimpleEntity> implemen
  /**
   * 检查区间值是否可比较
   *
+   * @param path   字段路径
   * @param value  区间对象
   * @param column 字段名称
   * @throws NotComparableException 当区间值不可比较时抛出
@@ -472,6 +439,7 @@ public abstract class SimpleServiceSupport<ENTITY extends SimpleEntity> implemen
   * 检查字段类型是否为字符串
   *
   * @param path   字段路径
+   * @param value  比较值
   * @param column 字段名称
   * @throws NotStringException 当字段类型不是字符串时抛出
   */
@@ -485,13 +453,13 @@ public abstract class SimpleServiceSupport<ENTITY extends SimpleEntity> implemen
   * 构建列表查询条件
   * <p>
   * 子类可以重写此方法以添加特定的查询条件。
-   * 默认返回空列表，表示不添加额外条件。
+   * 默认返回null，表示不添加额外条件。
   * </p>
   *
   * @param root    JPA Criteria查询根节点
   * @param query   JPA Criteria查询对象
   * @param builder JPA Criteria构建器
-   * @return List<Predicate> 返回查询条件谓词列表
+   * @return 返回查询条件谓词
   */
  protected Predicate listPredicate(Root<ENTITY> root, CriteriaQuery<?> query, CriteriaBuilder builder) {
    return null;
@@ -505,7 +473,7 @@ public abstract class SimpleServiceSupport<ENTITY extends SimpleEntity> implemen
   * </p>
   *
   * @param listQuery 查询条件对象
-   * @return Page<ENTITY> 返回分页查询结果
+   * @return 返回分页查询结果
   */
  @Override
  public Page<ENTITY> list(Query listQuery) {
@@ -544,7 +512,7 @@ public abstract class SimpleServiceSupport<ENTITY extends SimpleEntity> implemen
   * </p>
   *
   * @param id 实体ID
-   * @return Optional<ENTITY> 返回实体详情的Optional包装
+   * @return 返回实体详情的Optional包装
   */
  private Optional<ENTITY> detailOptional(Long id) {
    if (ObjectHelper.isNull(id)) {
@@ -568,7 +536,7 @@ public abstract class SimpleServiceSupport<ENTITY extends SimpleEntity> implemen
   * </p>
   *
   * @param id 实体ID
-   * @return ENTITY 返回实体详情，不存在时返回null
+   * @return 返回实体详情，不存在时返回null
   */
  @Named("detail")
  @Override
@@ -583,7 +551,7 @@ public abstract class SimpleServiceSupport<ENTITY extends SimpleEntity> implemen
   * </p>
   *
   * @param id 实体ID
-   * @return ENTITY 返回实体详情
+   * @return 返回实体详情
   * @throws IdNotFoundException 当实体不存在时抛出
   */
  @Named("detailOrThrow")
@@ -599,7 +567,7 @@ public abstract class SimpleServiceSupport<ENTITY extends SimpleEntity> implemen
   * 如果ID为空则不执行任何操作。
   * </p>
   *
-   * @param id 实体ID
+   * @param id 实体主键ID
   */
  @Transactional(rollbackOn = Throwable.class)
  @Override
@@ -617,7 +585,7 @@ public abstract class SimpleServiceSupport<ENTITY extends SimpleEntity> implemen
   * 如果ID集合为空则不执行任何操作。
   * </p>
   *
-   * @param ids 实体ID集合
+   * @param ids 实体主键ID集合
   */
  @Transactional(rollbackOn = Throwable.class)
  @Override