From d88078ce4294c7af24fe8d81a749481e184e0aca Mon Sep 17 00:00:00 2001
From: lanyuanxiaoyao <lanyuanxiaoyao@gmail.com>
Date: Tue, 6 Jan 2026 14:49:07 +0800
Subject: [PATCH] =?UTF-8?q?refactor(common):=20=E4=BC=98=E5=8C=96=E7=BB=A7?=
 =?UTF-8?q?=E6=89=BF=E7=BB=93=E6=9E=84=EF=BC=8C=E5=90=88=E5=B9=B6list?=
 =?UTF-8?q?=E5=92=8Cdetail=E6=9F=A5=E8=AF=A2?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../common/controller/DetailController.java   | 27 --------
 ...stController.java => QueryController.java} | 20 ++++--
 .../common/controller/SimpleController.java   |  2 +-
 .../template/common/service/QueryService.java | 65 +++++++++++++++++++
 .../common/service/RemoveService.java         | 25 +++++++
 .../template/common/service/SaveService.java  | 26 ++++++++
 .../common/service/SimpleService.java         | 25 +------
 7 files changed, 133 insertions(+), 57 deletions(-)
 delete mode 100644 spring-boot-service-template-common/src/main/java/com/lanyuanxiaoyao/service/template/common/controller/DetailController.java
 rename spring-boot-service-template-common/src/main/java/com/lanyuanxiaoyao/service/template/common/controller/{ListController.java => QueryController.java} (79%)
 create mode 100644 spring-boot-service-template-common/src/main/java/com/lanyuanxiaoyao/service/template/common/service/QueryService.java
 create mode 100644 spring-boot-service-template-common/src/main/java/com/lanyuanxiaoyao/service/template/common/service/RemoveService.java
 create mode 100644 spring-boot-service-template-common/src/main/java/com/lanyuanxiaoyao/service/template/common/service/SaveService.java

diff --git a/spring-boot-service-template-common/src/main/java/com/lanyuanxiaoyao/service/template/common/controller/DetailController.java b/spring-boot-service-template-common/src/main/java/com/lanyuanxiaoyao/service/template/common/controller/DetailController.java
deleted file mode 100644
index f065436..0000000
--- a/spring-boot-service-template-common/src/main/java/com/lanyuanxiaoyao/service/template/common/controller/DetailController.java
+++ /dev/null
@@ -1,27 +0,0 @@
-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;
-}
\ No newline at end of file
diff --git a/spring-boot-service-template-common/src/main/java/com/lanyuanxiaoyao/service/template/common/controller/ListController.java b/spring-boot-service-template-common/src/main/java/com/lanyuanxiaoyao/service/template/common/controller/QueryController.java
similarity index 79%
rename from spring-boot-service-template-common/src/main/java/com/lanyuanxiaoyao/service/template/common/controller/ListController.java
rename to spring-boot-service-template-common/src/main/java/com/lanyuanxiaoyao/service/template/common/controller/QueryController.java
index d34a878..5d5c1d6 100644
--- a/spring-boot-service-template-common/src/main/java/com/lanyuanxiaoyao/service/template/common/controller/ListController.java
+++ b/spring-boot-service-template-common/src/main/java/com/lanyuanxiaoyao/service/template/common/controller/QueryController.java
@@ -3,7 +3,7 @@ package com.lanyuanxiaoyao.service.template.common.controller;
 import java.util.Map;
 
 /**
- * 列表控制器接口，用于定义统一的获取实体列表的接口规范
+ * 查询控制器接口，用于定义统一的查询实体详情和列表的接口规范
  *
  * <p>
  * 前端传入的JSON格式示例:
@@ -53,16 +53,17 @@ import java.util.Map;
  * </ul>
  * </p>
  *
- * @param <LIST_ITEM> 列表项的实体类型
+ * @param <QUERY_ITEM> 查询结果的实体类型
  * @author lanyuanxiaoyao
  */
-public interface ListController<LIST_ITEM> {
+public interface QueryController<QUERY_ITEM> {
   String LIST = "/list";
+  String DETAIL = "/detail/{id}";
 
   /**
    * 获取所有实体列表
    *
-   * @return GlobalCrudResponse<LIST_ITEM> 返回实体列表
+   * @return GlobalResponse<Map<String, Object>> 返回实体列表
    * @throws Exception 查询过程中可能抛出的异常
    */
   GlobalResponse<Map<String, Object>> list() throws Exception;
@@ -71,8 +72,17 @@ public interface ListController<LIST_ITEM> {
    * 根据查询条件获取实体列表
    *
    * @param query 查询条件对象
-   * @return GlobalCrudResponse<LIST_ITEM> 返回符合条件的实体列表
+   * @return GlobalResponse<Map<String, Object>> 返回符合条件的实体列表
    * @throws Exception 查询过程中可能抛出的异常
    */
   GlobalResponse<Map<String, Object>> list(Query query) throws Exception;
+
+  /**
+   * 根据ID获取实体详情
+   *
+   * @param id 实体ID
+   * @return GlobalResponse<QUERY_ITEM> 返回实体详情
+   * @throws Exception 查询过程中可能抛出的异常
+   */
+  GlobalResponse<QUERY_ITEM> detail(Long id) throws Exception;
 }
\ No newline at end of file
diff --git a/spring-boot-service-template-common/src/main/java/com/lanyuanxiaoyao/service/template/common/controller/SimpleController.java b/spring-boot-service-template-common/src/main/java/com/lanyuanxiaoyao/service/template/common/controller/SimpleController.java
index 3dc771b..eb159fb 100644
--- a/spring-boot-service-template-common/src/main/java/com/lanyuanxiaoyao/service/template/common/controller/SimpleController.java
+++ b/spring-boot-service-template-common/src/main/java/com/lanyuanxiaoyao/service/template/common/controller/SimpleController.java
@@ -1,4 +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 {
+public interface SimpleController<SAVE_ITEM, LIST_ITEM, DETAIL_ITEM> extends SaveController<SAVE_ITEM>, QueryController<DETAIL_ITEM>, RemoveController {
 }
diff --git a/spring-boot-service-template-common/src/main/java/com/lanyuanxiaoyao/service/template/common/service/QueryService.java b/spring-boot-service-template-common/src/main/java/com/lanyuanxiaoyao/service/template/common/service/QueryService.java
new file mode 100644
index 0000000..9f02ad4
--- /dev/null
+++ b/spring-boot-service-template-common/src/main/java/com/lanyuanxiaoyao/service/template/common/service/QueryService.java
@@ -0,0 +1,65 @@
+package com.lanyuanxiaoyao.service.template.common.service;
+
+import com.lanyuanxiaoyao.service.template.common.controller.Query;
+import java.util.List;
+import java.util.Set;
+
+/**
+ * 查询服务接口，用于定义统一的查询实体详情和列表的服务规范
+ *
+ * @param <ENTITY> 实体类型
+ * @author lanyuanxiaoyao
+ */
+public interface QueryService<ENTITY> {
+  /**
+   * 根据ID获取实体详情
+   *
+   * @param id 实体ID
+   * @return 实体详情
+   * @throws Exception 查询过程中可能抛出的异常
+   */
+  ENTITY detail(Long id) throws Exception;
+
+  /**
+   * 根据ID获取实体详情，如果不存在则抛出异常
+   *
+   * @param id 实体ID
+   * @return 实体详情
+   * @throws Exception 查询过程中可能抛出的异常
+   */
+  ENTITY detailOrThrow(Long id) throws Exception;
+
+  /**
+   * 获取实体总数
+   *
+   * @return 实体总数
+   * @throws Exception 查询过程中可能抛出的异常
+   */
+  Long count() throws Exception;
+
+  /**
+   * 获取所有实体列表
+   *
+   * @return 实体列表
+   * @throws Exception 查询过程中可能抛出的异常
+   */
+  List<ENTITY> list() throws Exception;
+
+  /**
+   * 根据ID集合获取实体列表
+   *
+   * @param ids 实体ID集合
+   * @return 实体列表
+   * @throws Exception 查询过程中可能抛出的异常
+   */
+  List<ENTITY> list(Set<Long> ids) throws Exception;
+
+  /**
+   * 根据查询条件获取分页实体列表
+   *
+   * @param query 查询条件对象
+   * @return 分页实体列表
+   * @throws Exception 查询过程中可能抛出的异常
+   */
+  Page<ENTITY> list(Query query) throws Exception;
+}
\ No newline at end of file
diff --git a/spring-boot-service-template-common/src/main/java/com/lanyuanxiaoyao/service/template/common/service/RemoveService.java b/spring-boot-service-template-common/src/main/java/com/lanyuanxiaoyao/service/template/common/service/RemoveService.java
new file mode 100644
index 0000000..3505b95
--- /dev/null
+++ b/spring-boot-service-template-common/src/main/java/com/lanyuanxiaoyao/service/template/common/service/RemoveService.java
@@ -0,0 +1,25 @@
+package com.lanyuanxiaoyao.service.template.common.service;
+
+/**
+ * 删除服务接口，用于定义统一的删除实体对象的服务规范
+ *
+ * @param <ENTITY> 实体类型
+ * @author lanyuanxiaoyao
+ */
+public interface RemoveService<ENTITY> {
+  /**
+   * 根据ID删除实体对象
+   *
+   * @param id 需要删除的实体ID
+   * @throws Exception 删除过程中可能抛出的异常
+   */
+  void remove(Long id) throws Exception;
+
+  /**
+   * 批量删除实体对象
+   *
+   * @param ids 需要删除的实体ID集合
+   * @throws Exception 删除过程中可能抛出的异常
+   */
+  void remove(Iterable<Long> ids) throws Exception;
+}
\ No newline at end of file
diff --git a/spring-boot-service-template-common/src/main/java/com/lanyuanxiaoyao/service/template/common/service/SaveService.java b/spring-boot-service-template-common/src/main/java/com/lanyuanxiaoyao/service/template/common/service/SaveService.java
new file mode 100644
index 0000000..8bdcdf3
--- /dev/null
+++ b/spring-boot-service-template-common/src/main/java/com/lanyuanxiaoyao/service/template/common/service/SaveService.java
@@ -0,0 +1,26 @@
+package com.lanyuanxiaoyao.service.template.common.service;
+
+/**
+ * 保存服务接口，用于定义统一的保存实体对象的服务规范
+ *
+ * @param <ENTITY> 实体类型
+ * @author lanyuanxiaoyao
+ */
+public interface SaveService<ENTITY> {
+  /**
+   * 保存实体对象
+   *
+   * @param entity 需要保存的实体对象
+   * @return 保存后的实体ID
+   * @throws Exception 保存过程中可能抛出的异常
+   */
+  Long save(ENTITY entity) throws Exception;
+
+  /**
+   * 批量保存实体对象
+   *
+   * @param entities 需要保存的实体对象集合
+   * @throws Exception 保存过程中可能抛出的异常
+   */
+  void save(Iterable<ENTITY> entities) throws Exception;
+}
\ No newline at end of file
diff --git a/spring-boot-service-template-common/src/main/java/com/lanyuanxiaoyao/service/template/common/service/SimpleService.java b/spring-boot-service-template-common/src/main/java/com/lanyuanxiaoyao/service/template/common/service/SimpleService.java
index de02767..11df5c1 100644
--- a/spring-boot-service-template-common/src/main/java/com/lanyuanxiaoyao/service/template/common/service/SimpleService.java
+++ b/spring-boot-service-template-common/src/main/java/com/lanyuanxiaoyao/service/template/common/service/SimpleService.java
@@ -1,27 +1,4 @@
 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;
+public interface SimpleService<ENTITY> extends SaveService<ENTITY>, QueryService<ENTITY>, RemoveService<ENTITY> {
 }