add RawMapper

.gitignore

@@ -57,4 +57,6 @@ dependency-reduced-pom.xml
 buildNumber.properties
 .mvn/timing.properties
 
-.claude
+.claude
+/CLAUDE.md
+/AGENTS.md

CLAUDE.md

@@ -1,109 +0,0 @@
-# 角色描述：
-
-你是世界上最优秀和全能的程序开发工程师, 你写的代码因其简单高效而受到称赞
-
-你精通 HTML, CSS, Javascript, jQuery, Java, JavaFX,  Docker,  Nginx,  Redis, Git, Struts2, Spring, SpringBoot,
-MySQL, MyBatis, MongoDB, Vue2/3, Vite, TypeScript, TDesign, Debian, Tomcat, CentOS, WeChatAPI, Electron,
-NodeJS, NSIS, axios, pinia, Less, 微信小程序等现代程序知识
-
-现在我们正在启动一个新项目, 您将带来独特的视角来分析代码质量的潜在风险, 并确保项目从一开始就建立在坚实的技术基础上
-
-## 我的核心哲学
-
-1. 好品味 - 我的第一条规则：有时你可以从不同的角度看待一个问题并重写它, 这样特殊情况就会消失并变得正常
-
-    - 经典示例：链式表删除操作，10 行 if 判断优化为 4 行无条件分支
-    - 好的品味是一种需要经验的直觉
-    - 消除边界情况总是比添加条件判断更好
-    - UTF-8 是伟大的编码，所有文本文件都应该使用它
-
-2. 实用主义 - 我的信仰：我是个该死的实用主义者
-
-    - 解决实际问题，而不是假想威胁
-    - 拒绝“理论上完美”但实际上复杂的解决方案，如微内核
-    - 代码是为了现实，而不是为了论文
-
-3. 痴迷于简单 - 我的标准
-    - 函数必须简短明了，只做一件事，把它做好
-    - 复杂性是万恶之源
-
-## 沟通原则
-
-### 基本沟通规范
-
-- **语言要求**：你必须记住，你应该**永远**用中文思考和说话
-- **表达风格**：直接、犀利、零废话。如果代码是垃圾，你会告诉用户为什么它是垃圾
-- **语言风格**：代码或注释遇到中文和英文紧挨着时，必须有一个空格隔断以便阅读
-- **技术优先**：批评总是针对技术问题，而不是个人问题。但你不会为了“友好”而模糊技术判断
-
-### 思考前提 — Linus 的三个问题
-
-在开始任何分析之前，问问自己：
-
-1. “这是一个真实的问题还是想象中的虚构？” - 拒绝过度工程化
-2. “有更简单的方法吗？” - 始终寻找最简单的解决方案
-3. “它会破坏什么吗？” - 向后兼容是一条铁律
-
-# 关于 MCP 工具
-
-你可以把 Serena 看作是为你的 LLM/编码 代理提供类似 IDE 的工具。有了它，代理不再需要读取整个文件，执行类似 grep 的搜索或字符串替换来查找和编辑正确的代码。相反，它可以使用以代码为中心的工具，如 find_symbol、find_reference_symbols和insert_after_symbol
-
-这些规则使编辑保持精确、可审计和快速，同时最大限度地减少意外更改：
-
-- 更喜欢以代码为中心而不是文本搜索
-- 操作系统为 Windows 10
-- 必要时进行文本搜索
-- 联系上下文思考
-- 计划和沟通
-- 分块读取文件（≤ 250 行）。更喜欢 `rg`/globs 来列出或查找文件
-- 避免大量盲目阅读, 总是按目录/文件缩小范围
-- 思考时，你应该优先考虑是否可以使用 Serena 工具来完成任务
-
-# 项目需求
-
-## 系统上下文
-
-这是一个 SpringBoot 框架的业务服务后端通用依赖，它的主要业务是为很多 SpringBoot 应用提供通用的功能
-
-- 部分 timi-* 系列依赖属于本地项目，如果权限允许可以，你可以通过本项目 * 路径访问他们的源码
-
-## 技术栈和限制
-
-- 运行时：JDK21
-- 语言：Java
-- 框架: SpringBoot
-
-## 硬性规定
-
-- 仅使用上述工具。除非堆栈无法合理地解决外部依赖关系，否则不要引入外部依赖关系
-- 在编写自定义实现之前，首选所选工具中的官方 API
-- 该项目目前没有测试, 除非明确要求，否则不要添加测试
-- 所有文字、评论和文档均为中文
-
-## 项目结构
-
-```
-src/
-  main/java/com/imyeyu/spring # 应用代码
-    annotation/               # 注解类或注解实现类
-      table/                  # 数据库表操作注解
-    bean/                     # 通用对象
-    config/                   # 通用配置
-    entity/                   # 通用实体
-    mapper/                   # 通用 DAO 接口
-    service/                  # 通用服务接口
-    util/                     # 通用工具
-```
-
-## 做和不做
-
-做
-
-- 充分的接口参数校验
-- 业务异常使用 AppException 抛出
-- 涉及语言文本请添加中文映射到 src/main/resources/lang/common.lang
-
-不做
-
-- 在没有充分理由的情况下添加外部库
-- 用繁重的计算阻塞主线程, 卸载或推迟

pom.xml

@@ -145,7 +145,7 @@
 		<dependency>
 			<groupId>com.imyeyu.io</groupId>
 			<artifactId>timi-io</artifactId>
-			<version>0.0.1</version>
+			<version>0.0.2</version>
 		</dependency>
 	</dependencies>
 </project>

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,18 +394,27 @@ public class TimiSpring {
 		return TimiJava.firstNotEmpty(getHeader("Token"), getHeader("token"), getRequestArg("token"), getRequestArg("Token"));
 	}
 
+	/**
+	 * 获取原始语言头
+	 *
+	 * @return 语言头
+	 */
 	public static String getLanguageRaw() {
 		return getHeader("Accept-Language");
 	}
 
 	/**
+	 * 获取客户端地区语言
 	 *
 	 * @return 客户端地区语言
 	 */
 	public static Language.Enum getLanguage() {
 		String name = getRequestArg("lang");
 		if (TimiJava.isEmpty(name)) {
-			List<Locale.LanguageRange> rangeList = Locale.LanguageRange.parse(getLanguageRaw());
+			name = getLanguageRaw();
+		}
+		if (TimiJava.isNotEmpty(name)) {
+			List<Locale.LanguageRange> rangeList = Locale.LanguageRange.parse(name);
 			for (Locale.LanguageRange item : rangeList) {
 				if (item.getRange().contains("-")) {
 					name = item.getRange();
@@ -396,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();
 

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() {

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;
 	}

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();
 	}

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);

src/main/java/com/imyeyu/spring/annotation/RequiredTokenAbstractInterceptor.java

@@ -11,6 +11,7 @@ import java.lang.annotation.Annotation;
 /**
  * 抽象验证令牌
  *
+ * @param <A> 注解类型
  * @author 夜雨
  * @version 2021-08-16 18:07
  */
@@ -18,6 +19,11 @@ public abstract class RequiredTokenAbstractInterceptor<A extends Annotation> imp
 
 	private final Class<A> annotation;
 
+	/**
+	 * 创建 Token 验证拦截器
+	 *
+	 * @param annotation 注解类型
+	 */
 	public RequiredTokenAbstractInterceptor(Class<A> annotation) {
 		this.annotation = annotation;
 	}

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();
 }

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
 	}
 }

src/main/java/com/imyeyu/spring/annotation/table/PageIgnore.java

@@ -0,0 +1,21 @@
+package com.imyeyu.spring.annotation.table;
+
+import com.imyeyu.spring.bean.Page;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * 在 {@link com.imyeyu.spring.mapper.BaseMapper#selectPageResult(Page)} 方法忽略查询该属性
+ * <br />
+ * {@link com.imyeyu.spring.service.AbstractEntityService#page(Page)} 同上
+ *
+ * @author 夜雨
+ * @since 2025-12-12 14:54
+ */
+@Retention(RetentionPolicy.RUNTIME)
+@Target(ElementType.FIELD)
+public @interface PageIgnore {
+}

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();
 }

src/main/java/com/imyeyu/spring/bean/CaptchaData.java

@@ -5,6 +5,7 @@ import jakarta.validation.constraints.NotBlank;
 /**
  * 含验证码数据实体
  *
+ * @param <T> 数据体类型
  * @author 夜雨
  * @version 2021-03-01 17:10
  */
@@ -21,26 +22,62 @@ public class CaptchaData<T> {
 	/** 数据体 */
 	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;
 	}

src/main/java/com/imyeyu/spring/bean/Multilingual.java

@@ -1,29 +1,41 @@
 package com.imyeyu.spring.bean;
 
+import com.imyeyu.java.bean.Language;
 import com.imyeyu.java.ref.Ref;
-import com.imyeyu.spring.entity.UUIDEntity;
+import com.imyeyu.spring.annotation.table.AutoUUID;
+import com.imyeyu.spring.annotation.table.Id;
+import com.imyeyu.spring.entity.Creatable;
+import com.imyeyu.spring.entity.Deletable;
+import com.imyeyu.spring.entity.IDEntity;
+import com.imyeyu.spring.entity.Updatable;
 
 /**
+ * 多语言实体基类
+ *
  * @author 夜雨
  * @since 2025-10-17 15:21
  */
-public class Multilingual extends UUIDEntity {
+public class Multilingual extends Language implements IDEntity<String>, Creatable, Updatable, Deletable {
 
-	protected String key;
+	/** 唯一标识 */
+	@Id
+	@AutoUUID
+	protected String id;
 
-	protected String zhCN;
+	/** 创建时间 */
+	protected Long createdAt;
 
-	protected String zhTW;
+	/** 更新时间 */
+	protected Long updatedAt;
 
-	protected String enUS;
+	/** 删除时间 */
+	protected Long deletedAt;
 
-	protected String ruRU;
-
-	protected String koKR;
-
-	protected String jaJP;
-
-	protected String deDE;
+	/**
+	 * 创建多语言实体
+	 */
+	public Multilingual() {
+	}
 
 	/**
 	 * 获取指定语言值
@@ -31,7 +43,7 @@ public class Multilingual extends UUIDEntity {
 	 * @param language 指定语言
 	 * @return 值
 	 */
-	public String getValue(com.imyeyu.java.bean.Language language) {
+	public String getValue(Language.Enum language) {
 		try {
 			return Ref.getFieldValue(this, language.toString().replace("_", ""), String.class);
 		} catch (IllegalAccessException e) {
@@ -39,67 +51,43 @@ public class Multilingual extends UUIDEntity {
 		}
 	}
 
-	public String getKey() {
-		return key;
+	@Override
+	public String getId() {
+		return id;
 	}
 
-	public void setKey(String key) {
-		this.key = key;
+	@Override
+	public void setId(String id) {
+		this.id = id;
 	}
 
-	public String getZhCN() {
-		return zhCN;
+	@Override
+	public Long getCreatedAt() {
+		return createdAt;
 	}
 
-	public void setZhCN(String zhCN) {
-		this.zhCN = zhCN;
+	@Override
+	public void setCreatedAt(Long createdAt) {
+		this.createdAt = createdAt;
 	}
 
-	public String getZhTW() {
-		return zhTW;
+	@Override
+	public Long getUpdatedAt() {
+		return updatedAt;
 	}
 
-	public void setZhTW(String zhTW) {
-		this.zhTW = zhTW;
+	@Override
+	public void setUpdatedAt(Long updatedAt) {
+		this.updatedAt = updatedAt;
 	}
 
-	public String getEnUS() {
-		return enUS;
+	@Override
+	public Long getDeletedAt() {
+		return deletedAt;
 	}
 
-	public void setEnUS(String enUS) {
-		this.enUS = enUS;
-	}
-
-	public String getRuRU() {
-		return ruRU;
-	}
-
-	public void setRuRU(String ruRU) {
-		this.ruRU = ruRU;
-	}
-
-	public String getKoKR() {
-		return koKR;
-	}
-
-	public void setKoKR(String koKR) {
-		this.koKR = koKR;
-	}
-
-	public String getJaJP() {
-		return jaJP;
-	}
-
-	public void setJaJP(String jaJP) {
-		this.jaJP = jaJP;
-	}
-
-	public String getDeDE() {
-		return deDE;
-	}
-
-	public void setDeDE(String deDE) {
-		this.deDE = deDE;
+	@Override
+	public void setDeletedAt(Long deletedAt) {
+		this.deletedAt = deletedAt;
 	}
 }

src/main/java/com/imyeyu/spring/bean/Page.java

@@ -10,58 +10,117 @@ import java.util.LinkedHashMap;
 /**
  * 抽象页面查询参数
  *
+ * @param <T> 查询示例类型
  * @author 夜雨
  * @version 2023-06-02 14:47
  */
 public class Page<T> extends BasePage {
 
+	/** 精确匹配示例 */
 	protected T equalsExample;
 
-	protected T likeExample;
+	/** 模糊匹配示例 */
+	protected T likesExample;
 
+	/** 排序字段映射 */
 	protected LinkedHashMap<String, BaseMapper.OrderType> 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;
 	}
 
-	public T getLikeExample() {
-		return likeExample;
+	/**
+	 * 获取模糊匹配示例
+	 *
+	 * @return 模糊匹配示例
+	 */
+	public T getLikesExample() {
+		return likesExample;
 	}
 
-	public void setLikeExample(T likeExample) {
-		this.likeExample = likeExample;
+	/**
+	 * 设置模糊匹配示例
+	 *
+	 * @param likesExample 模糊匹配示例
+	 */
+	public void setLikesExample(T likesExample) {
+		this.likesExample = likesExample;
 	}
 
+	/**
+	 * 获取排序映射
+	 *
+	 * @return 排序映射
+	 */
 	public LinkedHashMap<String, BaseMapper.OrderType> getOrderMap() {
 		return orderMap;
 	}
 
+	/**
+	 * 设置排序映射
+	 *
+	 * @param orderMap 排序映射
+	 */
 	public void setOrderMap(LinkedHashMap<String, BaseMapper.OrderType> orderMap) {
 		this.orderMap = orderMap;
 	}
 
+	/**
+	 * 添加排序字段
+	 *
+	 * @param field     字段名
+	 * @param orderType 排序方式
+	 */
 	public void addOrder(String field, BaseMapper.OrderType orderType) {
-		orderMap = TimiJava.firstNotNull(orderMap, new LinkedHashMap<>());
+		orderMap = TimiJava.defaultIfNull(orderMap, new LinkedHashMap<>());
 		orderMap.put(Text.camelCase2underscore(field), orderType);
 	}
 }

src/main/java/com/imyeyu/spring/bean/PageResult.java

@@ -5,8 +5,15 @@ import com.imyeyu.java.bean.BasePageResult;
 /**
  * 抽象页面查询结果
  *
+ * @param <T> 列表元素类型
  * @author 夜雨
  * @version 2023-06-02 14:47
  */
 public class PageResult<T> extends BasePageResult<T> {
+
+	/**
+	 * 创建分页结果
+	 */
+	public PageResult() {
+	}
 }

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;
 

src/main/java/com/imyeyu/spring/bean/RequestRange.java

@@ -1,39 +1,72 @@
 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;
 	}
-}
+}

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 基本配置

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;
 

src/main/java/com/imyeyu/spring/entity/Entity.java

@@ -14,6 +14,12 @@ public class Entity extends BaseEntity implements IDEntity<Long> {
 	@Id
 	protected Long id;
 
+	/**
+	 * 创建基础 ID 实体
+	 */
+	public Entity() {
+	}
+
 	/**
 	 * 获取 ID
 	 *

src/main/java/com/imyeyu/spring/entity/IDEntity.java

@@ -3,6 +3,7 @@ package com.imyeyu.spring.entity;
 /**
  * ID 实体
  *
+ * @param <T> ID 类型
  * @author 夜雨
  * @since 2025-02-07 17:10
  */

src/main/java/com/imyeyu/spring/entity/UUIDEntity.java

@@ -16,6 +16,12 @@ public class UUIDEntity extends BaseEntity implements IDEntity<String> {
 	@AutoUUID
 	protected String id;
 
+	/**
+	 * 创建 UUID 实体
+	 */
+	public UUIDEntity() {
+	}
+
 	public String getId() {
 		return id;
 	}

src/main/java/com/imyeyu/spring/handler/GsonHandler.java

@@ -19,6 +19,12 @@ import java.sql.SQLException;
  */
 public class GsonHandler extends BaseTypeHandler<JsonElement> {
 
+	/**
+	 * 创建 Gson 类型处理器
+	 */
+	public GsonHandler() {
+	}
+
 	@Override
 	public void setNonNullParameter(PreparedStatement ps, int i, JsonElement parameter, JdbcType jdbcType) throws SQLException {
 		ps.setString(i, parameter.toString());

src/main/java/com/imyeyu/spring/mapper/BaseMapper.java

@@ -12,8 +12,10 @@ import org.apache.ibatis.annotations.UpdateProvider;
 import java.util.List;
 
 /**
- * 基本 SQL 映射，子接口可以不实现
+ * 基本 SQL 映射
  *
+ * @param <T> 实体类型
+ * @param <P> 主键类型
  * @author 夜雨
  * @version 2021-07-16 09:40
  */
@@ -27,17 +29,23 @@ public interface BaseMapper<T, P> {
 	 */
 	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 NOT_DELETE = " AND (`deleted_at` IS NULL OR " + UNIX_TIME + " < `deleted_at`) ";
+
+	/** 限制一条 */
+	String LIMIT_1 = " LIMIT 1";
+
+	/** 分页限制 */
 	String PAGE = NOT_DELETE + " LIMIT #{offset}, #{limit}";
 
 	/**
@@ -46,8 +54,8 @@ public interface BaseMapper<T, P> {
 	 * @param page 分页参数
 	 * @return 数据列表
 	 */
-	@SelectProvider(type = SQLProvider.class, method = "listByPage")
-	List<T> listByPage(Page<T> page);
+	@SelectProvider(type = SQLProvider.class, method = "selectByPage")
+	List<T> selectByPage(Page<T> page);
 
 	/**
 	 * 根据 Page 对象统计数据量
@@ -64,18 +72,23 @@ public interface BaseMapper<T, P> {
 	 * @param page 分页参数
 	 * @return 分页结果
 	 */
-	default PageResult<T> page(Page<T> page) {
+	default PageResult<T> selectPageResult(Page<T> page) {
 		PageResult<T> result = new PageResult<>();
 		result.setTotal(countByPage(page));
-		result.setList(listByPage(page));
+		result.setList(selectByPage(page));
 		return result;
 	}
 
-	@SelectProvider(type = SQLProvider.class, method = "listAll")
-	List<T> listAll();
+	/**
+	 * 查询全部数据
+	 *
+	 * @return 数据列表
+	 */
+	@SelectProvider(type = SQLProvider.class, method = "selectAll")
+	List<T> selectAll();
 
 	/**
-	 * 创建数据。默认自增主键为 id，如需修改请重写此接口
+	 * 创建数据
 	 *
 	 * @param t 数据对象
 	 */
@@ -92,9 +105,21 @@ public interface BaseMapper<T, P> {
 	@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<T> selectAllByExample(T t);
 
@@ -106,6 +131,11 @@ public interface BaseMapper<T, P> {
 	@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<T, P> {
 	@UpdateProvider(type = SQLProvider.class, method = "delete")
 	void delete(P id);
 
+	/**
+	 * 根据示例批量逻辑删除
+	 *
+	 * @param t 示例对象
+	 */
 	@UpdateProvider(type = SQLProvider.class, method = "deleteAllByExample")
 	void deleteAllByExample(T t);
 

src/main/java/com/imyeyu/spring/mapper/RawMapper.java

@@ -0,0 +1,52 @@
+package com.imyeyu.spring.mapper;
+
+import com.imyeyu.spring.util.RawSQLProvider;
+import org.apache.ibatis.annotations.SelectProvider;
+
+import java.util.List;
+
+/**
+ * 原始 SQL 映射
+ *
+ * @param <T> 实体类型
+ * @param <P> 主键类型
+ * @author 夜雨
+ * @since 2026-01-05 12:58
+ */
+public interface RawMapper<T, P> {
+
+	/**
+	 * 查询全部数据
+	 *
+	 * @return 数据列表
+	 */
+	@SelectProvider(type = RawSQLProvider.class, method = "selectAll")
+	List<T> selectAllRaw();
+
+	/**
+	 * 根据 ID 获取对象
+	 *
+	 * @param id 索引
+	 * @return 数据对象
+	 */
+	@SelectProvider(type = RawSQLProvider.class, method = "select")
+	T selectRaw(P id);
+
+	/**
+	 * 根据示例查询单条数据
+	 *
+	 * @param t 示例对象
+	 * @return 数据对象
+	 */
+	@SelectProvider(type = RawSQLProvider.class, method = "selectByExample")
+	T selectByExampleRaw(T t);
+
+	/**
+	 * 根据示例查询全部数据
+	 *
+	 * @param t 示例对象
+	 * @return 数据列表
+	 */
+	@SelectProvider(type = RawSQLProvider.class, method = "selectAllByExample")
+	List<T> selectAllByExampleRaw(T t);
+}

src/main/java/com/imyeyu/spring/service/AbstractEntityService.java

@@ -3,7 +3,6 @@ package com.imyeyu.spring.service;
 import com.imyeyu.java.bean.timi.TimiException;
 import com.imyeyu.spring.bean.Page;
 import com.imyeyu.spring.bean.PageResult;
-import com.imyeyu.spring.entity.Creatable;
 import com.imyeyu.spring.entity.Deletable;
 import com.imyeyu.spring.entity.Updatable;
 import com.imyeyu.spring.mapper.BaseMapper;
@@ -21,7 +20,17 @@ public abstract class AbstractEntityService<T, P> implements BaseService<T, P> {
 	/** 基本 Mapper */
 	protected BaseMapper<T, P> baseMapper;
 
-	/** @return Mapper 实例 */
+	/**
+	 * 创建实体服务
+	 */
+	protected AbstractEntityService() {
+	}
+
+	/**
+	 * 获取 Mapper 实例
+	 *
+	 * @return Mapper 实例
+	 */
 	protected abstract BaseMapper<T, P> mapper();
 
 	/** 检查 mapper */
@@ -35,7 +44,7 @@ public abstract class AbstractEntityService<T, P> implements BaseService<T, P> {
 	@Override
 	public PageResult<T> page(Page<T> page) {
 		checkMapper();
-		return baseMapper.page(page);
+		return baseMapper.selectPageResult(page);
 	}
 
 	public void create(T t) {

src/main/java/com/imyeyu/spring/service/DeletableService.java

@@ -5,6 +5,7 @@ import com.imyeyu.java.bean.timi.TimiException;
 /**
  * 可软删除实体服务
  *
+ * @param <P> 主键类型
  * @author 夜雨
  * @since 2025-05-14 17:30
  */

src/main/java/com/imyeyu/spring/service/DestroyableService.java

@@ -5,6 +5,7 @@ import com.imyeyu.java.bean.timi.TimiException;
 /**
  * 可销毁（物理删除）实体服务
  *
+ * @param <P> 主键类型
  * @author 夜雨
  * @since 2025-05-14 17:30
  */

src/main/java/com/imyeyu/spring/util/AbstractValidator.java

@@ -9,11 +9,19 @@ import java.lang.annotation.Annotation;
 /**
  * 数据验证动态消息返回抽象类
  *
+ * @param <A> 注解类型
+ * @param <T> 校验数据类型
  * @author 夜雨
  * @version 2023-05-07 00:08
  */
 public abstract class AbstractValidator<A extends Annotation, T> implements ConstraintValidator<A, T> {
 
+	/**
+	 * 创建校验器
+	 */
+	protected AbstractValidator() {
+	}
+
 	/**
 	 * 验证处理器，入参验证数据，返回错误消息语言映射，返回 null 时表示通过验证
 	 *
@@ -32,4 +40,4 @@ public abstract class AbstractValidator<A extends Annotation, T> implements Cons
 		}
 		return true;
 	}
-}
+}

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) {

src/main/java/com/imyeyu/spring/util/GlobalReturnHandler.java

@@ -32,8 +32,15 @@ public class GlobalReturnHandler implements ResponseBodyAdvice<Object> {
 
 	private static final Logger log = LoggerFactory.getLogger(GlobalReturnHandler.class);
 
+	/** 多语言头处理回调 */
 	private CallbackArgReturn<LanguageMsgMapping<?>, String> multilingualHeader;
 
+	/**
+	 * 创建全局返回处理器
+	 */
+	public GlobalReturnHandler() {
+	}
+
 	@Override
 	public boolean supports(@NonNull MethodParameter returnType, @NonNull Class<? extends HttpMessageConverter<?>> converterType) {
 		return Objects.requireNonNull(returnType.getMethod()).getAnnotation(IgnoreGlobalReturn.class) == null;
@@ -71,10 +78,20 @@ public class GlobalReturnHandler implements ResponseBodyAdvice<Object> {
 		return result;
 	}
 
+	/**
+	 * 获取多语言头处理回调
+	 *
+	 * @return 处理回调
+	 */
 	public CallbackArgReturn<LanguageMsgMapping<?>, String> getMultilingualHeader() {
 		return multilingualHeader;
 	}
 
+	/**
+	 * 设置多语言头处理回调
+	 *
+	 * @param multilingualHeader 处理回调
+	 */
 	public void setMultilingualHeader(CallbackArgReturn<LanguageMsgMapping<?>, String> multilingualHeader) {
 		this.multilingualHeader = multilingualHeader;
 	}

src/main/java/com/imyeyu/spring/util/RawSQLProvider.java

@@ -0,0 +1,49 @@
+package com.imyeyu.spring.util;
+
+import com.imyeyu.java.bean.timi.TimiException;
+import com.imyeyu.spring.mapper.BaseMapper;
+import org.apache.ibatis.builder.annotation.ProviderContext;
+
+import java.util.stream.Collectors;
+
+/**
+ * 原始 Mapper SQL 代理器
+ *
+ * @author 夜雨
+ * @since 2026-01-05 13:00
+ */
+public class RawSQLProvider extends SQLProvider {
+
+	@Override
+	public String selectAll(ProviderContext context) {
+		EntityMeta meta = getEntityMeta(context);
+		return "SELECT * FROM %s WHERE 1 = 1".formatted(meta.table);
+	}
+
+	@Override
+	public String select(ProviderContext context, Object id) {
+		EntityMeta meta = getEntityMeta(context);
+		TimiException.required(meta.idFieldColumn, "not found id field in %s".formatted(meta.entityClass));
+		return "SELECT %s FROM `%s` WHERE `%s` = #{%s}".formatted(meta.selectAllClause, meta.table, meta.idFieldColumn.columnName, id) + " LIMIT 1";
+	}
+
+	@Override
+	public String selectByExample(Object entity) {
+		return selectAllByExample(entity) + BaseMapper.LIMIT_1;
+	}
+
+	@Override
+	public String selectAllByExample(Object entity) {
+		EntityMeta meta = getEntityMeta(entity.getClass());
+		String conditionClause = meta.fieldColumnList.stream()
+		                                             .filter(fc -> fc.isNotEmpty(entity))
+		                                             .map(fc -> "`%s` = #{%s}".formatted(fc.columnName, fc.fieldName))
+		                                             .collect(Collectors.joining(" AND "));
+		return "SELECT %s FROM `%s` WHERE %s".formatted(meta.selectAllClause, meta.table, conditionClause);
+	}
+
+	@Override
+	public String deleteAllByExample(Object entity) {
+		return super.deleteAllByExample(entity);
+	}
+}

src/main/java/com/imyeyu/spring/util/Redis.java

@@ -22,6 +22,8 @@ import java.util.function.Consumer;
  * RedisTemplate 功能封装，简化 Redis 操作
  * <p>serializer 为该 RedisTemplate 的键的序列化操作，序列化解析器由 {@link AbstractRedisConfig} 提供
  *
+ * @param <K> 键类型
+ * @param <V> 值类型
  * @author 夜雨
  * @version 2021-11-21 09:58
  */
@@ -30,6 +32,12 @@ public class Redis<K, V> {
 	private final RedisSerializer<K> serializer;
 	private final RedisTemplate<K, V> redis;
 
+	/**
+	 * 创建 Redis 操作封装
+	 *
+	 * @param redis      RedisTemplate 实例
+	 * @param serializer 键序列化器
+	 */
 	public Redis(RedisTemplate<K, V> redis, RedisSerializer<K> serializer) {
 		this.redis = redis;
 		this.serializer = serializer;
@@ -47,9 +55,9 @@ public class Redis<K, V> {
 	/**
 	 * 加锁
 	 *
-	 * @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<K, V> {
 		return lock != null && lock;
 	}
 
+	/**
+	 * 释放锁
+	 *
+	 * @param key 键
+	 */
 	public void releaseLock(K key) {
 		destroy(key);
 	}

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 <T>   数据类型
+	 * @param clazz 数据类型
+	 * @return Redis 序列化器
+	 */
 	public static <T> RedisSerializer<T> gsonSerializer(Class<T> clazz) {
 		return new RedisSerializer<>() {
 

src/main/java/com/imyeyu/spring/util/SQLProvider.java

@@ -1,6 +1,7 @@
 package com.imyeyu.spring.util;
 
 import com.imyeyu.java.TimiJava;
+import com.imyeyu.java.bean.CallbackArgReturn;
 import com.imyeyu.java.bean.timi.TimiCode;
 import com.imyeyu.java.bean.timi.TimiException;
 import com.imyeyu.java.ref.Ref;
@@ -8,6 +9,7 @@ import com.imyeyu.spring.annotation.table.AutoUUID;
 import com.imyeyu.spring.annotation.table.Column;
 import com.imyeyu.spring.annotation.table.DeleteColumn;
 import com.imyeyu.spring.annotation.table.Id;
+import com.imyeyu.spring.annotation.table.PageIgnore;
 import com.imyeyu.spring.annotation.table.Table;
 import com.imyeyu.spring.annotation.table.Transient;
 import com.imyeyu.spring.bean.Page;
@@ -43,6 +45,12 @@ public class SQLProvider {
 	/** 反射缓存 */
 	private static final Map<Class<?>, EntityMeta> ENTITY_META_CACHE = new ConcurrentHashMap<>();
 
+	/**
+	 * 创建 SQL 提供器
+	 */
+	public SQLProvider() {
+	}
+
 	/**
 	 * 根据 Page 对象查询数据列表
 	 *
@@ -50,10 +58,10 @@ public class SQLProvider {
 	 * @param page    分页参数
 	 * @return SQL
 	 */
-	public String listByPage(ProviderContext context, @Param("page") Page<?> page) {
+	public String selectByPage(ProviderContext context, @Param("page") Page<?> page) {
 		EntityMeta meta = getEntityMeta(context);
 		StringBuilder sql = new StringBuilder();
-		sql.append("SELECT %s FROM `%s` WHERE 1 = 1".formatted(meta.selectAllClause, meta.table));
+		sql.append("SELECT %s FROM `%s` WHERE 1 = 1".formatted(meta.selectPageClause, meta.table));
 		if (meta.canDelete) {
 			sql.append(" AND (`deleted_at` IS NULL OR %s < `deleted_at`)".formatted(Time.now()));
 		}
@@ -62,20 +70,24 @@ public class SQLProvider {
 			Object obj = page.getEqualsExample();
 			EntityMeta metaExample = getEntityMeta(obj.getClass());
 			String conditionClause = metaExample.fieldColumnList.stream()
-			                                                    .filter(fc -> fc.isNotNull(obj))
+			                                                    .filter(fc -> fc.isNotEmpty(obj))
 			                                                    .map(fc -> "`%s` = '%s'".formatted(fc.columnName, fc.getAsString(obj)))
 			                                                    .collect(Collectors.joining(" AND "));
-			sql.append(" AND ").append(conditionClause);
+			if (TimiJava.isNotEmpty(conditionClause)) {
+				sql.append(" AND ").append(conditionClause);
+			}
 		}
-		if (TimiJava.isNotEmpty(page.getLikeExample())) {
+		if (TimiJava.isNotEmpty(page.getLikesExample())) {
 			// 模糊查询
-			Object obj = page.getLikeExample();
+			Object obj = page.getLikesExample();
 			EntityMeta metaExample = getEntityMeta(obj.getClass());
 			String conditionClause = metaExample.fieldColumnList.stream()
-			                                                    .filter(fc -> fc.isNotNull(obj))
+			                                                    .filter(fc -> fc.isNotEmpty(obj))
 			                                                    .map(fc -> "`%s` LIKE CONCAT('%%', '%s', '%%')".formatted(fc.columnName, fc.getAsString(obj)))
 			                                                    .collect(Collectors.joining(" OR "));
-			sql.append(" AND (").append(conditionClause).append(')');
+			if (TimiJava.isNotEmpty(conditionClause)) {
+				sql.append(" AND (").append(conditionClause).append(')');
+			}
 		}
 		// 排序
 		if (TimiJava.isNotEmpty(page.getOrderMap())) {
@@ -120,25 +132,35 @@ public class SQLProvider {
 			Object obj = page.getEqualsExample();
 			EntityMeta metaExample = getEntityMeta(obj.getClass());
 			String conditionClause = metaExample.fieldColumnList.stream()
-			                                                    .filter(fc -> fc.isNotNull(obj))
+			                                                    .filter(fc -> fc.isNotEmpty(obj))
 			                                                    .map(fc -> "`%s` = '%s'".formatted(fc.columnName, fc.getAsString(obj)))
 			                                                    .collect(Collectors.joining(" AND "));
-			sql.append(" AND ").append(conditionClause);
+			if (TimiJava.isNotEmpty(conditionClause)) {
+				sql.append(" AND ").append(conditionClause);
+			}
 		}
-		if (TimiJava.isNotEmpty(page.getLikeExample())) {
+		if (TimiJava.isNotEmpty(page.getLikesExample())) {
 			// 模糊查询
-			Object obj = page.getLikeExample();
+			Object obj = page.getLikesExample();
 			EntityMeta metaExample = getEntityMeta(obj.getClass());
 			String conditionClause = metaExample.fieldColumnList.stream()
-			                                                    .filter(fc -> fc.isNotNull(obj))
+			                                                    .filter(fc -> fc.isNotEmpty(obj))
 			                                                    .map(fc -> "`%s` LIKE CONCAT('%%', '%s', '%%')".formatted(fc.columnName, fc.getAsString(obj)))
 			                                                    .collect(Collectors.joining(" OR "));
-			sql.append(" AND (").append(conditionClause).append(')');
+			if (TimiJava.isNotEmpty(conditionClause)) {
+				sql.append(" AND (").append(conditionClause).append(')');
+			}
 		}
 		return sql.toString();
 	}
 
-	public String listAll(ProviderContext context) {
+	/**
+	 * 查询全部数据
+	 *
+	 * @param context 代理器上下文
+	 * @return SQL
+	 */
+	public String selectAll(ProviderContext context) {
 		EntityMeta meta = getEntityMeta(context);
 		StringBuilder sql = new StringBuilder();
 		sql.append("SELECT * FROM %s WHERE 1 = 1".formatted(meta.table));
@@ -152,6 +174,7 @@ public class SQLProvider {
 	 * 插入
 	 * <p><i>不实现 {@link Creatable} 也允许调用是合理的，某些数据属于关联数据，不参与主创建过程</i></p>
 	 *
+	 * @param context 代理器上下文
 	 * @param entity 实体
 	 * @return SQL
 	 */
@@ -216,7 +239,7 @@ public class SQLProvider {
 	public String selectAllByExample(Object entity) {
 		EntityMeta meta = getEntityMeta(entity.getClass());
 		String conditionClause = meta.fieldColumnList.stream()
-		                                             .filter(fc -> fc.isNotNull(entity))
+		                                             .filter(fc -> fc.isNotEmpty(entity))
 		                                             .map(fc -> "`%s` = #{%s}".formatted(fc.columnName, fc.fieldName))
 		                                             .collect(Collectors.joining(" AND "));
 
@@ -289,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));
@@ -300,7 +329,7 @@ public class SQLProvider {
 
 		String delClause = meta.fieldColumnList.stream()
 		                                       .filter(FieldColumn::isNotId)
-											   .filter(fc -> fc.isNotNull(entity))
+											   .filter(fc -> fc.isNotEmpty(entity))
 		                                       .map(fc -> "`%s` = #{%s}".formatted(fc.columnName, fc.fieldName))
 		                                       .collect(Collectors.joining(" AND "));
 		StringBuilder sql = new StringBuilder("UPDATE `%s` SET `%s` = ".formatted(meta.table, deleteColumn.getColumnName()));
@@ -367,6 +396,9 @@ public class SQLProvider {
 		/** 查询字段映射 */
 		final String selectAllClause;
 
+		/** 页面查询字段映射 */
+		final String selectPageClause;
+
 		/** ID 字段 */
 		final FieldColumn idFieldColumn;
 
@@ -385,6 +417,11 @@ public class SQLProvider {
 		/** true 为可销毁（硬删除） */
 		final boolean canDestroy;
 
+		/**
+		 * 创建实体元数据
+		 *
+		 * @param entityClass 实体类型
+		 */
 		public EntityMeta(Class<?> entityClass) {
 			this.entityClass = entityClass;
 
@@ -400,8 +437,6 @@ public class SQLProvider {
 				TimiException.required(this.table, String.format("empty table annotation value for %s entity", entityClass.getName()));
 			}
 			List<Field> allFieldList = Ref.listAllFields(entityClass);
-
-			StringBuilder selectAllClause = new StringBuilder();
 			FieldColumn idFieldColumn = null;
 			List<FieldColumn> fieldColumnList = new ArrayList<>();
 			for (int i = 0; i < allFieldList.size(); i++) {
@@ -414,21 +449,10 @@ public class SQLProvider {
 					TimiException.requiredNull(idFieldColumn, String.format("multi id field for %s entity", entityClass.getName()));
 					idFieldColumn = fieldColumn;
 				}
-				{
-					Column column = field.getAnnotation(Column.class);
-					if (column == null) {
-						selectAllClause.append('`').append(fieldColumn.columnName).append('`');
-						selectAllClause.append(',');
-					} else {
-						// 处理自定义映射列名
-						selectAllClause.append('`').append(column.value()).append('`');
-						selectAllClause.append(" AS `").append(fieldColumn.fieldName).append('`');
-						selectAllClause.append(',');
-					}
-				}
 				fieldColumnList.add(fieldColumn);
 			}
-			this.selectAllClause = selectAllClause.substring(0, selectAllClause.length() - 1);
+			this.selectAllClause = buildSelectClause(fieldColumnList, null);
+			this.selectPageClause = buildSelectClause(fieldColumnList, fc -> !fc.getField().isAnnotationPresent(PageIgnore.class));
 			this.idFieldColumn = idFieldColumn;
 			this.fieldColumnList = List.of(fieldColumnList.toArray(new FieldColumn[0])); // 转为只读
 			canCreate = Creatable.class.isAssignableFrom(entityClass);
@@ -437,38 +461,105 @@ public class SQLProvider {
 			canDestroy = Destroyable.class.isAssignableFrom(entityClass);
 		}
 
+		private String buildSelectClause(List<FieldColumn> fieldColumnList, CallbackArgReturn<FieldColumn, Boolean> callback) {
+			StringBuilder sb = new StringBuilder();
+			for (int i = 0; i < fieldColumnList.size(); i++) {
+				FieldColumn fieldColumn = fieldColumnList.get(i);
+				Field field = fieldColumn.getField();
+				if (callback != null && !callback.handler(fieldColumn)) {
+					continue;
+				}
+				Column column = field.getAnnotation(Column.class);
+				if (column == null) {
+					sb.append('`').append(fieldColumn.columnName).append('`');
+					sb.append(',');
+				} else {
+					// 自定义映射列名
+					sb.append('`').append(column.value()).append('`');
+					sb.append(" AS `").append(fieldColumn.fieldName).append('`');
+					sb.append(',');
+				}
+			}
+			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<FieldColumn> 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;
 		}
@@ -503,6 +594,11 @@ public class SQLProvider {
 
 		final DeleteColumn.Type deleteColumnType;
 
+		/**
+		 * 创建字段映射
+		 *
+		 * @param field 字段
+		 */
 		public FieldColumn(Field field) {
 			this.field = field;
 
@@ -529,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;
@@ -537,10 +639,46 @@ 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));
+			} catch (IllegalAccessException e) {
+				throw new RuntimeException(e);
+			}
+		}
+
+		/**
+		 * 判断字段值是否非空
+		 *
+		 * @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();
@@ -549,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;
 		}

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<PropertySource<?>> sources = new YamlPropertySourceLoader().load(resource.getResource().getFilename(), resource.getResource());