From a9156e07f4e68818cf8129b84115a59347db4e51 Mon Sep 17 00:00:00 2001 From: Timi Date: Sun, 4 Jan 2026 17:27:36 +0800 Subject: [PATCH] fix javadoc warning --- .../java/com/imyeyu/spring/TimiSpring.java | 67 +++++++++ .../spring/annotation/AOPLogInterceptor.java | 7 + .../CaptchaValidAbstractInterceptor.java | 14 ++ .../RequestRateLimitAbstractInterceptor.java | 12 ++ .../RequestSingleParamResolver.java | 12 ++ .../RequiredTokenAbstractInterceptor.java | 6 + .../spring/annotation/table/Column.java | 5 + .../spring/annotation/table/DeleteColumn.java | 12 +- .../imyeyu/spring/annotation/table/Table.java | 5 + .../com/imyeyu/spring/bean/CaptchaData.java | 37 +++++ .../com/imyeyu/spring/bean/Multilingual.java | 12 ++ .../java/com/imyeyu/spring/bean/Page.java | 59 ++++++++ .../com/imyeyu/spring/bean/PageResult.java | 7 + .../imyeyu/spring/bean/RedisConfigParams.java | 6 + .../com/imyeyu/spring/bean/RequestRange.java | 38 ++++- .../spring/config/AbstractRedisConfig.java | 6 + .../com/imyeyu/spring/entity/BaseEntity.java | 6 + .../java/com/imyeyu/spring/entity/Entity.java | 6 + .../com/imyeyu/spring/entity/IDEntity.java | 1 + .../com/imyeyu/spring/entity/UUIDEntity.java | 6 + .../imyeyu/spring/handler/GsonHandler.java | 6 + .../com/imyeyu/spring/mapper/BaseMapper.java | 35 +++++ .../spring/service/AbstractEntityService.java | 12 +- .../spring/service/DeletableService.java | 1 + .../spring/service/DestroyableService.java | 1 + .../imyeyu/spring/util/AbstractValidator.java | 10 +- .../spring/util/GlobalExceptionHandler.java | 12 +- .../spring/util/GlobalReturnHandler.java | 17 +++ .../java/com/imyeyu/spring/util/Redis.java | 19 ++- .../imyeyu/spring/util/RedisSerializers.java | 14 +- .../com/imyeyu/spring/util/SQLProvider.java | 139 ++++++++++++++++++ .../util/YamlPropertySourceFactory.java | 8 +- 32 files changed, 587 insertions(+), 11 deletions(-) diff --git a/src/main/java/com/imyeyu/spring/TimiSpring.java b/src/main/java/com/imyeyu/spring/TimiSpring.java index 2c83f2e..d170fe3 100644 --- a/src/main/java/com/imyeyu/spring/TimiSpring.java +++ b/src/main/java/com/imyeyu/spring/TimiSpring.java @@ -42,6 +42,12 @@ public class TimiSpring { private static final Logger log = LoggerFactory.getLogger(TimiSpring.class); private static final Gson GSON = new Gson(); + /** + * 工具类禁止实例化 + */ + private TimiSpring() { + } + /** * 回调数据 * @@ -102,24 +108,50 @@ public class TimiSpring { return getServletRequestAttributes().getRequest(); } + /** + * 获取请求域名 + * + * @return 请求域名 + */ public static String getDomain() { return getRequest().getServerName(); } + /** + * 获取完整域名（含协议与端口） + * + * @return 完整域名 + */ public static String getFullDomain() { HttpServletRequest req = getRequest(); String port = req.getServerPort() == 80 || req.getServerPort() == 443 ? "" : ":" + req.getServerPort(); return "%s://%s%s".formatted(req.getScheme(), getDomain(), port); } + /** + * 获取请求 URL + * + * @return 请求 URL + */ public static String getURL() { return getRequest().getRequestURL().toString(); } + /** + * 获取请求 URI + * + * @return 请求 URI + */ public static String getURI() { return getRequest().getRequestURI(); } + /** + * 从 URI 指定标记开始截取 + * + * @param flag 标记 + * @return 截取后的 URI + */ public static String cutURIStartAt(String flag) { int indexOf = getURI().indexOf(flag); TimiException.requiredTrue(-1 < indexOf, "not found flag: %s".formatted(flag)); @@ -315,14 +347,31 @@ public class TimiSpring { return getRequest().getParameterValues(key); } + /** + * 添加 Cookie + * + * @param cookie Cookie + */ public static void addCookie(Cookie cookie) { getResponse().addCookie(cookie); } + /** + * 添加 Cookie + * + * @param key 键 + * @param value 值 + */ public static void addCookie(String key, String value) { addCookie(new Cookie(key, value)); } + /** + * 获取 Cookie + * + * @param key 键 + * @return Cookie + */ public static Cookie getCookie(String key) { Cookie[] cookies = getRequest().getCookies(); if (cookies == null) { @@ -345,11 +394,17 @@ public class TimiSpring { return TimiJava.firstNotEmpty(getHeader("Token"), getHeader("token"), getRequestArg("token"), getRequestArg("Token")); } + /** + * 获取原始语言头 + * + * @return 语言头 + */ public static String getLanguageRaw() { return getHeader("Accept-Language"); } /** + * 获取客户端地区语言 * * @return 客户端地区语言 */ @@ -399,10 +454,22 @@ public class TimiSpring { return "0:0:0:0:0:0:0:1".equals(ip) ? "127.0.0.1" : ip; } + /** + * 是否本地 IP + * + * @return true 为本地 IP + */ public static boolean isLocalIP() { return getRequestIP().startsWith("127"); } + /** + * 解析 Range 请求范围 + * + * @param fileLength 文件长度 + * @return 请求范围 + * @throws IOException IO 异常 + */ public static RequestRange requestRange(long fileLength) throws IOException { HttpServletResponse resp = getResponse(); diff --git a/src/main/java/com/imyeyu/spring/annotation/AOPLogInterceptor.java b/src/main/java/com/imyeyu/spring/annotation/AOPLogInterceptor.java index eb0f7d4..57cbe9c 100644 --- a/src/main/java/com/imyeyu/spring/annotation/AOPLogInterceptor.java +++ b/src/main/java/com/imyeyu/spring/annotation/AOPLogInterceptor.java @@ -26,10 +26,17 @@ import org.springframework.stereotype.Component; @Component public class AOPLogInterceptor { + /** 全局请求追踪 ID Key */ public static final String REQUEST_ID = "TIMI_SPRING_REQUEST_ID"; private static final Logger log = LoggerFactory.getLogger(AOPLogInterceptor.class); + /** + * 创建 AOP 日志拦截器 + */ + public AOPLogInterceptor() { + } + /** 注入注解 */ @Pointcut("@annotation(annotation.com.imyeyu.spring.AOPLog)") public void logPointCut() { diff --git a/src/main/java/com/imyeyu/spring/annotation/CaptchaValidAbstractInterceptor.java b/src/main/java/com/imyeyu/spring/annotation/CaptchaValidAbstractInterceptor.java index 0e821ee..84849cf 100644 --- a/src/main/java/com/imyeyu/spring/annotation/CaptchaValidAbstractInterceptor.java +++ b/src/main/java/com/imyeyu/spring/annotation/CaptchaValidAbstractInterceptor.java @@ -18,6 +18,12 @@ public abstract class CaptchaValidAbstractInterceptor { private boolean enable = true; + /** + * 创建验证码校验拦截器 + */ + protected CaptchaValidAbstractInterceptor() { + } + /** 注入注解 */ @Pointcut("@annotation(com.imyeyu.spring.annotation.CaptchaValid)") public void captchaPointCut() { @@ -45,12 +51,20 @@ public abstract class CaptchaValidAbstractInterceptor { } } + /** + * 校验验证码 + * + * @param captchaId 验证码 ID + * @param captcha 验证码 + */ protected abstract void verify(String captchaId, String captcha); + /** 启用校验 */ public void enable() { enable = true; } + /** 禁用校验 */ public void disable() { enable = false; } diff --git a/src/main/java/com/imyeyu/spring/annotation/RequestRateLimitAbstractInterceptor.java b/src/main/java/com/imyeyu/spring/annotation/RequestRateLimitAbstractInterceptor.java index 9fa57e0..7e7493c 100644 --- a/src/main/java/com/imyeyu/spring/annotation/RequestRateLimitAbstractInterceptor.java +++ b/src/main/java/com/imyeyu/spring/annotation/RequestRateLimitAbstractInterceptor.java @@ -14,6 +14,18 @@ import org.springframework.web.servlet.HandlerInterceptor; */ public abstract class RequestRateLimitAbstractInterceptor implements HandlerInterceptor { + /** + * 创建访问频率限制拦截器 + */ + protected RequestRateLimitAbstractInterceptor() { + } + + /** + * 构建接口标识 + * + * @param handlerMethod 方法信息 + * @return 接口标识 + */ protected String buildId(HandlerMethod handlerMethod) { return handlerMethod.getMethod().getDeclaringClass().getSimpleName() + "." + handlerMethod.getMethod().getName(); } diff --git a/src/main/java/com/imyeyu/spring/annotation/RequestSingleParamResolver.java b/src/main/java/com/imyeyu/spring/annotation/RequestSingleParamResolver.java index f9db3df..9adb719 100644 --- a/src/main/java/com/imyeyu/spring/annotation/RequestSingleParamResolver.java +++ b/src/main/java/com/imyeyu/spring/annotation/RequestSingleParamResolver.java @@ -15,9 +15,21 @@ import org.springframework.web.context.request.NativeWebRequest; import org.springframework.web.method.support.HandlerMethodArgumentResolver; import org.springframework.web.method.support.ModelAndViewContainer; +/** + * 单参数请求解析器 + * + * @author 夜雨 + * @since 2025-10-13 16:29 + */ @Component public class RequestSingleParamResolver implements HandlerMethodArgumentResolver { + /** + * 创建单参数解析器 + */ + public RequestSingleParamResolver() { + } + @Override public boolean supportsParameter(MethodParameter parameter) { return parameter.hasParameterAnnotation(RequestSingleParam.class); diff --git a/src/main/java/com/imyeyu/spring/annotation/RequiredTokenAbstractInterceptor.java b/src/main/java/com/imyeyu/spring/annotation/RequiredTokenAbstractInterceptor.java index 8c56b82..03e4238 100644 --- a/src/main/java/com/imyeyu/spring/annotation/RequiredTokenAbstractInterceptor.java +++ b/src/main/java/com/imyeyu/spring/annotation/RequiredTokenAbstractInterceptor.java @@ -11,6 +11,7 @@ import java.lang.annotation.Annotation; /** * 抽象验证令牌 * + * @param 注解类型 * @author 夜雨 * @version 2021-08-16 18:07 */ @@ -18,6 +19,11 @@ public abstract class RequiredTokenAbstractInterceptor imp private final Class annotation; + /** + * 创建 Token 验证拦截器 + * + * @param annotation 注解类型 + */ public RequiredTokenAbstractInterceptor(Class annotation) { this.annotation = annotation; } diff --git a/src/main/java/com/imyeyu/spring/annotation/table/Column.java b/src/main/java/com/imyeyu/spring/annotation/table/Column.java index 49ddd28..999e6e5 100644 --- a/src/main/java/com/imyeyu/spring/annotation/table/Column.java +++ b/src/main/java/com/imyeyu/spring/annotation/table/Column.java @@ -17,5 +17,10 @@ import java.lang.annotation.Target; @Target(ElementType.FIELD) public @interface Column { + /** + * 指定列名 + * + * @return 列名 + */ String value(); } diff --git a/src/main/java/com/imyeyu/spring/annotation/table/DeleteColumn.java b/src/main/java/com/imyeyu/spring/annotation/table/DeleteColumn.java index fb026bd..b100ed9 100644 --- a/src/main/java/com/imyeyu/spring/annotation/table/DeleteColumn.java +++ b/src/main/java/com/imyeyu/spring/annotation/table/DeleteColumn.java @@ -6,6 +6,8 @@ import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; /** + * 标记逻辑删除字段并指定存储类型 + * * @author 夜雨 * @since 2025-12-01 10:56 */ @@ -13,20 +15,28 @@ import java.lang.annotation.Target; @Target(ElementType.FIELD) public @interface DeleteColumn { + /** + * 逻辑删除的存储类型 + * + * @return 存储类型 + */ Type value() default Type.UNIX; /** - * + * 逻辑删除的时间类型 * * @author 夜雨 * @since 2025-12-01 10:57 */ enum Type { + /** 毫秒时间戳 */ UNIX, + /** 日期 */ DATE, + /** 日期时间 */ DATE_TIME } } diff --git a/src/main/java/com/imyeyu/spring/annotation/table/Table.java b/src/main/java/com/imyeyu/spring/annotation/table/Table.java index 33c8037..7bcb606 100644 --- a/src/main/java/com/imyeyu/spring/annotation/table/Table.java +++ b/src/main/java/com/imyeyu/spring/annotation/table/Table.java @@ -17,5 +17,10 @@ import java.lang.annotation.Target; @Target(ElementType.TYPE) public @interface Table { + /** + * 指定表名 + * + * @return 表名 + */ String value(); } diff --git a/src/main/java/com/imyeyu/spring/bean/CaptchaData.java b/src/main/java/com/imyeyu/spring/bean/CaptchaData.java index db7f732..77e2aaf 100644 --- a/src/main/java/com/imyeyu/spring/bean/CaptchaData.java +++ b/src/main/java/com/imyeyu/spring/bean/CaptchaData.java @@ -5,6 +5,7 @@ import jakarta.validation.constraints.NotBlank; /** * 含验证码数据实体 * + * @param 数据体类型 * @author 夜雨 * @version 2021-03-01 17:10 */ @@ -21,26 +22,62 @@ public class CaptchaData { /** 数据体 */ protected T data; + /** + * 创建验证码数据实体 + */ + public CaptchaData() { + } + + /** + * 获取验证码 ID + * + * @return 验证码 ID + */ public String getCaptchaId() { return captchaId; } + /** + * 设置验证码 ID + * + * @param captchaId 验证码 ID + */ public void setCaptchaId(String captchaId) { this.captchaId = captchaId; } + /** + * 获取验证码 + * + * @return 验证码 + */ public String getCaptcha() { return captcha; } + /** + * 设置验证码 + * + * @param captcha 验证码 + */ public void setCaptcha(String captcha) { this.captcha = captcha; } + /** + * 获取数据体 + * + * @return 数据体 + */ public T getData() { return data; } + /** + * 设置数据体 + * + * @param data 数据体 + */ public void setData(T data) { this.data = data; } diff --git a/src/main/java/com/imyeyu/spring/bean/Multilingual.java b/src/main/java/com/imyeyu/spring/bean/Multilingual.java index 3840ef9..8af1833 100644 --- a/src/main/java/com/imyeyu/spring/bean/Multilingual.java +++ b/src/main/java/com/imyeyu/spring/bean/Multilingual.java @@ -10,21 +10,33 @@ import com.imyeyu.spring.entity.IDEntity; import com.imyeyu.spring.entity.Updatable; /** + * 多语言实体基类 + * * @author 夜雨 * @since 2025-10-17 15:21 */ public class Multilingual extends Language implements IDEntity, Creatable, Updatable, Deletable { + /** 唯一标识 */ @Id @AutoUUID protected String id; + /** 创建时间 */ protected Long createdAt; + /** 更新时间 */ protected Long updatedAt; + /** 删除时间 */ protected Long deletedAt; + /** + * 创建多语言实体 + */ + public Multilingual() { + } + /** * 获取指定语言值 * diff --git a/src/main/java/com/imyeyu/spring/bean/Page.java b/src/main/java/com/imyeyu/spring/bean/Page.java index d62c276..03c2d5e 100644 --- a/src/main/java/com/imyeyu/spring/bean/Page.java +++ b/src/main/java/com/imyeyu/spring/bean/Page.java @@ -10,56 +10,115 @@ import java.util.LinkedHashMap; /** * 抽象页面查询参数 * + * @param 查询示例类型 * @author 夜雨 * @version 2023-06-02 14:47 */ public class Page extends BasePage { + /** 精确匹配示例 */ protected T equalsExample; + /** 模糊匹配示例 */ protected T likesExample; + /** 排序字段映射 */ protected LinkedHashMap orderMap; + /** + * 创建分页参数 + */ public Page() { } + /** + * 创建分页参数 + * + * @param index 页码 + * @param size 每页数量 + */ public Page(int index, int size) { super(index, size); } + /** + * 获取偏移量 + * + * @return 偏移量 + */ public long getOffset() { return (long) index * size; } + /** + * 获取限制数量 + * + * @return 限制数量 + */ public long getLimit() { return size; } + /** + * 获取精确匹配示例 + * + * @return 精确匹配示例 + */ public T getEqualsExample() { return equalsExample; } + /** + * 设置精确匹配示例 + * + * @param equalsExample 精确匹配示例 + */ public void setEqualsExample(T equalsExample) { this.equalsExample = equalsExample; } + /** + * 获取模糊匹配示例 + * + * @return 模糊匹配示例 + */ public T getLikesExample() { return likesExample; } + /** + * 设置模糊匹配示例 + * + * @param likesExample 模糊匹配示例 + */ public void setLikesExample(T likesExample) { this.likesExample = likesExample; } + /** + * 获取排序映射 + * + * @return 排序映射 + */ public LinkedHashMap getOrderMap() { return orderMap; } + /** + * 设置排序映射 + * + * @param orderMap 排序映射 + */ public void setOrderMap(LinkedHashMap orderMap) { this.orderMap = orderMap; } + /** + * 添加排序字段 + * + * @param field 字段名 + * @param orderType 排序方式 + */ public void addOrder(String field, BaseMapper.OrderType orderType) { orderMap = TimiJava.defaultIfNull(orderMap, new LinkedHashMap<>()); orderMap.put(Text.camelCase2underscore(field), orderType); diff --git a/src/main/java/com/imyeyu/spring/bean/PageResult.java b/src/main/java/com/imyeyu/spring/bean/PageResult.java index 369df70..fb14b22 100644 --- a/src/main/java/com/imyeyu/spring/bean/PageResult.java +++ b/src/main/java/com/imyeyu/spring/bean/PageResult.java @@ -5,8 +5,15 @@ import com.imyeyu.java.bean.BasePageResult; /** * 抽象页面查询结果 * + * @param 列表元素类型 * @author 夜雨 * @version 2023-06-02 14:47 */ public class PageResult extends BasePageResult { + + /** + * 创建分页结果 + */ + public PageResult() { + } } diff --git a/src/main/java/com/imyeyu/spring/bean/RedisConfigParams.java b/src/main/java/com/imyeyu/spring/bean/RedisConfigParams.java index 975fedd..1441844 100644 --- a/src/main/java/com/imyeyu/spring/bean/RedisConfigParams.java +++ b/src/main/java/com/imyeyu/spring/bean/RedisConfigParams.java @@ -8,6 +8,12 @@ package com.imyeyu.spring.bean; */ public class RedisConfigParams { + /** + * 创建 Redis 配置参数 + */ + public RedisConfigParams() { + } + /** 地址 */ private String host; diff --git a/src/main/java/com/imyeyu/spring/bean/RequestRange.java b/src/main/java/com/imyeyu/spring/bean/RequestRange.java index 7198a93..96cbcca 100644 --- a/src/main/java/com/imyeyu/spring/bean/RequestRange.java +++ b/src/main/java/com/imyeyu/spring/bean/RequestRange.java @@ -1,39 +1,75 @@ package com.imyeyu.spring.bean; /** + * 请求范围参数 + * * @author 夜雨 * @since 2025-07-14 17:09 */ public class RequestRange { + /** 起始值 */ private long start; + /** 结束值 */ private long end; + /** 范围长度 */ private long length; + /** + * 创建请求范围 + * + * @param start 起始值 + * @param end 结束值 + */ public RequestRange(long start, long end) { this.start = start; this.end = end; } + /** + * 获取起始值 + * + * @return 起始值 + */ public long getStart() { return start; } + /** + * 设置起始值 + * + * @param start 起始值 + */ public void setStart(long start) { this.start = start; } + /** + * 获取结束值 + * + * @return 结束值 + */ public long getEnd() { return end; } + /** + * 设置结束值 + * + * @param end 结束值 + */ public void setEnd(long end) { this.end = end; } + /** + * 获取范围长度 + * + * @return 范围长度 + */ public long getLength() { return end - start + 1; } -} \ No newline at end of file +} diff --git a/src/main/java/com/imyeyu/spring/config/AbstractRedisConfig.java b/src/main/java/com/imyeyu/spring/config/AbstractRedisConfig.java index 4d8932f..b24262b 100644 --- a/src/main/java/com/imyeyu/spring/config/AbstractRedisConfig.java +++ b/src/main/java/com/imyeyu/spring/config/AbstractRedisConfig.java @@ -21,6 +21,12 @@ import java.time.Duration; * @version 2021-11-21 10:00 */ public abstract class AbstractRedisConfig implements CachingConfigurer { + + /** + * 创建 Redis 配置 + */ + protected AbstractRedisConfig() { + } /** * 构建 Redis 基本配置 diff --git a/src/main/java/com/imyeyu/spring/entity/BaseEntity.java b/src/main/java/com/imyeyu/spring/entity/BaseEntity.java index 87273f4..3d1db6b 100644 --- a/src/main/java/com/imyeyu/spring/entity/BaseEntity.java +++ b/src/main/java/com/imyeyu/spring/entity/BaseEntity.java @@ -13,6 +13,12 @@ import java.io.Serializable; */ public class BaseEntity implements Serializable, Creatable, Updatable, Deletable { + /** + * 创建基础实体 + */ + public BaseEntity() { + } + /** 创建时间 */ protected Long createdAt; diff --git a/src/main/java/com/imyeyu/spring/entity/Entity.java b/src/main/java/com/imyeyu/spring/entity/Entity.java index c371102..24c48bc 100644 --- a/src/main/java/com/imyeyu/spring/entity/Entity.java +++ b/src/main/java/com/imyeyu/spring/entity/Entity.java @@ -14,6 +14,12 @@ public class Entity extends BaseEntity implements IDEntity { @Id protected Long id; + /** + * 创建基础 ID 实体 + */ + public Entity() { + } + /** * 获取 ID * diff --git a/src/main/java/com/imyeyu/spring/entity/IDEntity.java b/src/main/java/com/imyeyu/spring/entity/IDEntity.java index c54db99..1465f63 100644 --- a/src/main/java/com/imyeyu/spring/entity/IDEntity.java +++ b/src/main/java/com/imyeyu/spring/entity/IDEntity.java @@ -3,6 +3,7 @@ package com.imyeyu.spring.entity; /** * ID 实体 * + * @param ID 类型 * @author 夜雨 * @since 2025-02-07 17:10 */ diff --git a/src/main/java/com/imyeyu/spring/entity/UUIDEntity.java b/src/main/java/com/imyeyu/spring/entity/UUIDEntity.java index 2021a94..050d9e1 100644 --- a/src/main/java/com/imyeyu/spring/entity/UUIDEntity.java +++ b/src/main/java/com/imyeyu/spring/entity/UUIDEntity.java @@ -16,6 +16,12 @@ public class UUIDEntity extends BaseEntity implements IDEntity { @AutoUUID protected String id; + /** + * 创建 UUID 实体 + */ + public UUIDEntity() { + } + public String getId() { return id; } diff --git a/src/main/java/com/imyeyu/spring/handler/GsonHandler.java b/src/main/java/com/imyeyu/spring/handler/GsonHandler.java index 2260f53..30f4b5e 100644 --- a/src/main/java/com/imyeyu/spring/handler/GsonHandler.java +++ b/src/main/java/com/imyeyu/spring/handler/GsonHandler.java @@ -19,6 +19,12 @@ import java.sql.SQLException; */ public class GsonHandler extends BaseTypeHandler { + /** + * 创建 Gson 类型处理器 + */ + public GsonHandler() { + } + @Override public void setNonNullParameter(PreparedStatement ps, int i, JsonElement parameter, JdbcType jdbcType) throws SQLException { ps.setString(i, parameter.toString()); diff --git a/src/main/java/com/imyeyu/spring/mapper/BaseMapper.java b/src/main/java/com/imyeyu/spring/mapper/BaseMapper.java index 50a0f94..aa5e648 100644 --- a/src/main/java/com/imyeyu/spring/mapper/BaseMapper.java +++ b/src/main/java/com/imyeyu/spring/mapper/BaseMapper.java @@ -14,6 +14,8 @@ import java.util.List; /** * 基本 SQL 映射，子接口可以不实现 * + * @param 实体类型 + * @param

主键类型 * @author 夜雨 * @version 2021-07-16 09:40 */ @@ -27,17 +29,23 @@ public interface BaseMapper { */ enum OrderType { + /** 升序 */ ASC, + /** 降序 */ DESC } + /** 未删除条件 */ String NOT_DELETE = " AND `deleted_at` IS NULL "; + /** 限制一条 */ String LIMIT_1 = " LIMIT 1"; + /** 当前时间戳毫秒 */ String UNIX_TIME = " FLOOR(UNIX_TIMESTAMP(NOW(3)) * 1000) "; + /** 分页限制 */ String PAGE = NOT_DELETE + " LIMIT #{offset}, #{limit}"; /** @@ -71,6 +79,11 @@ public interface BaseMapper { return result; } + /** + * 查询全部数据 + * + * @return 数据列表 + */ @SelectProvider(type = SQLProvider.class, method = "selectAll") List selectAll(); @@ -92,9 +105,21 @@ public interface BaseMapper { @SelectProvider(type = SQLProvider.class, method = "select") T select(P id); + /** + * 根据示例查询单条数据 + * + * @param t 示例对象 + * @return 数据对象 + */ @SelectProvider(type = SQLProvider.class, method = "selectByExample") T selectByExample(T t); + /** + * 根据示例查询全部数据 + * + * @param t 示例对象 + * @return 数据列表 + */ @SelectProvider(type = SQLProvider.class, method = "selectAllByExample") List selectAllByExample(T t); @@ -106,6 +131,11 @@ public interface BaseMapper { @UpdateProvider(type = SQLProvider.class, method = "update") void update(T t); + /** + * 选择性更新 + * + * @param t 数据对象 + */ @UpdateProvider(type = SQLProvider.class, method = "updateSelective") void updateSelective(T t); @@ -117,6 +147,11 @@ public interface BaseMapper { @UpdateProvider(type = SQLProvider.class, method = "delete") void delete(P id); + /** + * 根据示例批量逻辑删除 + * + * @param t 示例对象 + */ @UpdateProvider(type = SQLProvider.class, method = "deleteAllByExample") void deleteAllByExample(T t); diff --git a/src/main/java/com/imyeyu/spring/service/AbstractEntityService.java b/src/main/java/com/imyeyu/spring/service/AbstractEntityService.java index ea6628d..e1022d9 100644 --- a/src/main/java/com/imyeyu/spring/service/AbstractEntityService.java +++ b/src/main/java/com/imyeyu/spring/service/AbstractEntityService.java @@ -20,7 +20,17 @@ public abstract class AbstractEntityService implements BaseService { /** 基本 Mapper */ protected BaseMapper baseMapper; - /** @return Mapper 实例 */ + /** + * 创建实体服务 + */ + protected AbstractEntityService() { + } + + /** + * 获取 Mapper 实例 + * + * @return Mapper 实例 + */ protected abstract BaseMapper mapper(); /** 检查 mapper */ diff --git a/src/main/java/com/imyeyu/spring/service/DeletableService.java b/src/main/java/com/imyeyu/spring/service/DeletableService.java index a801f5d..c6e27b4 100644 --- a/src/main/java/com/imyeyu/spring/service/DeletableService.java +++ b/src/main/java/com/imyeyu/spring/service/DeletableService.java @@ -5,6 +5,7 @@ import com.imyeyu.java.bean.timi.TimiException; /** * 可软删除实体服务 * + * @param

主键类型 * @author 夜雨 * @since 2025-05-14 17:30 */ diff --git a/src/main/java/com/imyeyu/spring/service/DestroyableService.java b/src/main/java/com/imyeyu/spring/service/DestroyableService.java index 14c4231..49758d1 100644 --- a/src/main/java/com/imyeyu/spring/service/DestroyableService.java +++ b/src/main/java/com/imyeyu/spring/service/DestroyableService.java @@ -5,6 +5,7 @@ import com.imyeyu.java.bean.timi.TimiException; /** * 可销毁（物理删除）实体服务 * + * @param

主键类型 * @author 夜雨 * @since 2025-05-14 17:30 */ diff --git a/src/main/java/com/imyeyu/spring/util/AbstractValidator.java b/src/main/java/com/imyeyu/spring/util/AbstractValidator.java index 2381f28..5ab3a93 100644 --- a/src/main/java/com/imyeyu/spring/util/AbstractValidator.java +++ b/src/main/java/com/imyeyu/spring/util/AbstractValidator.java @@ -9,11 +9,19 @@ import java.lang.annotation.Annotation; /** * 数据验证动态消息返回抽象类 * + * @param 注解类型 + * @param 校验数据类型 * @author 夜雨 * @version 2023-05-07 00:08 */ public abstract class AbstractValidator implements ConstraintValidator { + /** + * 创建校验器 + */ + protected AbstractValidator() { + } + /** * 验证处理器，入参验证数据，返回错误消息语言映射，返回 null 时表示通过验证 * @@ -32,4 +40,4 @@ public abstract class AbstractValidator implements Cons } return true; } -} \ No newline at end of file +} diff --git a/src/main/java/com/imyeyu/spring/util/GlobalExceptionHandler.java b/src/main/java/com/imyeyu/spring/util/GlobalExceptionHandler.java index 272e5bd..3b8fd0a 100644 --- a/src/main/java/com/imyeyu/spring/util/GlobalExceptionHandler.java +++ b/src/main/java/com/imyeyu/spring/util/GlobalExceptionHandler.java @@ -28,12 +28,20 @@ public class GlobalExceptionHandler { private static final Logger log = LoggerFactory.getLogger(GlobalExceptionHandler.class); private static final String DEV_LANG_CONFIG = "dev.lang"; + /** + * 创建全局异常处理器 + */ + public GlobalExceptionHandler() { + } + @Value("${spring.profiles.active}") private String env; /** - * @param e - * @return + * 消息转换异常 + * + * @param e 异常 + * @return 异常返回 */ @ExceptionHandler(HttpMessageConversionException.class) public TimiResponse conversionException(HttpMessageConversionException e) { diff --git a/src/main/java/com/imyeyu/spring/util/GlobalReturnHandler.java b/src/main/java/com/imyeyu/spring/util/GlobalReturnHandler.java index 059f242..b14b102 100644 --- a/src/main/java/com/imyeyu/spring/util/GlobalReturnHandler.java +++ b/src/main/java/com/imyeyu/spring/util/GlobalReturnHandler.java @@ -32,8 +32,15 @@ public class GlobalReturnHandler implements ResponseBodyAdvice { private static final Logger log = LoggerFactory.getLogger(GlobalReturnHandler.class); + /** 多语言头处理回调 */ private CallbackArgReturn, String> multilingualHeader; + /** + * 创建全局返回处理器 + */ + public GlobalReturnHandler() { + } + @Override public boolean supports(@NonNull MethodParameter returnType, @NonNull Class> converterType) { return Objects.requireNonNull(returnType.getMethod()).getAnnotation(IgnoreGlobalReturn.class) == null; @@ -71,10 +78,20 @@ public class GlobalReturnHandler implements ResponseBodyAdvice { return result; } + /** + * 获取多语言头处理回调 + * + * @return 处理回调 + */ public CallbackArgReturn, String> getMultilingualHeader() { return multilingualHeader; } + /** + * 设置多语言头处理回调 + * + * @param multilingualHeader 处理回调 + */ public void setMultilingualHeader(CallbackArgReturn, String> multilingualHeader) { this.multilingualHeader = multilingualHeader; } diff --git a/src/main/java/com/imyeyu/spring/util/Redis.java b/src/main/java/com/imyeyu/spring/util/Redis.java index e65ac89..a9020fd 100644 --- a/src/main/java/com/imyeyu/spring/util/Redis.java +++ b/src/main/java/com/imyeyu/spring/util/Redis.java @@ -22,6 +22,8 @@ import java.util.function.Consumer; * RedisTemplate 功能封装，简化 Redis 操作 *

serializer 为该 RedisTemplate 的键的序列化操作，序列化解析器由 {@link AbstractRedisConfig} 提供 * + * @param 键类型 + * @param 值类型 * @author 夜雨 * @version 2021-11-21 09:58 */ @@ -30,6 +32,12 @@ public class Redis { private final RedisSerializer serializer; private final RedisTemplate redis; + /** + * 创建 Redis 操作封装 + * + * @param redis RedisTemplate 实例 + * @param serializer 键序列化器 + */ public Redis(RedisTemplate redis, RedisSerializer serializer) { this.redis = redis; this.serializer = serializer; @@ -47,9 +55,9 @@ public class Redis { /** * 加锁 * - * @param key - * @param value - * @param timeoutMS + * @param key 键 + * @param value 值 + * @param timeoutMS 超时时间毫秒 * @return true 为加锁成功 */ public boolean lock(K key, V value, long timeoutMS) { @@ -57,6 +65,11 @@ public class Redis { return lock != null && lock; } + /** + * 释放锁 + * + * @param key 键 + */ public void releaseLock(K key) { destroy(key); } diff --git a/src/main/java/com/imyeyu/spring/util/RedisSerializers.java b/src/main/java/com/imyeyu/spring/util/RedisSerializers.java index 0fe258c..73015b7 100644 --- a/src/main/java/com/imyeyu/spring/util/RedisSerializers.java +++ b/src/main/java/com/imyeyu/spring/util/RedisSerializers.java @@ -8,11 +8,17 @@ import org.springframework.data.redis.serializer.StringRedisSerializer; import java.nio.charset.StandardCharsets; /** + * Redis 序列化工具 + * * @author 夜雨 * @version 2023-07-17 16:20 */ public class RedisSerializers { + /** 工具类禁止实例化 */ + private RedisSerializers() { + } + /** 字符串序列化 */ public static final StringRedisSerializer STRING = new StringRedisSerializer(); @@ -76,7 +82,13 @@ public class RedisSerializers { } }; - /** Gson 序列化 */ + /** + * Gson 序列化 + * + * @param 数据类型 + * @param clazz 数据类型 + * @return Redis 序列化器 + */ public static RedisSerializer gsonSerializer(Class clazz) { return new RedisSerializer<>() { diff --git a/src/main/java/com/imyeyu/spring/util/SQLProvider.java b/src/main/java/com/imyeyu/spring/util/SQLProvider.java index 13ac490..2602d19 100644 --- a/src/main/java/com/imyeyu/spring/util/SQLProvider.java +++ b/src/main/java/com/imyeyu/spring/util/SQLProvider.java @@ -45,6 +45,12 @@ public class SQLProvider { /** 反射缓存 */ private static final Map, EntityMeta> ENTITY_META_CACHE = new ConcurrentHashMap<>(); + /** + * 创建 SQL 提供器 + */ + public SQLProvider() { + } + /** * 根据 Page 对象查询数据列表 * @@ -148,6 +154,12 @@ public class SQLProvider { return sql.toString(); } + /** + * 查询全部数据 + * + * @param context 代理器上下文 + * @return SQL + */ public String selectAll(ProviderContext context) { EntityMeta meta = getEntityMeta(context); StringBuilder sql = new StringBuilder(); @@ -162,6 +174,7 @@ public class SQLProvider { * 插入 *

不实现 {@link Creatable} 也允许调用是合理的，某些数据属于关联数据，不参与主创建过程

* + * @param context 代理器上下文 * @param entity 实体 * @return SQL */ @@ -299,6 +312,12 @@ public class SQLProvider { return "UPDATE `%s` SET `deleted_at` = %s WHERE `%s` = #{id}".formatted(meta.table, Time.now(), meta.idFieldColumn.columnName); } + /** + * 根据示例批量逻辑删除 + * + * @param entity 实体 + * @return SQL + */ public String deleteAllByExample(Object entity) { EntityMeta meta = getEntityMeta(entity.getClass()); TimiException.required(meta.canDelete, "not allow delete for %s".formatted(meta.entityClass)); @@ -398,6 +417,11 @@ public class SQLProvider { /** true 为可销毁（硬删除） */ final boolean canDestroy; + /** + * 创建实体元数据 + * + * @param entityClass 实体类型 + */ public EntityMeta(Class entityClass) { this.entityClass = entityClass; @@ -459,38 +483,83 @@ public class SQLProvider { return sb.substring(0, sb.length() - 1); } + /** + * 获取实体类型 + * + * @return 实体类型 + */ public Class getEntityClass() { return entityClass; } + /** + * 获取表名 + * + * @return 表名 + */ public String getTable() { return table; } + /** + * 获取查询字段映射 + * + * @return 查询字段映射 + */ public String getSelectAllClause() { return selectAllClause; } + /** + * 获取 ID 字段映射 + * + * @return ID 字段映射 + */ public FieldColumn getIdFieldColumn() { return idFieldColumn; } + /** + * 获取字段映射列表 + * + * @return 字段映射列表 + */ public List getFieldColumnList() { return fieldColumnList; } + /** + * 是否可创建 + * + * @return true 为可创建 + */ public boolean canCreate() { return canCreate; } + /** + * 是否可更新 + * + * @return true 为可更新 + */ public boolean canUpdate() { return canUpdate; } + /** + * 是否可删除 + * + * @return true 为可删除 + */ public boolean canDelete() { return canDelete; } + /** + * 是否可销毁 + * + * @return true 为可销毁 + */ public boolean canDestroy() { return canDestroy; } @@ -525,6 +594,11 @@ public class SQLProvider { final DeleteColumn.Type deleteColumnType; + /** + * 创建字段映射 + * + * @param field 字段 + */ public FieldColumn(Field field) { this.field = field; @@ -551,6 +625,12 @@ public class SQLProvider { } } + /** + * 判断字段值是否为空 + * + * @param entity 实体 + * @return true 为 null + */ public boolean isNull(Object entity) { try { return Ref.getFieldValue(entity, field, Object.class) == null; @@ -559,10 +639,22 @@ public class SQLProvider { } } + /** + * 判断字段值是否非空 + * + * @param entity 实体 + * @return true 为非 null + */ public boolean isNotNull(Object entity) { return !isNull(entity); } + /** + * 判断字段值是否为空 + * + * @param entity 实体 + * @return true 为空 + */ public boolean isEmpty(Object entity) { try { return TimiJava.isEmpty(Ref.getFieldValue(entity, field, Object.class)); @@ -571,10 +663,22 @@ public class SQLProvider { } } + /** + * 判断字段值是否非空 + * + * @param entity 实体 + * @return true 为非空 + */ public boolean isNotEmpty(Object entity) { return !isEmpty(entity); } + /** + * 获取字段字符串值 + * + * @param obj 实体 + * @return 字符串值 + */ public String getAsString(Object obj) { try { return field.get(obj).toString(); @@ -583,30 +687,65 @@ public class SQLProvider { } } + /** + * 获取字段 + * + * @return 字段 + */ public Field getField() { return field; } + /** + * 获取字段名 + * + * @return 字段名 + */ public String getFieldName() { return fieldName; } + /** + * 获取列名 + * + * @return 列名 + */ public String getColumnName() { return columnName; } + /** + * 是否为 ID 字段 + * + * @return true 为 ID 字段 + */ public boolean isId() { return isId; } + /** + * 是否非 ID 字段 + * + * @return true 为非 ID 字段 + */ public boolean isNotId() { return !isId(); } + /** + * 是否自动 UUID + * + * @return true 为自动 UUID + */ public boolean isAutoUUID() { return isAutoUUID; } + /** + * 是否自动大写 UUID + * + * @return true 为自动大写 UUID + */ public boolean isAutoUpperUUID() { return isAutoUpperUUID; } diff --git a/src/main/java/com/imyeyu/spring/util/YamlPropertySourceFactory.java b/src/main/java/com/imyeyu/spring/util/YamlPropertySourceFactory.java index 35f7305..8745a8f 100644 --- a/src/main/java/com/imyeyu/spring/util/YamlPropertySourceFactory.java +++ b/src/main/java/com/imyeyu/spring/util/YamlPropertySourceFactory.java @@ -9,13 +9,19 @@ import java.io.IOException; import java.util.List; /** - * + * Yaml 属性源加载工厂 * * @author 夜雨 * @since 2025-10-13 16:29 */ public class YamlPropertySourceFactory implements PropertySourceFactory { + /** + * 创建 Yaml 属性源工厂 + */ + public YamlPropertySourceFactory() { + } + @Override public @org.springframework.lang.NonNull PropertySource createPropertySource(String name, EncodedResource resource) throws IOException { List> sources = new YamlPropertySourceLoader().load(resource.getResource().getFilename(), resource.getResource());