refactor(common): 将包结构从 jpa 迁移至 common 并重构核心类

- 将所有控制器接口从 jpa 包迁移至 common 包
- 将 GlobalResponse、Query、Page 等核心类重构为 record 类型
- 移除 Lombok 依赖并简化代码结构
- 更新 SimpleService 接口以支持更通用的实体类型
- 调整 SimpleControllerSupport 和 SimpleServiceSupport 以适配新的 API
- 清理 web 模块的 pom.xml 中的冗余依赖和配置

spring-boot-service-template-common/src/main/java/com/lanyuanxiaoyao/service/template/common/controller/DetailController.java

@@ -0,0 +1,27 @@
+package com.lanyuanxiaoyao.service.template.common.controller;
+
+/**
+ * 详情控制器接口，用于定义统一的获取实体详情的接口规范
+ *
+ * <p>
+ * 前端传入的JSON格式示例:
+ * <pre>
+ * GET /detail/1
+ * </pre>
+ * </p>
+ *
+ * @param <DETAIL_ITEM> 详情实体类型
+ * @author lanyuanxiaoyao
+ */
+public interface DetailController<DETAIL_ITEM> {
+  String DETAIL = "/detail/{id}";
+
+  /**
+   * 根据ID获取实体详情
+   *
+   * @param id 实体ID
+   * @return GlobalResponse<DETAIL_ITEM> 返回实体详情
+   * @throws Exception 查询过程中可能抛出的异常
+   */
+  GlobalResponse<DETAIL_ITEM> detail(Long id) throws Exception;
+}

spring-boot-service-template-common/src/main/java/com/lanyuanxiaoyao/service/template/common/controller/GlobalResponse.java

@@ -0,0 +1,58 @@
+package com.lanyuanxiaoyao.service.template.common.controller;
+
+import java.util.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";
+
+  public static GlobalResponse<Object> responseError() {
+    return responseError(ERROR_MESSAGE);
+  }
+
+  public static GlobalResponse<Object> responseError(String message) {
+    return new GlobalResponse<>(ERROR_STATUS, message, null);
+  }
+
+  public static GlobalResponse<Object> responseSuccess() {
+    return responseSuccess(SUCCESS_MESSAGE);
+  }
+
+  public static GlobalResponse<Object> responseSuccess(String message) {
+    return responseSuccess(message, null);
+  }
+
+  public static <E> GlobalResponse<E> responseSuccess(E data) {
+    return responseSuccess(SUCCESS_MESSAGE, data);
+  }
+
+  public static <E> GlobalResponse<E> responseSuccess(String message, E data) {
+    return new GlobalResponse<>(SUCCESS_STATUS, message, data);
+  }
+
+  public static GlobalResponse<Map<String, Object>> responseMapData(Map<String, Object> data) {
+    return responseSuccess(data);
+  }
+
+  public static GlobalResponse<Map<String, Object>> responseMapData(String key, Object value) {
+    return responseMapData(Map.of(key, value));
+  }
+
+  public static <T> GlobalResponse<Map<String, Object>> responseCrudData(Iterable<T> data, Integer total) {
+    return responseCrudData(data, total.longValue());
+  }
+
+  public static <T> GlobalResponse<Map<String, Object>> responseCrudData(Iterable<T> data, Long total) {
+    return responseMapData(Map.of("items", data, "total", total));
+  }
+
+  public static GlobalResponse<Map<String, Object>> responseDetailData(Object detail) {
+    return responseMapData("detail", detail);
+  }
+}

spring-boot-service-template-common/src/main/java/com/lanyuanxiaoyao/service/template/common/controller/ListController.java

@@ -0,0 +1,78 @@
+package com.lanyuanxiaoyao.service.template.common.controller;
+
+import java.util.Map;
+
+/**
+ * 列表控制器接口，用于定义统一的获取实体列表的接口规范
+ *
+ * <p>
+ * 前端传入的JSON格式示例:
+ * <pre>
+ * {
+ *   "query": {
+ *     "equal": {
+ *       "status": "ACTIVE"
+ *     },
+ *     "like": {
+ *       "name": "关键字"
+ *     }
+ *   },
+ *   "sort": [
+ *     {
+ *       "column": "createTime",
+ *       "direction": "DESC"
+ *     }
+ *   ],
+ *   "page": {
+ *     "index": 0,
+ *     "size": 10
+ *   }
+ * }
+ * </pre>
+ * </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>
+ * </ul>
+ * </p>
+ *
+ * @param <LIST_ITEM> 列表项的实体类型
+ * @author lanyuanxiaoyao
+ */
+public interface ListController<LIST_ITEM> {
+  String LIST = "/list";
+
+  /**
+   * 获取所有实体列表
+   *
+   * @return GlobalCrudResponse<LIST_ITEM> 返回实体列表
+   * @throws Exception 查询过程中可能抛出的异常
+   */
+  GlobalResponse<Map<String, Object>> list() throws Exception;
+
+  /**
+   * 根据查询条件获取实体列表
+   *
+   * @param query 查询条件对象
+   * @return GlobalCrudResponse<LIST_ITEM> 返回符合条件的实体列表
+   * @throws Exception 查询过程中可能抛出的异常
+   */
+  GlobalResponse<Map<String, Object>> list(Query query) throws Exception;
+}

spring-boot-service-template-common/src/main/java/com/lanyuanxiaoyao/service/template/common/controller/Query.java

@@ -0,0 +1,133 @@
+package com.lanyuanxiaoyao.service.template.common.controller;
+
+import java.util.List;
+import java.util.Map;
+
+/**
+ * 查询条件封装类，用于构建复杂的查询条件
+ * 包含查询条件、排序条件和分页条件
+ *
+ * <p>前端传入的JSON格式示例:</p>
+ * <pre>
+ * {
+ *   "query": {
+ *     "equal": {
+ *       "name": "张三"
+ *     },
+ *     "like": {
+ *       "address": "%北京%"
+ *     },
+ *     "greatEqual": {
+ *       "age": 18
+ *     },
+ *     "less": {
+ *       "age": 60
+ *     },
+ *     "between": {
+ *       "salary": {
+ *         "start": 5000,
+ *         "end": 10000
+ *       }
+ *     }
+ *   },
+ *   "sort": [
+ *     {
+ *       "column": "createTime",
+ *       "direction": "DESC"
+ *     }
+ *   ],
+ *   "page": {
+ *     "index": 0,
+ *     "size": 10
+ *   }
+ * }
+ * </pre>
+ *
+ * <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>
+ * </ul>
+ */
+public record Query(
+    Queryable query,
+    List<Sortable> sort,
+    Pageable page
+) {
+  /**
+   * 可查询条件类，封装各种查询条件
+   */
+  public record Queryable(
+      List<String> nullEqual,
+      List<String> notNullEqual,
+      List<String> empty,
+      List<String> notEmpty,
+      Map<String, Object> equal,
+      Map<String, Object> notEqual,
+      Map<String, String> like,
+      Map<String, String> notLike,
+      Map<String, String> contain,
+      Map<String, String> notContain,
+      Map<String, String> startWith,
+      Map<String, String> notStartWith,
+      Map<String, String> endWith,
+      Map<String, String> notEndWith,
+      Map<String, Object> great,
+      Map<String, Object> less,
+      Map<String, Object> greatEqual,
+      Map<String, Object> lessEqual,
+      Map<String, List<Object>> inside,
+      Map<String, List<Object>> notInside,
+      Map<String, Between> between,
+      Map<String, Between> notBetween
+  ) {
+    /**
+     * 区间范围类，用于表示起始值和结束值
+     */
+    public record Between(
+        Object start,
+        Object end
+    ) {
+    }
+  }
+
+
+  public record Sortable(
+      String column,
+      Direction direction
+  ) {
+    public enum Direction {
+      /**
+       * 升序排列
+       */
+      ASC,
+      /**
+       * 降序排列
+       */
+      DESC,
+    }
+  }
+
+  /**
+   * 可分页条件类，用于指定分页参数
+   */
+  public record Pageable(
+      Integer index,
+      Integer size
+  ) {
+  }
+}

spring-boot-service-template-common/src/main/java/com/lanyuanxiaoyao/service/template/common/controller/RemoveController.java

@@ -0,0 +1,26 @@
+package com.lanyuanxiaoyao.service.template.common.controller;
+
+/**
+ * 删除控制器接口，用于定义统一的删除实体对象的接口规范
+ *
+ * <p>
+ * 前端传入的JSON格式示例:
+ * <pre>
+ * DELETE /remove/1
+ * </pre>
+ * </p>
+ *
+ * @author lanyuanxiaoyao
+ */
+public interface RemoveController {
+  String REMOVE = "/remove/{id}";
+
+  /**
+   * 根据ID删除实体对象
+   *
+   * @param id 需要删除的实体ID
+   * @return GlobalResponse<Object> 返回删除结果
+   * @throws Exception 删除过程中可能抛出的异常
+   */
+  GlobalResponse<Object> remove(Long id) throws Exception;
+}

spring-boot-service-template-common/src/main/java/com/lanyuanxiaoyao/service/template/common/controller/SaveController.java

@@ -0,0 +1,30 @@
+package com.lanyuanxiaoyao.service.template.common.controller;
+
+/**
+ * 保存控制器接口，用于定义统一的保存实体对象的接口规范
+ *
+ * <p>
+ * 前端传入的JSON格式示例:
+ * <pre>
+ * {
+ *   // 实体对象的具体字段
+ *   "name": "示例名称",
+ *   "description": "示例描述"
+ * }
+ * </pre>
+ * </p>
+ *
+ * @author lanyuanxiaoyao
+ */
+public interface SaveController<SAVE_ITEM> {
+  String SAVE = "/save";
+
+  /**
+   * 保存实体对象
+   *
+   * @param item 需要保存的实体对象
+   * @return GlobalResponse<Long> 返回保存后的实体ID
+   * @throws Exception 保存过程中可能抛出的异常
+   */
+  GlobalResponse<Long> save(SAVE_ITEM item) throws Exception;
+}

spring-boot-service-template-common/src/main/java/com/lanyuanxiaoyao/service/template/common/controller/SimpleController.java

@@ -0,0 +1,4 @@
+package com.lanyuanxiaoyao.service.template.common.controller;
+
+public interface SimpleController<SAVE_ITEM, LIST_ITEM, DETAIL_ITEM> extends SaveController<SAVE_ITEM>, ListController<LIST_ITEM>, DetailController<DETAIL_ITEM>, RemoveController {
+}

spring-boot-service-template-common/src/main/java/com/lanyuanxiaoyao/service/template/common/service/Page.java

@@ -0,0 +1,12 @@
+package com.lanyuanxiaoyao.service.template.common.service;
+
+import java.util.stream.Stream;
+
+/**
+ * 分页
+ *
+ * @author lanyuanxiaoyao
+ * @version 20260106
+ */
+public record Page<ENTITY>(Stream<ENTITY> items, long total) {
+}

spring-boot-service-template-common/src/main/java/com/lanyuanxiaoyao/service/template/common/service/SimpleService.java

@@ -0,0 +1,27 @@
+package com.lanyuanxiaoyao.service.template.common.service;
+
+import com.lanyuanxiaoyao.service.template.common.controller.Query;
+import java.util.List;
+import java.util.Set;
+
+public interface SimpleService<ENTITY> {
+  Long save(ENTITY entity) throws Exception;
+
+  void save(Iterable<ENTITY> entities) throws Exception;
+
+  Long count() throws Exception;
+
+  List<ENTITY> list() throws Exception;
+
+  List<ENTITY> list(Set<Long> ids) throws Exception;
+
+  Page<ENTITY> list(Query query) throws Exception;
+
+  ENTITY detail(Long id) throws Exception;
+
+  ENTITY detailOrThrow(Long id) throws Exception;
+
+  void remove(Long id) throws Exception;
+
+  void remove(Iterable<Long> ids) throws Exception;
+}