From 327e983c466dffa4cfb2e91a4233635db44f786c Mon Sep 17 00:00:00 2001 From: lanyuanxiaoyao Date: Tue, 6 Jan 2026 15:50:36 +0800 Subject: [PATCH] =?UTF-8?q?doc(common):=20=E4=BC=98=E5=8C=96=E7=BB=9F?= =?UTF-8?q?=E4=B8=80=E5=93=8D=E5=BA=94=E5=92=8C=E5=B7=A5=E5=85=B7=E7=B1=BB?= =?UTF-8?q?=E6=B3=A8=E9=87=8A?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../common/controller/GlobalResponse.java | 252 ++++++++++++++---- .../common/controller/QueryController.java | 78 ++---- .../common/controller/RemoveController.java | 15 +- .../common/controller/SaveController.java | 21 +- .../template/common/helper/ObjectHelper.java | 119 +++++++-- .../service/template/common/service/Page.java | 24 +- .../template/common/service/QueryService.java | 41 ++- .../common/service/RemoveService.java | 15 +- .../template/common/service/SaveService.java | 17 +- .../controller/SimpleControllerSupport.java | 122 ++++----- .../jpa/service/SimpleServiceSupport.java | 108 +++----- 11 files changed, 510 insertions(+), 302 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 539ce90..c61f768 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 @@ -4,69 +4,121 @@ import java.util.List; import java.util.Map; /** - * 全局响应对象 + * 全局统一API响应封装类 *

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

* - *

- * 响应格式示例: + *

设计特点

+ * + * + *

响应格式示例

+ *

成功响应（无数据）:

+ * 
+ * {
+ *   "status": 0,
+ *   "message": "OK",
+ *   "data": null
+ * }
+ *
+ * + *

成功响应（带数据）:

+ * 
+ * {
+ *   "status": 0,
+ *   "message": "操作成功",
+ *   "data": {
+ *     "id": 1,
+ *     "name": "示例数据"
+ *   }
+ * }
+ *
+ * + *

分页列表响应:

* 
  * {
  *   "status": 0,
  *   "message": "OK",
  *   "data": {
- *     "items": [...],
- *     "total": 10
+ *     "items": [
+ *       {"id": 1, "name": "数据1"},
+ *       {"id": 2, "name": "数据2"}
+ *     ],
+ *     "total": 100
  *   }
  * }
  *
- *

* - *

- * 使用说明: + *

错误响应:

+ * 
+ * {
+ *   "status": 500,
+ *   "message": "系统异常，请稍后重试",
+ *   "data": null
+ * }
+ *
+ * + *

使用场景

* - *

* - * @param 响应数据的类型 - * @param status 响应状态码，0表示成功，500表示错误，其他值可根据业务需求扩展 + * @param 响应数据的类型，可以是任意对象、集合、Map或包装类 + * @param status 响应状态码 + *
    + *
  • 0 - 成功
    • + *
  • 500 - 服务器错误
    • + *
  • 其他 - 业务自定义状态码
    • + *
* @param message 响应消息，对状态码的简短描述，如"OK"、"ERROR"或具体的错误信息 * @param data 响应数据，具体的业务数据，可以是任意类型。对于列表查询，通常封装为包含items和total的Map；对于详情查询，直接返回对象或Map + * + * @see #responseSuccess() + * @see #responseError() + * @see #responseListData(Iterable, Long) + * @see #responseDetailData(Object) */ 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 + * 使用默认错误消息"ERROR"，状态码500，数据为null。 + * 适用于无法确定具体错误原因的通用异常场景。 *

* - * @return 错误响应对象 + * @return 错误响应对象，格式：{status: 500, message: "ERROR", data: null} + * + * @see #responseError(String) + * @see #responseSuccess() */ public static GlobalResponse responseError() { return responseError(ERROR_MESSAGE); @@ -75,11 +127,15 @@ public record GlobalResponse(Integer status, String message, T data) { /** * 返回指定错误消息的响应 *

- * 使用指定的错误消息，状态码500，数据为null + * 使用指定的错误消息，状态码500，数据为null。 + * 适用于需要向客户端传递具体错误信息的场景。 *

* - * @param message 错误消息内容 - * @return 错误响应对象 + * @param message 错误消息内容，建议描述具体错误原因，便于前端展示和问题定位 + * @return 错误响应对象，格式：{status: 500, message: "自定义错误信息", data: null} + * + * @see #responseError() + * @see #responseSuccess(String) */ public static GlobalResponse responseError(String message) { return new GlobalResponse<>(ERROR_STATUS, message, null); @@ -88,10 +144,15 @@ public record GlobalResponse(Integer status, String message, T data) { /** * 返回默认成功响应 *

- * 使用默认成功消息"OK"，状态码0，数据为null + * 使用默认成功消息"OK"，状态码0，数据为null。 + * 适用于操作成功但不需要返回数据的场景。 *

* - * @return 成功响应对象 + * @return 成功响应对象，格式：{status: 0, message: "OK", data: null} + * + * @see #responseSuccess(String) + * @see #responseSuccess(Object) + * @see #responseError() */ public static GlobalResponse responseSuccess() { return responseSuccess(SUCCESS_MESSAGE); @@ -100,11 +161,16 @@ public record GlobalResponse(Integer status, String message, T data) { /** * 返回指定成功消息的响应 *

- * 使用指定的成功消息，状态码0，数据为null + * 使用指定的成功消息，状态码0，数据为null。 + * 适用于需要向客户端返回自定义成功提示的场景。 *

* - * @param message 成功消息内容 - * @return 成功响应对象 + * @param message 成功消息内容，建议描述具体操作结果，便于用户理解 + * @return 成功响应对象，格式：{status: 0, message: "自定义成功信息", data: null} + * + * @see #responseSuccess() + * @see #responseSuccess(Object) + * @see #responseSuccess(String, Object) */ public static GlobalResponse responseSuccess(String message) { return responseSuccess(message, null); @@ -113,12 +179,17 @@ public record GlobalResponse(Integer status, String message, T data) { /** * 返回包含数据的成功响应 *

- * 使用默认成功消息"OK"，状态码0，包含指定数据 + * 使用默认成功消息"OK"，状态码0，包含指定数据。 + * 适用于需要返回数据但不需要自定义消息的场景。 *

* - * @param 数据类型 - * @param data 业务数据 - * @return 成功响应对象 + * @param 数据类型，可以是任意Java对象 + * @param data 业务数据，可以是实体对象、Map、集合等 + * @return 成功响应对象，格式：{status: 0, message: "OK", data: 业务数据} + * + * @see #responseSuccess(String, Object) + * @see #responseListData(Iterable, Long) + * @see #responseDetailData(Object) */ public static GlobalResponse responseSuccess(E data) { return responseSuccess(SUCCESS_MESSAGE, data); @@ -127,13 +198,18 @@ public record GlobalResponse(Integer status, String message, T data) { /** * 返回包含指定消息和数据的成功响应 *

- * 使用指定的成功消息，状态码0，包含指定数据 + * 使用指定的成功消息，状态码0，包含指定数据。 + * 这是最完整的方法，适用于需要同时自定义消息和返回数据的场景。 *

* * @param 数据类型 - * @param message 成功消息内容 - * @param data 业务数据 - * @return 成功响应对象 + * @param message 成功消息内容，描述具体操作结果 + * @param data 业务数据，可以是任意类型 + * @return 成功响应对象，格式：{status: 0, message: "自定义消息", data: 业务数据} + * + * @see #responseSuccess() + * @see #responseSuccess(Object) + * @see #responseSuccess(String) */ public static GlobalResponse responseSuccess(String message, E data) { return new GlobalResponse<>(SUCCESS_STATUS, message, data); @@ -142,11 +218,15 @@ public record GlobalResponse(Integer status, String message, T data) { /** * 返回Map类型数据的成功响应 *

- * 适用于需要返回结构化数据的场景，如分页查询结果 + * 适用于需要返回结构化数据的场景，如分页查询结果、统计信息等。 + * 内部使用responseSuccess方法封装。 *

* - * @param data Map格式的业务数据 - * @return 成功响应对象 + * @param data Map格式的业务数据，键为String，值为任意对象 + * @return 成功响应对象，格式：{status: 0, message: "OK", data: Map数据} + * + * @see #responseMapData(String, Object) + * @see #responseSuccess(Object) */ public static GlobalResponse> responseMapData(Map data) { return responseSuccess(data); @@ -155,17 +235,32 @@ public record GlobalResponse(Integer status, String message, T data) { /** * 返回单个键值对的成功响应 *

- * 将单个键值对封装为Map后返回 + * 将单个键值对封装为Map后返回，适用于返回单个配置项或简单结果的场景。 *

* - * @param key 数据键名 - * @param value 数据值 - * @return 成功响应对象 + * @param key 数据键名，不能为null + * @param value 数据值，可以是任意对象 + * @return 成功响应对象，格式：{status: 0, message: "OK", data: {key: value}} + * + * @see #responseMapData(Map) + * @see #responseSuccess(Object) */ public static GlobalResponse> responseMapData(String key, Object value) { return responseMapData(Map.of(key, value)); } + /** + * 返回空列表的成功响应 + *

+ * 适用于查询结果为空的场景，返回空列表和总数为0。 + *

+ * + * @param 数据项类型 + * @return 成功响应对象，格式：{status: 0, message: "OK", data: {items: [], total: 0}} + * + * @see #responseListData(Iterable, Long) + * @see #responseListData(Iterable, Integer) + */ public static GlobalResponse> responseListData() { return responseListData(List.of(), 0); } @@ -173,13 +268,18 @@ public record GlobalResponse(Integer status, String message, T data) { /** * 返回CRUD列表数据的成功响应（Integer类型总数） *

- * 适用于分页查询，将数据列表和总数封装为Map格式 + * 适用于分页查询，将数据列表和总数封装为标准格式。 + * 自动将Integer类型的总数转换为Long类型。 *

* * @param 数据项类型 - * @param data 数据列表 - * @param total 总记录数 - * @return 成功响应对象 + * @param data 数据列表，可以是List、Set等Iterable实现 + * @param total 总记录数，Integer类型 + * @return 成功响应对象，格式：{status: 0, message: "OK", data: {items: [...], total: total}} + * + * @see #responseListData(Iterable, Long) + * @see #responseListData() + * @see #responseSuccess(Object) */ public static GlobalResponse> responseListData(Iterable data, Integer total) { return responseListData(data, total.longValue()); @@ -188,13 +288,19 @@ public record GlobalResponse(Integer status, String message, T data) { /** * 返回CRUD列表数据的成功响应（Long类型总数） *

- * 适用于分页查询，将数据列表和总数封装为Map格式 + * 适用于分页查询，将数据列表和总数封装为标准格式。 + * 支持大数据量场景，使用Long类型避免整数溢出。 *

* * @param 数据项类型 - * @param data 数据列表 - * @param total 总记录数 - * @return 成功响应对象 + * @param data 数据列表，可以是List、Set等Iterable实现 + * @param total 总记录数，Long类型，支持大数据量 + * @return 成功响应对象，格式：{status: 0, message: "OK", data: {items: [...], total: total}} + * + * @see #responseListData(Iterable, Integer) + * @see #responseListData() + * @see ListItem + * @see #responseSuccess(Object) */ public static GlobalResponse> responseListData(Iterable data, Long total) { return responseSuccess(new ListItem<>(data, total)); @@ -203,19 +309,51 @@ public record GlobalResponse(Integer status, String message, T data) { /** * 返回详情数据的成功响应 *

- * 适用于详情查询，将单条记录封装为Map格式 + * 适用于详情查询，将单条记录封装为标准格式。 + * 便于前端统一处理详情数据的展示。 *

* - * @param data 详情数据 - * @return 成功响应对象 + * @param 数据类型 + * @param data 详情数据，可以是实体对象、Map等 + * @return 成功响应对象，格式：{status: 0, message: "OK", data: {item: 详情数据}} + * + * @see #responseSuccess(Object) + * @see DetailItem */ public static GlobalResponse> responseDetailData(T data) { return responseSuccess(new DetailItem<>(data)); } + /** + * 列表数据封装类 + *

+ * 用于封装分页查询的结果，包含数据列表和总记录数。 + * 便于前端进行分页控件的渲染和数据展示。 + *

+ * + * @param 数据项类型 + * @param items 数据列表，包含当前页的所有记录 + * @param total 总记录数，用于计算总页数和显示分页信息 + * + * @see #responseListData(Iterable, Long) + */ public record ListItem(Iterable items, Long total) { } + /** + * 详情数据封装类 + *

+ * 用于封装单条记录的查询结果，提供统一的详情数据结构。 + * 便于前端统一处理详情页面的数据展示。 + *

+ * + *

注意： item字段使用Object类型，可以存储任意类型的详情数据。

+ * + * @param 数据类型（主要用于类型提示） + * @param item 单条记录数据，可以是实体对象、Map、VO对象等 + * + * @see #responseDetailData(Object) + */ public record DetailItem(T item) { } } diff --git a/spring-boot-service-template-common/src/main/java/com/lanyuanxiaoyao/service/template/common/controller/QueryController.java b/spring-boot-service-template-common/src/main/java/com/lanyuanxiaoyao/service/template/common/controller/QueryController.java index d512721..4b6867f 100644 --- a/spring-boot-service-template-common/src/main/java/com/lanyuanxiaoyao/service/template/common/controller/QueryController.java +++ b/spring-boot-service-template-common/src/main/java/com/lanyuanxiaoyao/service/template/common/controller/QueryController.java @@ -2,56 +2,24 @@ package com.lanyuanxiaoyao.service.template.common.controller; /** * 查询控制器接口，用于定义统一的查询实体详情和列表的接口规范 - * *

- * 前端传入的JSON格式示例: - * 

- * {
- *   "query": {
- *     "equal": {
- *       "status": "ACTIVE"
- *     },
- *     "like": {
- *       "name": "关键字"
- *     }
- *   },
- *   "sort": [
- *     {
- *       "column": "createTime",
- *       "direction": "DESC"
- *     }
- *   ],
- *   "page": {
- *     "index": 0,
- *     "size": 10
- *   }
- * }
- *
+ * 该接口提供了标准的查询功能，支持条件查询、分页查询和详情查询。 + * 所有实现类应当遵循统一的请求响应格式。 *

* - *

- * 支持的查询条件说明: + *

查询条件说明

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

* - * @param 查询结果的实体类型 + * @param 列表查询结果的实体类型 + * @param 详情查询结果的实体类型 */ public interface QueryController { String LIST = "/list"; @@ -59,26 +27,38 @@ public interface QueryController { /** * 获取所有实体列表 + *

+ * 查询所有记录，不带任何过滤条件，返回分页格式的数据。 + * 适用于获取全量数据的场景。 + *

* - * @return GlobalResponse> 返回实体列表 + * @return 返回包含实体列表的响应对象，格式：{status: 0, message: "OK", data: {items: [...], total: total}} * @throws Exception 查询过程中可能抛出的异常 */ GlobalResponse> list() throws Exception; /** * 根据查询条件获取实体列表 + *

+ * 支持复杂的查询条件、排序和分页，返回符合条件的数据。 + * 查询条件包括相等、模糊匹配、范围查询、集合查询等。 + *

* - * @param query 查询条件对象 - * @return GlobalResponse> 返回符合条件的实体列表 + * @param query 查询条件对象，包含过滤条件、排序规则和分页信息 + * @return 返回符合条件的实体列表响应对象，格式：{status: 0, message: "OK", data: {items: [...], total: total}} * @throws Exception 查询过程中可能抛出的异常 */ GlobalResponse> list(Query query) throws Exception; /** * 根据ID获取实体详情 + *

+ * 根据主键ID查询单条记录的详细信息。 + * 适用于详情页面展示或数据编辑的场景。 + *

* - * @param id 实体ID - * @return GlobalResponse 返回实体详情 + * @param id 实体主键ID + * @return 返回实体详情响应对象，格式：{status: 0, message: "OK", data: {item: 详情数据}} * @throws Exception 查询过程中可能抛出的异常 */ GlobalResponse detail(Long id) throws Exception; diff --git a/spring-boot-service-template-common/src/main/java/com/lanyuanxiaoyao/service/template/common/controller/RemoveController.java b/spring-boot-service-template-common/src/main/java/com/lanyuanxiaoyao/service/template/common/controller/RemoveController.java index 3d147b1..93a43a8 100644 --- a/spring-boot-service-template-common/src/main/java/com/lanyuanxiaoyao/service/template/common/controller/RemoveController.java +++ b/spring-boot-service-template-common/src/main/java/com/lanyuanxiaoyao/service/template/common/controller/RemoveController.java @@ -2,12 +2,9 @@ package com.lanyuanxiaoyao.service.template.common.controller; /** * 删除控制器接口，用于定义统一的删除实体对象的接口规范 - * *

- * 前端传入的JSON格式示例: - * 

- * DELETE /remove/1
- *
+ * 该接口提供了标准的删除功能，通过主键ID删除单条记录。 + * 所有实现类应当遵循统一的请求响应格式。 *

*/ public interface RemoveController { @@ -15,9 +12,13 @@ public interface RemoveController { /** * 根据ID删除实体对象 + *

+ * 根据主键ID删除指定的记录，执行成功后返回操作结果。 + * 适用于单条记录删除的场景。 + *

* - * @param id 需要删除的实体ID - * @return GlobalResponse 返回删除结果 + * @param id 需要删除的实体主键ID + * @return 返回删除结果响应对象，格式：{status: 0, message: "OK", data: null} * @throws Exception 删除过程中可能抛出的异常 */ GlobalResponse remove(Long id) throws Exception; diff --git a/spring-boot-service-template-common/src/main/java/com/lanyuanxiaoyao/service/template/common/controller/SaveController.java b/spring-boot-service-template-common/src/main/java/com/lanyuanxiaoyao/service/template/common/controller/SaveController.java index 1897b63..18130e4 100644 --- a/spring-boot-service-template-common/src/main/java/com/lanyuanxiaoyao/service/template/common/controller/SaveController.java +++ b/spring-boot-service-template-common/src/main/java/com/lanyuanxiaoyao/service/template/common/controller/SaveController.java @@ -2,26 +2,25 @@ package com.lanyuanxiaoyao.service.template.common.controller; /** * 保存控制器接口，用于定义统一的保存实体对象的接口规范 - * *

- * 前端传入的JSON格式示例: - * 

- * {
- *   // 实体对象的具体字段
- *   "name": "示例名称",
- *   "description": "示例描述"
- * }
- *
+ * 该接口提供了标准的保存功能，支持新增和更新操作。 + * 所有实现类应当遵循统一的请求响应格式。 *

+ * + * @param 保存操作的实体类型 */ public interface SaveController { String SAVE = "/save"; /** * 保存实体对象 + *

+ * 保存或更新实体对象，根据业务逻辑判断是新增还是更新操作。 + * 返回保存后的实体ID，便于前端获取操作结果。 + *

* - * @param item 需要保存的实体对象 - * @return GlobalResponse 返回保存后的实体ID + * @param item 需要保存的实体对象，包含完整的字段信息 + * @return 返回保存后的实体ID响应对象，格式：{status: 0, message: "OK", data: 实体ID} * @throws Exception 保存过程中可能抛出的异常 */ GlobalResponse save(SAVE_ITEM item) throws Exception; diff --git a/spring-boot-service-template-common/src/main/java/com/lanyuanxiaoyao/service/template/common/helper/ObjectHelper.java b/spring-boot-service-template-common/src/main/java/com/lanyuanxiaoyao/service/template/common/helper/ObjectHelper.java index 322fbf7..a1848fd 100644 --- a/spring-boot-service-template-common/src/main/java/com/lanyuanxiaoyao/service/template/common/helper/ObjectHelper.java +++ b/spring-boot-service-template-common/src/main/java/com/lanyuanxiaoyao/service/template/common/helper/ObjectHelper.java @@ -4,9 +4,20 @@ import java.util.Collection; import java.util.Map; import java.util.Optional; +/** + * 对象工具类，提供常用的对象判断和处理方法 + *

+ * 该类封装了对象空值判断、空值检查、类型判断等常用功能， + * 用于简化代码中的对象处理逻辑。 + *

+ */ public class ObjectHelper { + /** * 判断对象是否为null + *

+ * 简单的null值检查，用于避免空指针异常。 + *

* * @param obj 待检查的对象 * @return 如果对象为null返回true，否则返回false @@ -15,9 +26,11 @@ public class ObjectHelper { return obj == null; } - /** * 判断对象是否不为null + *

+ * isNull方法的反向操作，语义更清晰。 + *

* * @param obj 待判断的对象 * @return 如果对象不为null则返回true，否则返回false @@ -26,82 +39,138 @@ public class ObjectHelper { return !isNull(obj); } - /** * 判断对象是否为空 + *

+ * 支持多种类型的空值判断，包括： + *

    + *
  • null值
    • + *
  • 集合（Collection）
    • + *
  • 映射（Map）
    • + *
  • 字符序列（String、StringBuilder等）
    • + *
  • 各种基本类型数组
    • + *
  • Optional对象
    • + *
+ *

* * @param obj 待判断的对象 * @return 如果对象为null或为空则返回true，否则返回false */ public static boolean isEmpty(Object obj) { - // 首先判断对象是否为null if (isNull(obj)) return true; - // 判断是否为集合类型 - else if (obj instanceof Collection collection) return collection.isEmpty(); - // 判断是否为Map类型 - else if (obj instanceof Map map) return map.isEmpty(); - // 判断是否为字符序列类型 - else if (obj instanceof CharSequence sequence) return sequence.isEmpty(); - // 判断是否为各种基本类型数组 - else if (obj instanceof Object[] array) return array.length == 0; - else if (obj instanceof byte[] array) return array.length == 0; - else if (obj instanceof short[] array) return array.length == 0; - else if (obj instanceof int[] array) return array.length == 0; - else if (obj instanceof long[] array) return array.length == 0; - else if (obj instanceof float[] array) return array.length == 0; - else if (obj instanceof double[] array) return array.length == 0; - else if (obj instanceof char[] array) return array.length == 0; - else if (obj instanceof boolean[] array) return array.length == 0; - // 判断是否为Optional类型 - else if (obj instanceof Optional optional) return optional.isEmpty(); - // 其他情况认为对象不为空 - else return false; + if (obj instanceof Collection collection) return collection.isEmpty(); + if (obj instanceof Map map) return map.isEmpty(); + if (obj instanceof CharSequence sequence) return sequence.isEmpty(); + if (obj instanceof Object[] array) return array.length == 0; + if (obj instanceof byte[] array) return array.length == 0; + if (obj instanceof short[] array) return array.length == 0; + if (obj instanceof int[] array) return array.length == 0; + if (obj instanceof long[] array) return array.length == 0; + if (obj instanceof float[] array) return array.length == 0; + if (obj instanceof double[] array) return array.length == 0; + if (obj instanceof char[] array) return array.length == 0; + if (obj instanceof boolean[] array) return array.length == 0; + if (obj instanceof Optional optional) return optional.isEmpty(); + return false; } - + /** + * 判断对象是否不为空 + *

+ * isEmpty方法的反向操作，语义更清晰。 + *

+ * + * @param obj 待判断的对象 + * @return 如果对象不为空则返回true，否则返回false + */ public static boolean isNotEmpty(Object obj) { return !isEmpty(obj); } + /** + * 如果对象为null则返回默认值 + *

+ * 提供对象的null值保护，避免空指针异常。 + *

+ * + * @param object 待检查的对象 + * @param defaultValue 默认值，当object为null时返回 + * @return 如果object不为null则返回object，否则返回defaultValue + */ public static T defaultIfNull(final T object, final T defaultValue) { return isNull(object) ? defaultValue : object; } /** * 判断给定的类是否可比较 + *

+ * 可比较的类型包括：枚举、字符序列、实现了Comparable接口的类、基本数据类型。 + *

* * @param clazz 待判断的类对象 * @return 如果类是枚举、字符序列、可比较接口的实现类或基本数据类型则返回true，否则返回false */ public static boolean isComparable(Class clazz) { if (isNull(clazz)) return false; - // 判断类是否为可比较类型：枚举、字符序列、可比较接口实现类或基本数据类型 return clazz.isEnum() || CharSequence.class.isAssignableFrom(clazz) || Comparable.class.isAssignableFrom(clazz) || clazz.isPrimitive(); } + /** + * 判断对象是否可比较 + *

+ * 通过对象的类来判断其是否可比较。 + *

+ * + * @param obj 待判断的对象 + * @return 如果对象所属的类可比较则返回true，否则返回false + */ public static boolean isComparable(Object obj) { if (isNull(obj)) return false; return isComparable(obj.getClass()); } + /** + * 判断给定的类是否为集合类型 + * + * @param clazz 待判断的类对象 + * @return 如果类是Collection的子类则返回true，否则返回false + */ public static boolean isCollection(Class clazz) { if (isNull(clazz)) return false; return Collection.class.isAssignableFrom(clazz); } + /** + * 判断对象是否为集合类型 + * + * @param obj 待判断的对象 + * @return 如果对象是集合类型则返回true，否则返回false + */ public static boolean isCollection(Object obj) { if (isNull(obj)) return false; return isCollection(obj.getClass()); } + /** + * 判断给定的类是否为字符串类型 + * + * @param clazz 待判断的类对象 + * @return 如果类是String类型则返回true，否则返回false + */ public static boolean isString(Class clazz) { if (isNull(clazz)) return false; return String.class.isAssignableFrom(clazz); } + /** + * 判断对象是否为字符串类型 + * + * @param obj 待判断的对象 + * @return 如果对象是字符串类型则返回true，否则返回false + */ public static boolean isString(Object obj) { if (isNull(obj)) return false; return isString(obj.getClass()); diff --git a/spring-boot-service-template-common/src/main/java/com/lanyuanxiaoyao/service/template/common/service/Page.java b/spring-boot-service-template-common/src/main/java/com/lanyuanxiaoyao/service/template/common/service/Page.java index 466a59a..d624929 100644 --- a/spring-boot-service-template-common/src/main/java/com/lanyuanxiaoyao/service/template/common/service/Page.java +++ b/spring-boot-service-template-common/src/main/java/com/lanyuanxiaoyao/service/template/common/service/Page.java @@ -3,7 +3,29 @@ package com.lanyuanxiaoyao.service.template.common.service; import java.util.stream.Stream; /** - * 分页 + * 分页数据封装类 + *

+ * 用于封装分页查询的结果，包含数据流和总记录数。 + * 适用于需要流式处理大量数据的场景，同时提供总数用于分页计算。 + *

+ * + *

使用场景

+ *
    + *
  • 数据库分页查询结果封装
    • + *
  • 大数据量流式处理
    • + *
  • 分页控件的数据源
    • + *
+ * + *

特点

+ *
    + *
  • 使用Java Record实现，不可变，线程安全
    • + *
  • 支持流式数据处理，内存效率高
    • + *
  • 包含总记录数，便于分页计算
    • + *
+ * + * @param 实体类型 + * @param items 数据流，包含当前页的所有记录 + * @param total 总记录数，用于计算总页数和显示分页信息 */ public record Page(Stream items, long total) { } 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 index c31226f..efda3d4 100644 --- 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 @@ -6,30 +6,45 @@ import java.util.Set; /** * 查询服务接口，用于定义统一的查询实体详情和列表的服务规范 + *

+ * 该接口提供了标准的查询功能，支持详情查询、列表查询、分页查询和统计查询。 + * 所有实现类应当遵循统一的查询逻辑和异常处理规范。 + *

* * @param 实体类型 */ public interface QueryService { + /** * 根据ID获取实体详情 + *

+ * 查询单条记录的详细信息，如果记录不存在返回null。 + *

* - * @param id 实体ID - * @return 实体详情 + * @param id 实体主键ID + * @return 实体详情，如果不存在则返回null * @throws Exception 查询过程中可能抛出的异常 */ ENTITY detail(Long id) throws Exception; /** * 根据ID获取实体详情，如果不存在则抛出异常 + *

+ * 查询单条记录的详细信息，如果记录不存在则抛出异常。 + * 适用于需要确保记录存在的场景。 + *

* - * @param id 实体ID + * @param id 实体主键ID * @return 实体详情 - * @throws Exception 查询过程中可能抛出的异常 + * @throws Exception 当记录不存在或查询失败时抛出异常 */ ENTITY detailOrThrow(Long id) throws Exception; /** * 获取实体总数 + *

+ * 统计所有记录的数量，不带任何过滤条件。 + *

* * @return 实体总数 * @throws Exception 查询过程中可能抛出的异常 @@ -38,6 +53,10 @@ public interface QueryService { /** * 获取所有实体列表 + *

+ * 查询所有记录，不带任何过滤条件，返回完整列表。 + * 适用于数据量较小或需要全量数据的场景。 + *

* * @return 实体列表 * @throws Exception 查询过程中可能抛出的异常 @@ -46,18 +65,26 @@ public interface QueryService { /** * 根据ID集合获取实体列表 + *

+ * 批量查询指定ID的记录，返回对应的实体列表。 + * 适用于需要批量获取特定记录的场景。 + *

* * @param ids 实体ID集合 - * @return 实体列表 + * @return 实体列表，包含集合中ID对应的记录 * @throws Exception 查询过程中可能抛出的异常 */ List list(Set ids) throws Exception; /** * 根据查询条件获取分页实体列表 + *

+ * 支持复杂的查询条件、排序和分页，返回符合条件的数据。 + * 这是最完整的查询方法，适用于大多数业务场景。 + *

* - * @param query 查询条件对象 - * @return 分页实体列表 + * @param query 查询条件对象，包含过滤条件、排序规则和分页信息 + * @return 分页实体列表，包含数据流和总记录数 * @throws Exception 查询过程中可能抛出的异常 */ Page list(Query query) throws Exception; 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 index 66b38be..a84f59b 100644 --- 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 @@ -2,20 +2,33 @@ package com.lanyuanxiaoyao.service.template.common.service; /** * 删除服务接口，用于定义统一的删除实体对象的服务规范 + *

+ * 该接口提供了标准的删除功能，支持单条记录删除和批量删除。 + * 所有实现类应当遵循统一的删除逻辑和异常处理规范。 + *

* * @param 实体类型 */ public interface RemoveService { + /** * 根据ID删除实体对象 + *

+ * 删除指定ID的单条记录，执行成功后无返回值。 + * 适用于单条记录删除的场景。 + *

* - * @param id 需要删除的实体ID + * @param id 需要删除的实体主键ID * @throws Exception 删除过程中可能抛出的异常 */ void remove(Long id) throws Exception; /** * 批量删除实体对象 + *

+ * 删除指定ID集合的多条记录，执行成功后无返回值。 + * 适用于批量删除的场景，提高删除效率。 + *

* * @param ids 需要删除的实体ID集合 * @throws Exception 删除过程中可能抛出的异常 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 index 6ea6437..b9a0741 100644 --- 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 @@ -2,21 +2,34 @@ package com.lanyuanxiaoyao.service.template.common.service; /** * 保存服务接口，用于定义统一的保存实体对象的服务规范 + *

+ * 该接口提供了标准的保存功能，支持单条记录保存和批量保存。 + * 所有实现类应当遵循统一的保存逻辑和异常处理规范。 + *

* * @param 实体类型 */ public interface SaveService { + /** * 保存实体对象 + *

+ * 保存或更新单条实体记录，根据业务逻辑判断是新增还是更新操作。 + * 返回保存后的实体ID，便于后续操作。 + *

* - * @param entity 需要保存的实体对象 - * @return 保存后的实体ID + * @param entity 需要保存的实体对象，包含完整的字段信息 + * @return 保存后的实体主键ID * @throws Exception 保存过程中可能抛出的异常 */ Long save(ENTITY entity) throws Exception; /** * 批量保存实体对象 + *

+ * 批量保存或更新多条实体记录，提高数据处理效率。 + * 适用于批量数据导入或同步的场景。 + *

* * @param entities 需要保存的实体对象集合 * @throws Exception 保存过程中可能抛出的异常 diff --git 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 index 2763700..88e45c5 100644 --- 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函数来完成实体类与传输对象之间的转换。 *

* - *

- * 前端传入的JSON格式示例: - * 

- * // 保存实体
- * 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
- *
- *

- * - *

- * 支持的查询条件说明: + *

设计特点

*
    - *
  • nullEqual: 指定字段值为null的条件列表
    • - *
  • notNullEqual: 指定字段值不为null的条件列表
    • - *
  • empty: 指定字段值为空的条件列表（如空字符串、空集合等）
    • - *
  • notEmpty: 指定字段值不为空的条件列表
    • - *
  • equal: 指定字段值相等的条件映射（字段名 -> 值）
    • - *
  • notEqual: 指定字段值不相等的条件映射（字段名 -> 值）
    • - *
  • like: 指定字段模糊匹配的条件映射（字段名 -> 匹配值）
    • - *
  • notLike: 指定字段不模糊匹配的条件映射（字段名 -> 匹配值）
    • - *
  • great: 指定字段大于条件的映射（字段名 -> 值）
    • - *
  • less: 指定字段小于条件的映射（字段名 -> 值）
    • - *
  • greatEqual: 指定字段大于等于条件的映射（字段名 -> 值）
    • - *
  • lessEqual: 指定字段小于等于条件的映射（字段名 -> 值）
    • - *
  • in: 指定字段值在指定范围内的条件映射（字段名 -> 值列表）
    • - *
  • notIn: 指定字段值不在指定范围内的条件映射（字段名 -> 值列表）
    • - *
  • between: 指定字段值在指定区间内的条件映射（字段名 -> 区间范围）
    • - *
  • notBetween: 指定字段值不在指定区间内的条件映射（字段名 -> 区间范围）
    • + *
  • 泛型设计，支持任意实体类型和数据转换
    • + *
  • 统一的异常处理和事务管理
    • + *
  • 支持条件查询、分页查询和详情查询
    • + *
  • 提供抽象的Mapper方法，便于子类实现数据转换逻辑
    • + *
+ * + *

使用说明

+ *

子类需要实现以下抽象方法：

+ *
    + *
  • saveItemMapper(): 保存项到实体的转换函数
    • + *
  • listItemMapper(): 实体到列表项的转换函数
    • + *
  • detailItemMapper(): 实体到详情项的转换函数
    • *
- *

* * @param 实体类型，必须继承SimpleEntity * @param 保存项类型 @@ -108,9 +57,13 @@ public abstract class SimpleControllerSupport + * 将保存项转换为实体对象后保存，返回保存后的实体ID。 + * 支持新增和更新操作，通过事务保证数据一致性。 + *

* * @param item 需要保存的项 - * @return GlobalResponse 返回保存后的实体ID + * @return 返回保存后的实体ID响应对象，格式：{status: 0, message: "OK", data: 实体ID} * @throws Exception 保存过程中可能抛出的异常 */ @Transactional(rollbackFor = Throwable.class) @@ -123,8 +76,12 @@ public abstract class SimpleControllerSupport + * 查询所有记录，不带任何过滤条件，返回分页格式的数据。 + * 将实体对象转换为列表项对象后返回。 + *

* - * @return GlobalCrudResponse 返回实体列表 + * @return 返回实体列表响应对象，格式：{status: 0, message: "OK", data: {items: [...], total: total}} * @throws Exception 查询过程中可能抛出的异常 */ @Transactional(readOnly = true) @@ -150,9 +107,13 @@ public abstract class SimpleControllerSupport + * 支持复杂的查询条件、排序和分页，返回符合条件的数据。 + * 将实体对象转换为列表项对象后返回。 + *

* - * @param query 查询条件对象 - * @return GlobalCrudResponse 返回符合条件的实体列表 + * @param query 查询条件对象，包含过滤条件、排序规则和分页信息 + * @return 返回符合条件的实体列表响应对象，格式：{status: 0, message: "OK", data: {items: [...], total: total}} * @throws Exception 查询过程中可能抛出的异常 */ @Transactional(readOnly = true) @@ -180,9 +141,13 @@ public abstract class SimpleControllerSupport + * 根据主键ID查询单条记录的详细信息，转换为详情项对象后返回。 + * 如果记录不存在则抛出异常。 + *

* - * @param id 实体ID - * @return GlobalResponse 返回实体详情 + * @param id 实体主键ID + * @return 返回实体详情响应对象，格式：{status: 0, message: "OK", data: 详情数据} * @throws Exception 查询过程中可能抛出的异常 */ @Transactional(readOnly = true) @@ -195,9 +160,13 @@ public abstract class SimpleControllerSupport + * 根据主键ID删除指定的记录，执行成功后返回成功响应。 + * 通过事务保证删除操作的一致性。 + *

* - * @param id 需要删除的实体ID - * @return GlobalResponse 返回删除结果 + * @param id 需要删除的实体主键ID + * @return 返回删除结果响应对象，格式：{status: 0, message: "OK", data: null} * @throws Exception 删除过程中可能抛出的异常 */ @Transactional(rollbackFor = Throwable.class) @@ -210,6 +179,9 @@ public abstract class SimpleControllerSupport + * 子类需要实现此方法，定义保存项到实体的转换逻辑。 + *

* * @return Function 保存项到实体的转换函数 */ @@ -217,6 +189,9 @@ public abstract class SimpleControllerSupport + * 子类需要实现此方法，定义实体到列表项的转换逻辑。 + *

* * @return Function 实体到列表项的转换函数 */ @@ -224,6 +199,9 @@ public abstract class SimpleControllerSupport + * 子类需要实现此方法，定义实体到详情项的转换逻辑。 + *

* * @return Function 实体到详情项的转换函数 */ diff --git 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 index ab5299a..20cf6d1 100644 --- 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接口，提供实体的增删改查等基本操作。 * 通过继承此类，可以快速实现常见的业务逻辑功能，包括： *
    - *
  • 实体的保存和更新
    • + *
  • 实体的保存和更新（支持部分字段更新）
    • *
  • 实体的条件查询和分页查询
    • *
  • 实体的详情查询（多种方式）
    • - *
  • 实体的删除操作
    • + *
  • 实体的删除操作（支持批量删除）
    • + *
  • 动态查询条件构建
    • *
*

* - *

- * 查询条件说明: + *

设计特点

*
    - *
  • nullEqual: 指定字段值为null的条件列表
    • - *
  • notNullEqual: 指定字段值不为null的条件列表
    • - *
  • empty: 指定字段值为空的条件列表（如空字符串、空集合等）
    • - *
  • notEmpty: 指定字段值不为空的条件列表
    • - *
  • equal: 指定字段值相等的条件映射（字段名 -> 值）
    • - *
  • notEqual: 指定字段值不相等的条件映射（字段名 -> 值）
    • - *
  • contain: 指定字段包含指定字符串的条件映射（字段名 -> 包含值）
    • - *
  • notContain: 指定字段不包含指定字符串的条件映射（字段名 -> 不包含值）
    • - *
  • startWith: 指定字段以指定字符串开头的条件映射（字段名 -> 开头值）
    • - *
  • notStartWith: 指定字段不以指定字符串开头的条件映射（字段名 -> 不开头值）
    • - *
  • endWith: 指定字段以指定字符串结尾的条件映射（字段名 -> 结尾值）
    • - *
  • notEndWith: 指定字段不以指定字符串结尾的条件映射（字段名 -> 不结尾值）
    • - *
  • great: 指定字段大于条件的映射（字段名 -> 值）
    • - *
  • less: 指定字段小于条件的映射（字段名 -> 值）
    • - *
  • greatEqual: 指定字段大于等于条件的映射（字段名 -> 值）
    • - *
  • lessEqual: 指定字段小于等于条件的映射（字段名 -> 值）
    • - *
  • in: 指定字段值在指定范围内的条件映射（字段名 -> 值列表）
    • - *
  • notIn: 指定字段值不在指定范围内的条件映射（字段名 -> 值列表）
    • - *
  • between: 指定字段值在指定区间内的条件映射（字段名 -> 区间范围）
    • - *
  • notBetween: 指定字段值不在指定区间内的条件映射（字段名 -> 区间范围）
    • + *
  • 泛型设计，支持任意实体类型
    • + *
  • 事务管理，确保数据一致性
    • + *
  • 动态查询条件，支持复杂的业务查询
    • + *
  • 部分更新，只更新非空字段
    • + *
  • 可扩展的查询条件构建
    • *
- *

* - *

- * 前端传入的JSON格式示例: - * 

- * {
- *   "query": {
- *     "equal": {
- *       "status": "ACTIVE"
- *     },
- *     "like": {
- *       "name": "关键字"
- *     }
- *   },
- *   "sort": [
- *     {
- *       "column": "createdTime",
- *       "direction": "DESC"
- *     }
- *   ],
- *   "page": {
- *     "index": 1,
- *     "size": 10
- *   }
- * }
- *
- *

+ *

使用说明

+ *

子类可以重写以下方法：

+ *
    + *
  • listPredicate(): 添加自定义的查询条件
    • + *
* * @param 实体类型，必须继承SimpleEntity */ @@ -116,7 +80,7 @@ public abstract class SimpleServiceSupport implemen *

* * @param entity 需要保存的实体对象 - * @return Long 返回保存后的实体ID + * @return 返回保存后的实体ID */ @Transactional(rollbackOn = Throwable.class) @Override @@ -143,10 +107,10 @@ public abstract class SimpleServiceSupport implemen /** * 统计符合条件的实体数量 *

- * 根据[listPredicate](file:///Users/lanyuanxiaoyao/Project/IdeaProjects/spring-boot-service-template/src/main/java/com/lanyuanxiaoyao/service/template/service/SimpleServiceSupport.java#L261-L263)方法构建的条件统计实体数量。 + * 根据listPredicate方法构建的条件统计实体数量。 *

* - * @return Long 返回符合条件的实体数量 + * @return 返回符合条件的实体数量 */ @Override public Long count() { @@ -156,10 +120,10 @@ public abstract class SimpleServiceSupport implemen /** * 获取所有符合条件的实体列表 *

- * 根据[listPredicate](file:///Users/lanyuanxiaoyao/Project/IdeaProjects/spring-boot-service-template/src/main/java/com/lanyuanxiaoyao/service/template/service/SimpleServiceSupport.java#L261-L263)方法构建的条件查询所有实体。 + * 根据listPredicate方法构建的条件查询所有实体。 *

* - * @return List 返回符合条件的实体列表 + * @return 返回符合条件的实体列表 */ @Override public List list() { @@ -169,11 +133,11 @@ public abstract class SimpleServiceSupport implemen /** * 根据ID集合获取实体列表 *

- * 根据提供的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方法构建的条件。 *

* * @param ids ID集合 - * @return List 返回ID集合对应的实体列表 + * @return 返回ID集合对应的实体列表 */ @Override public List list(Set ids) { @@ -194,14 +158,14 @@ public abstract class SimpleServiceSupport implemen /** * 解析字段路径 *

- * 支持多级字段路径解析，使用"/"分隔多级字段。 - * 例如: "user/name" 表示实体的user属性的name字段。 + * 支持多级字段路径解析，使用"."分隔多级字段。 + * 例如: "user.name" 表示实体的user属性的name字段。 *

* * @param root JPA Criteria查询根节点 * @param column 字段路径字符串 * @param 字段类型 - * @return Path 返回字段路径对象 + * @return 返回字段路径对象 * @throws IllegalArgumentException 当字段路径为空时抛出 */ private Path column(Root root, String column) { @@ -220,13 +184,14 @@ public abstract class SimpleServiceSupport implemen * 处理字段值 *

* 对于枚举类型字段，将字符串值转换为对应的枚举值。 + * 对于LocalDateTime类型字段，将字符串转换为时间对象。 * 其他类型直接返回原值。 *

* * @param column 字段路径 * @param value 字段值 * @param 字段类型 - * @return Object 处理后的字段值 + * @return 处理后的字段值 * @throws IllegalArgumentException 当枚举类型字段的值不是字符串时抛出 */ @SuppressWarnings({"unchecked", "rawtypes"}) @@ -259,7 +224,7 @@ public abstract class SimpleServiceSupport implemen * @param root JPA Criteria查询根节点 * @param query JPA Criteria查询对象 * @param builder JPA Criteria构建器 - * @return List 返回构建的谓词列表 + * @return 返回构建的谓词列表 */ @SuppressWarnings("unchecked") protected Predicate queryPredicates(Query.Queryable queryable, Root root, CriteriaQuery query, CriteriaBuilder builder) { @@ -421,6 +386,7 @@ public abstract class SimpleServiceSupport implemen * 检查字段类型是否可比较 * * @param path 字段路径 + * @param value 比较值 * @param column 字段名称 * @throws NotComparableException 当字段类型不可比较时抛出 */ @@ -433,6 +399,7 @@ public abstract class SimpleServiceSupport implemen /** * 检查区间值是否可比较 * + * @param path 字段路径 * @param value 区间对象 * @param column 字段名称 * @throws NotComparableException 当区间值不可比较时抛出 @@ -472,6 +439,7 @@ public abstract class SimpleServiceSupport implemen * 检查字段类型是否为字符串 * * @param path 字段路径 + * @param value 比较值 * @param column 字段名称 * @throws NotStringException 当字段类型不是字符串时抛出 */ @@ -485,13 +453,13 @@ public abstract class SimpleServiceSupport implemen * 构建列表查询条件 *

* 子类可以重写此方法以添加特定的查询条件。 - * 默认返回空列表，表示不添加额外条件。 + * 默认返回null，表示不添加额外条件。 *

* * @param root JPA Criteria查询根节点 * @param query JPA Criteria查询对象 * @param builder JPA Criteria构建器 - * @return List 返回查询条件谓词列表 + * @return 返回查询条件谓词 */ protected Predicate listPredicate(Root root, CriteriaQuery query, CriteriaBuilder builder) { return null; @@ -505,7 +473,7 @@ public abstract class SimpleServiceSupport implemen *

* * @param listQuery 查询条件对象 - * @return Page 返回分页查询结果 + * @return 返回分页查询结果 */ @Override public Page list(Query listQuery) { @@ -544,7 +512,7 @@ public abstract class SimpleServiceSupport implemen *

* * @param id 实体ID - * @return Optional 返回实体详情的Optional包装 + * @return 返回实体详情的Optional包装 */ private Optional detailOptional(Long id) { if (ObjectHelper.isNull(id)) { @@ -568,7 +536,7 @@ public abstract class SimpleServiceSupport implemen *

* * @param id 实体ID - * @return ENTITY 返回实体详情，不存在时返回null + * @return 返回实体详情，不存在时返回null */ @Named("detail") @Override @@ -583,7 +551,7 @@ public abstract class SimpleServiceSupport implemen *

* * @param id 实体ID - * @return ENTITY 返回实体详情 + * @return 返回实体详情 * @throws IdNotFoundException 当实体不存在时抛出 */ @Named("detailOrThrow") @@ -599,7 +567,7 @@ public abstract class SimpleServiceSupport implemen * 如果ID为空则不执行任何操作。 *

* - * @param id 实体ID + * @param id 实体主键ID */ @Transactional(rollbackOn = Throwable.class) @Override @@ -617,7 +585,7 @@ public abstract class SimpleServiceSupport implemen * 如果ID集合为空则不执行任何操作。 *

* - * @param ids 实体ID集合 + * @param ids 实体主键ID集合 */ @Transactional(rollbackOn = Throwable.class) @Override