v0.2.0

.gitea/workflows/ci.yml

@@ -1,110 +1,111 @@
 name: CI/CD
 
 on:
-  pull_request:
+    pull_request:
-    branches:
+        branches:
-      - master
+            - master
-    types:
+        types:
-      - closed
+            - closed
 
 jobs:
-  build-deploy:
+    build-deploy:
-    runs-on: act_runner_java
+        runs-on: act_runner_java
-    if: ${{ github.event.pull_request.merged == true }}
+        if: ${{ github.event.pull_request.merged == true }}
-    env:
-      JAVA_HOME: /usr/lib/jvm/java-21-openjdk
-    steps:
-      - name: Checkout code
-        run: |
-          git clone ${{ github.server_url }}/${{ github.repository }}.git .
-          git checkout ${{ github.sha }}
-      - name: Set up environment
-        run: |
-          echo "PR #${{ github.event.number }} merged into master"
-          echo "Source branch: ${{ github.event.pull_request.head.ref }}"
-          echo "Target branch: ${{ github.event.pull_request.base.ref }}"
-      - name: Run tests
-        run: |
-          echo "Running test suite..."
-      - name: Build project
-        run: |
-          mvn -B -DskipTests clean package source:jar javadoc:jar
-      - name: Deploy to Nexus
-        if: success()
-        run: |
-          if [ -z "${{ secrets.NEXUS_USERNAME }}" ] || [ -z "${{ secrets.NEXUS_PASSWORD }}" ]; then
-            echo "Missing secrets.NEXUS_USERNAME or secrets.NEXUS_PASSWORD"
-            exit 1
-          fi
-          mkdir -p ~/.m2
-          cat > ~/.m2/settings.xml <<EOF
-          <settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
-            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 http://maven.apache.org/xsd/settings-1.0.0.xsd">
-            <servers>
-              <server>
-                <id>timi-nexus</id>
-                <username>${{ secrets.NEXUS_USERNAME }}</username>
-                <password>${{ secrets.NEXUS_PASSWORD }}</password>
-              </server>
-            </servers>
-          </settings>
-          EOF
-          version=$(mvn -q -DforceStdout help:evaluate -Dexpression=project.version)
-          artifact_id=$(mvn -q -DforceStdout help:evaluate -Dexpression=project.artifactId)
-          main_jar="target/${artifact_id}-${version}.jar"
-          sources_jar="target/${artifact_id}-${version}-sources.jar"
-          javadoc_jar="target/${artifact_id}-${version}-javadoc.jar"
-          if [ ! -f "$main_jar" ] || [ ! -f "$sources_jar" ] || [ ! -f "$javadoc_jar" ]; then
-            echo "Missing build artifacts in target"
-            exit 1
-          fi
-          mvn -B deploy:deploy-file \
-            -Dfile="$main_jar" \
-            -Dsources="$sources_jar" \
-            -Djavadoc="$javadoc_jar" \
-            -DpomFile="./pom.xml" \
-            -Durl="https://nexus.imyeyu.com/repository/maven-releases/" \
-            -DrepositoryId="timi-nexus" \
-            -Dhttps.protocols=TLSv1.2 \
-            -Djdk.tls.client.protocols=TLSv1.2
-      - name: Create release
-        if: ${{ success() && startsWith(github.event.pull_request.title, 'v') }}
         env:
-          GITEA_TOKEN: ${{ secrets.RUNNER_TOKEN }}
+            JAVA_HOME: /usr/lib/jvm/java-21-openjdk
-          GITEA_SERVER_URL: ${{ github.server_url }}
+        steps:
-          GITEA_REPOSITORY: ${{ github.repository }}
+            - name: Checkout code
-          RELEASE_TAG: ${{ github.event.pull_request.title }}
+              run: |
-          RELEASE_TARGET: ${{ github.sha }}
+                  git clone ${{ github.server_url }}/${{ github.repository }}.git .
-        run: |
+                  git checkout ${{ github.sha }}
-          if [ -z "$GITEA_TOKEN" ]; then
+            - name: Set up environment
-            echo "Missing secrets.RUNNER_TOKEN"
+              run: |
-            exit 1
+                  echo "PR #${{ github.event.number }} merged into master"
-          fi
+                  echo "Source branch: ${{ github.event.pull_request.head.ref }}"
-          api_url="$GITEA_SERVER_URL/api/v1/repos/$GITEA_REPOSITORY/releases"
+                  echo "Target branch: ${{ github.event.pull_request.base.ref }}"
-          payload=$(cat <<EOF
+            - name: Run tests
-          {
+              run: |
-            "tag_name": "$RELEASE_TAG",
+                  echo "Running test suite..."
-            "name": "$RELEASE_TAG",
+            - name: Build project
-            "target_commitish": "$RELEASE_TARGET",
+              run: |
-            "draft": false,
+                  mvn -B -DskipTests clean package source:jar javadoc:jar
-            "prerelease": false
+            - name: Deploy to Nexus
-          }
+              if: success()
-          EOF
+              run: |
-          )
+                  if [ -z "${{ secrets.NEXUS_USERNAME }}" ] || [ -z "${{ secrets.NEXUS_PASSWORD }}" ]; then
-          response=$(curl -sS -X POST "$api_url" \
+                    echo "Missing secrets.NEXUS_USERNAME or secrets.NEXUS_PASSWORD"
-            -H "Authorization: token $GITEA_TOKEN" \
+                    exit 1
-            -H "Content-Type: application/json" \
+                  fi
-            -d "$payload")
+                  mkdir -p ~/.m2
-          release_id=$(echo "$response" | sed -n 's/.*"id":[ ]*\\([0-9][0-9]*\\).*/\\1/p' | head -n 1)
+                  cat > ~/.m2/settings.xml <<EOF
-          if [ -z "$release_id" ]; then
+                  <settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
-            echo "Create release failed: $response"
+                    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-            exit 1
+                    xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 http://maven.apache.org/xsd/settings-1.0.0.xsd">
-          fi
+                    <servers>
-          for asset_path in target/*.jar; do
+                      <server>
-            asset_name=$(basename "$asset_path")
+                        <id>timi-nexus</id>
-            curl -sS -X POST "$api_url/$release_id/assets?name=$asset_name" \
+                        <username>${{ secrets.NEXUS_USERNAME }}</username>
-              -H "Authorization: token $GITEA_TOKEN" \
+                        <password>${{ secrets.NEXUS_PASSWORD }}</password>
-              -H "Content-Type: application/octet-stream" \
+                      </server>
-              --data-binary @"$asset_path"
+                    </servers>
-          done
+                  </settings>
+                  EOF
+                  version=$(mvn -q -DforceStdout help:evaluate -Dexpression=project.version)
+                  artifact_id=$(mvn -q -DforceStdout help:evaluate -Dexpression=project.artifactId)
+                  main_jar="target/${artifact_id}-${version}.jar"
+                  sources_jar="target/${artifact_id}-${version}-sources.jar"
+                  javadoc_jar="target/${artifact_id}-${version}-javadoc.jar"
+                  if [ ! -f "$main_jar" ] || [ ! -f "$sources_jar" ] || [ ! -f "$javadoc_jar" ]; then
+                    echo "Missing build artifacts in target"
+                    exit 1
+                  fi
+                  mvn -B deploy:deploy-file \
+                    -Dfile="$main_jar" \
+                    -Dsources="$sources_jar" \
+                    -Djavadoc="$javadoc_jar" \
+                    -DpomFile="./pom.xml" \
+                    -Durl="https://nexus.imyeyu.com/repository/maven-releases/" \
+                    -DrepositoryId="timi-nexus" \
+                    -Dhttps.protocols=TLSv1.2 \
+                    -Djdk.tls.client.protocols=TLSv1.2
+            - name: Create release
+              if: ${{ success() && startsWith(github.event.pull_request.title, 'v') }}
+              env:
+                  GITEA_TOKEN: ${{ secrets.RUNNER_TOKEN }}
+                  GITEA_SERVER_URL: ${{ github.server_url }}
+                  GITEA_REPOSITORY: ${{ github.repository }}
+                  RELEASE_TAG: ${{ github.event.pull_request.title }}
+                  RELEASE_TARGET: ${{ github.sha }}
+              run: |
+                  if [ -z "$GITEA_TOKEN" ]; then
+                    echo "Missing secrets.RUNNER_TOKEN"
+                    exit 1
+                  fi
+                  api_url="$GITEA_SERVER_URL/api/v1/repos/$GITEA_REPOSITORY/releases"
+                  payload=$(cat <<EOF
+                  {
+                    "tag_name": "$RELEASE_TAG",
+                    "name": "$RELEASE_TAG",
+                    "target_commitish": "$RELEASE_TARGET",
+                    "draft": false,
+                    "prerelease": false
+                  }
+                  EOF
+                  )
+                  response=$(curl -sS -X POST "$api_url" \
+                    -H "Authorization: token $GITEA_TOKEN" \
+                    -H "Content-Type: application/json" \
+                    -d "$payload")
+                  release_id=$(echo "$response" | grep -o '"id":[0-9]*' | head -n 1 | grep -o '[0-9]*')
+                  if [ -z "$release_id" ] || echo "$response" | grep -q '"message"'; then
+                    echo "Create release failed: $response"
+                    exit 1
+                  fi
+                  echo "Release created: id=$release_id"
+                  for asset_path in target/*.jar; do
+                    asset_name=$(basename "$asset_path")
+                    curl -sS -X POST "$api_url/$release_id/assets?name=$asset_name" \
+                      -H "Authorization: token $GITEA_TOKEN" \
+                      -H "Content-Type: application/octet-stream" \
+                      --data-binary @"$asset_path"
+                  done

.serena/.gitignore

@@ -0,0 +1,2 @@
+/cache
+/project.local.yml

.serena/project.yml

@@ -0,0 +1,154 @@
+# the name by which the project can be referenced within Serena
+project_name: "timi-java"
+
+
+# list of languages for which language servers are started; choose from:
+#   al                  bash                clojure             cpp                 csharp
+#   csharp_omnisharp    dart                elixir              elm                 erlang
+#   fortran             fsharp              go                  groovy              haskell
+#   haxe                java                julia               kotlin              lua
+#   markdown
+#   matlab              nix                 pascal              perl                php
+#   php_phpactor        powershell          python              python_jedi         r
+#   rego                ruby                ruby_solargraph     rust                scala
+#   swift               terraform           toml                typescript          typescript_vts
+#   vue                 yaml                zig
+#   (This list may be outdated. For the current list, see values of Language enum here:
+#   https://github.com/oraios/serena/blob/main/src/solidlsp/ls_config.py
+#   For some languages, there are alternative language servers, e.g. csharp_omnisharp, ruby_solargraph.)
+# Note:
+#   - For C, use cpp
+#   - For JavaScript, use typescript
+#   - For Free Pascal/Lazarus, use pascal
+# Special requirements:
+#   Some languages require additional setup/installations.
+#   See here for details: https://oraios.github.io/serena/01-about/020_programming-languages.html#language-servers
+# When using multiple languages, the first language server that supports a given file will be used for that file.
+# The first language is the default language and the respective language server will be used as a fallback.
+# Note that when using the JetBrains backend, language servers are not used and this list is correspondingly ignored.
+languages:
+- java
+
+# the encoding used by text files in the project
+# For a list of possible encodings, see https://docs.python.org/3.11/library/codecs.html#standard-encodings
+encoding: "utf-8"
+
+# line ending convention to use when writing source files.
+# Possible values: unset (use global setting), "lf", "crlf", or "native" (platform default)
+# This does not affect Serena's own files (e.g. memories and configuration files), which always use native line endings.
+line_ending:
+
+# The language backend to use for this project.
+# If not set, the global setting from serena_config.yml is used.
+# Valid values: LSP, JetBrains
+# Note: the backend is fixed at startup. If a project with a different backend
+# is activated post-init, an error will be returned.
+language_backend:
+
+# whether to use project's .gitignore files to ignore files
+ignore_all_files_in_gitignore: true
+
+# advanced configuration option allowing to configure language server-specific options.
+# Maps the language key to the options.
+# Have a look at the docstring of the constructors of the LS implementations within solidlsp (e.g., for C# or PHP) to see which options are available.
+# No documentation on options means no options are available.
+ls_specific_settings: {}
+
+# list of additional paths to ignore in this project.
+# Same syntax as gitignore, so you can use * and **.
+# Note: global ignored_paths from serena_config.yml are also applied additively.
+ignored_paths: []
+
+# whether the project is in read-only mode
+# If set to true, all editing tools will be disabled and attempts to use them will result in an error
+# Added on 2025-04-18
+read_only: false
+
+# list of tool names to exclude.
+# This extends the existing exclusions (e.g. from the global configuration)
+#
+# Below is the complete list of tools for convenience.
+# To make sure you have the latest list of tools, and to view their descriptions, 
+# execute `uv run scripts/print_tool_overview.py`.
+#
+#  * `activate_project`: Activates a project based on the project name or path.
+#  * `check_onboarding_performed`: Checks whether project onboarding was already performed.
+#  * `create_text_file`: Creates/overwrites a file in the project directory.
+#  * `delete_memory`: Delete a memory file. Should only happen if a user asks for it explicitly,
+#       for example by saying that the information retrieved from a memory file is no longer correct
+#       or no longer relevant for the project.
+#  * `edit_memory`: Replaces content matching a regular expression in a memory.
+#  * `execute_shell_command`: Executes a shell command.
+#  * `find_file`: Finds files in the given relative paths
+#  * `find_referencing_symbols`: Finds symbols that reference the given symbol using the language server backend
+#  * `find_symbol`: Performs a global (or local) search using the language server backend.
+#  * `get_current_config`: Prints the current configuration of the agent, including the active and available projects, tools, contexts, and modes.
+#  * `get_symbols_overview`: Gets an overview of the top-level symbols defined in a given file.
+#  * `initial_instructions`: Provides instructions Serena usage (i.e. the 'Serena Instructions Manual')
+#       for clients that do not read the initial instructions when the MCP server is connected.
+#  * `insert_after_symbol`: Inserts content after the end of the definition of a given symbol.
+#  * `insert_before_symbol`: Inserts content before the beginning of the definition of a given symbol.
+#  * `list_dir`: Lists files and directories in the given directory (optionally with recursion).
+#  * `list_memories`: List available memories. Any memory can be read using the `read_memory` tool.
+#  * `onboarding`: Performs onboarding (identifying the project structure and essential tasks, e.g. for testing or building).
+#  * `read_file`: Reads a file within the project directory.
+#  * `read_memory`: Read the content of a memory file. This tool should only be used if the information
+#       is relevant to the current task. You can infer whether the information
+#       is relevant from the memory file name.
+#       You should not read the same memory file multiple times in the same conversation.
+#  * `rename_memory`: Renames or moves a memory. Moving between project and global scope is supported
+#       (e.g., renaming "global/foo" to "bar" moves it from global to project scope).
+#  * `rename_symbol`: Renames a symbol throughout the codebase using language server refactoring capabilities.
+#       For JB, we use a separate tool.
+#  * `replace_content`: Replaces content in a file (optionally using regular expressions).
+#  * `replace_symbol_body`: Replaces the full definition of a symbol using the language server backend.
+#  * `safe_delete_symbol`:
+#  * `search_for_pattern`: Performs a search for a pattern in the project.
+#  * `write_memory`: Write some information (utf-8-encoded) about this project that can be useful for future tasks to a memory in md format.
+#       The memory name should be meaningful.
+excluded_tools: []
+
+# list of tools to include that would otherwise be disabled (particularly optional tools that are disabled by default).
+# This extends the existing inclusions (e.g. from the global configuration).
+included_optional_tools: []
+
+# fixed set of tools to use as the base tool set (if non-empty), replacing Serena's default set of tools.
+# This cannot be combined with non-empty excluded_tools or included_optional_tools.
+fixed_tools: []
+
+# list of mode names to that are always to be included in the set of active modes
+# The full set of modes to be activated is base_modes + default_modes.
+# If the setting is undefined, the base_modes from the global configuration (serena_config.yml) apply.
+# Otherwise, this setting overrides the global configuration.
+# Set this to [] to disable base modes for this project.
+# Set this to a list of mode names to always include the respective modes for this project.
+base_modes:
+
+# list of mode names that are to be activated by default.
+# The full set of modes to be activated is base_modes + default_modes.
+# If the setting is undefined, the default_modes from the global configuration (serena_config.yml) apply.
+# Otherwise, this overrides the setting from the global configuration (serena_config.yml).
+# This setting can, in turn, be overridden by CLI parameters (--mode).
+default_modes:
+
+# initial prompt for the project. It will always be given to the LLM upon activating the project
+# (contrary to the memories, which are loaded on demand).
+initial_prompt: ""
+
+# time budget (seconds) per tool call for the retrieval of additional symbol information
+# such as docstrings or parameter information.
+# This overrides the corresponding setting in the global configuration; see the documentation there.
+# If null or missing, use the setting from the global configuration.
+symbol_info_budget:
+
+# list of regex patterns which, when matched, mark a memory entry as read‑only.
+# Extends the list from the global configuration, merging the two lists.
+read_only_memory_patterns: []
+
+# list of regex patterns for memories to completely ignore.
+# Matching memories will not appear in list_memories or activate_project output
+# and cannot be accessed via read_memory or write_memory.
+# To access ignored memory files, use the read_file tool on the raw file path.
+# Extends the list from the global configuration, merging the two lists.
+# Example: ["_archive/.*", "_episodes/.*"]
+ignored_memory_patterns: []

pom.xml

@@ -6,14 +6,14 @@
 
 	<groupId>com.imyeyu.java</groupId>
 	<artifactId>timi-java</artifactId>
-	<version>0.0.2</version>
+	<version>0.2.0</version>
 	<packaging>jar</packaging>
 
 	<properties>
+		<maven.test.skip>true</maven.test.skip>
 		<maven.compiler.source>21</maven.compiler.source>
 		<maven.compiler.target>21</maven.compiler.target>
 		<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
-		<maven.test.skip>true</maven.test.skip>
 	</properties>
 
 	<build>
@@ -28,10 +28,42 @@
 				<artifactId>maven-source-plugin</artifactId>
 				<version>3.3.1</version>
 			</plugin>
+			<plugin>
+				<groupId>org.projectlombok</groupId>
+				<artifactId>lombok-maven-plugin</artifactId>
+				<version>1.18.20.0</version>
+				<configuration>
+					<sourceDirectory>${project.basedir}/src/main/java</sourceDirectory>
+					<outputDirectory>${project.build.directory}/delombok</outputDirectory>
+					<addOutputDirectory>false</addOutputDirectory>
+					<encoding>UTF-8</encoding>
+				</configuration>
+				<executions>
+					<execution>
+						<phase>generate-sources</phase>
+						<goals>
+							<goal>delombok</goal>
+						</goals>
+					</execution>
+				</executions>
+				<dependencies>
+					<dependency>
+						<groupId>org.projectlombok</groupId>
+						<artifactId>lombok</artifactId>
+						<version>1.18.46</version>
+					</dependency>
+				</dependencies>
+			</plugin>
 			<plugin>
 				<groupId>org.apache.maven.plugins</groupId>
 				<artifactId>maven-javadoc-plugin</artifactId>
 				<version>3.11.2</version>
+				<configuration>
+					<sourcepath>${project.build.directory}/delombok</sourcepath>
+					<encoding>UTF-8</encoding>
+					<charset>UTF-8</charset>
+					<docencoding>UTF-8</docencoding>
+				</configuration>
 			</plugin>
 		</plugins>
 	</build>
@@ -57,6 +89,11 @@
 	</repositories>
 
 	<dependencies>
+		<dependency>
+			<groupId>org.projectlombok</groupId>
+			<artifactId>lombok</artifactId>
+			<version>1.18.46</version>
+		</dependency>
 		<dependency>
 			<groupId>org.junit.jupiter</groupId>
 			<artifactId>junit-jupiter</artifactId>

src/main/java/com/imyeyu/java/TimiJava.java

@@ -2,17 +2,22 @@ package com.imyeyu.java;
 
 import java.io.PrintWriter;
 import java.io.StringWriter;
+import java.util.Arrays;
 import java.util.Collection;
 import java.util.Collections;
+import java.util.List;
 import java.util.Map;
+import java.util.Objects;
 
 /**
+ * 通用工具
  *
  * @author 夜雨
  * @since 2021-02-13 11:39
  */
 public interface TimiJava {
 
+	/** 全 0 UUID */
 	String ZERO_UUID = "00000000-0000-0000-0000-000000000000";
 
 	/**
@@ -69,42 +74,126 @@ public interface TimiJava {
 		return !isEmpty(object);
 	}
 
+	static boolean hasEmpty(Object... objects) {
+		for (Object object : objects) {
+			if (isEmpty(object)) {
+				return true;
+			}
+		}
+		return false;
+	}
+
+	static boolean allEmpty(Object... objects) {
+		for (Object object : objects) {
+			if (isNotEmpty(object)) {
+				return false;
+			}
+		}
+		return true;
+	}
+
+	static boolean allNotEmpty(Object... objects) {
+		for (Object object : objects) {
+			if (isEmpty(object)) {
+				return false;
+			}
+		}
+		return true;
+	}
+	static <T> T nullIfEmpty(T object) {
+		if (isEmpty(object)) {
+			return null;
+		}
+		return object;
+	}
+
+	/**
+	 * 为空时取默认值
+	 *
+	 * @param obj        判空对象
+	 * @param defaultObj 默认对象
+	 * @return 最终值
+	 * @param <T> 对象类型
+	 */
 	static <T> T defaultIfNull(T obj, T defaultObj) {
-		return firstNotNull(obj, defaultObj);
+		return obj != null ? obj : defaultObj;
 	}
 
+	/**
+	 * 为空时取默认值
+	 *
+	 * @param obj        判空对象
+	 * @param defaultObj 默认对象
+	 * @return 最终值
+	 * @param <T> 对象类型
+	 */
 	static <T> T defaultIfEmpty(T obj, T defaultObj) {
-		return firstNotEmpty(obj, defaultObj);
+		if (isEmpty(obj)) {
+			return defaultObj;
+		}
+		return obj;
 	}
 
+	/**
+	 * 取第一个非空对象
+	 *
+	 * @param objects 对象列表
+	 * @return 最终值
+	 * @param <T> 对象类型
+	 */
 	@SafeVarargs
 	static <T> T firstNotNull(T... objects) {
-		for (int i = 0; i < objects.length; i++) {
+		for (T object : objects) {
-			if (objects[i] != null) {
+			if (object != null) {
-				return objects[i];
+				return object;
 			}
 		}
 		return null;
 	}
 
+	/**
+	 * 取第一个非空对象
+	 *
+	 * @param objects 对象列表
+	 * @return 最终值
+	 * @param <T> 对象类型
+	 */
 	@SafeVarargs
 	static <T> T firstNotEmpty(T... objects) {
-		for (int i = 0; i < objects.length; i++) {
+		for (T object : objects) {
-			if (TimiJava.isNotEmpty(objects[i])) {
+			if (TimiJava.isNotEmpty(object)) {
-				return objects[i];
+				return object;
 			}
 		}
 		return null;
 	}
 
-	static String toString(Exception e) {
+	/**
+	 * 打印异常
+	 *
+	 * @param e 异常
+	 * @return 异常文本
+	 */
+	static String serializeThrowable(Throwable e) {
 		StringWriter sw = new StringWriter();
 		PrintWriter pw = new PrintWriter(sw);
 		e.printStackTrace(pw);
 		return sw.toString();
 	}
 
+	/**
+	 * 空安全迭代器，使 for 迭代可以入参为空
+	 *
+	 * @param iterable 可迭代对象
+	 * @return 安全迭代对象
+	 * @param <T> 迭代对象类型
+	 */
 	static <T> Iterable<T> safeIterable(Iterable<T> iterable) {
 		return defaultIfNull(iterable, Collections::emptyIterator);
 	}
+
+	@SafeVarargs
+	static <T> List<T> ofList(T... objs) {
+		return objs == null ? List.of() : Arrays.stream(objs).filter(Objects::nonNull).toList();
+	}
 }

src/main/java/com/imyeyu/java/bean/ActionError.java

@@ -0,0 +1,62 @@
+package com.imyeyu.java.bean;
+
+import lombok.Getter;
+
+import java.util.Map;
+
+/**
+ * 致命错误
+ *
+ * @author 夜雨
+ * @since 2023-04-27 15:55
+ */
+@Getter
+public class ActionError extends AssertionError {
+
+	/** 代码 */
+	protected final ResultCode code;
+
+	/** 消息代码 */
+	protected final String messageCode;
+
+	/** 消息插值参数 */
+	protected final transient Map<String, Object> messageArgs;
+
+	/** @param code 代码 */
+	public ActionError(ResultCode code) {
+		this(code, code.toString());
+	}
+
+	/**
+	 * 构造器
+	 *
+	 * @param code 代码
+	 * @param messageCode 消息代码
+	 */
+	public ActionError(ResultCode code, String messageCode) {
+		this(code, messageCode, null);
+	}
+
+	/**
+	 * 构造器
+	 *
+	 * @param code 代码
+	 * @param messageCode 消息代码
+	 * @param messageArgs 消息插值参数
+	 */
+	public ActionError(ResultCode code, String messageCode, Map<String, Object> messageArgs) {
+		super(messageCode);
+		this.code = code;
+		this.messageCode = messageCode;
+		this.messageArgs = messageArgs;
+	}
+
+	/**
+	 * 转为通用响应
+	 *
+	 * @return 响应
+	 */
+	public Response<?> toResponse() {
+		return new Response<>(code).messageCode(messageCode, messageArgs);
+	}
+}

src/main/java/com/imyeyu/java/bean/ActionException.java

@@ -0,0 +1,133 @@
+package com.imyeyu.java.bean;
+
+import com.imyeyu.java.TimiJava;
+import lombok.Getter;
+
+import java.util.Map;
+
+/**
+ * 通用运行时异常，附加通用代码和消息代码
+ *
+ * @author 夜雨
+ * @since 2021-05-20 15:18
+ */
+@Getter
+public class ActionException extends RuntimeException {
+
+	/** 代码 */
+	protected final ResultCode code;
+
+	/** 消息代码 */
+	protected final String messageCode;
+
+	/** 消息插值参数 */
+	protected final transient Map<String, Object> messageArgs;
+
+	/** @param code 代码 */
+	public ActionException(ResultCode code) {
+		this(code, code.toString());
+	}
+
+	/**
+	 * 构造器
+	 *
+	 * @param code 代码
+	 * @param messageCode 消息代码
+	 */
+	public ActionException(ResultCode code, String messageCode) {
+		this(code, messageCode, (Map<String, Object>) null);
+	}
+
+	/**
+	 * 构造器
+	 *
+	 * @param code 代码
+	 * @param messageCode 消息代码
+	 * @param messageArgs 消息插值参数
+	 */
+	public ActionException(ResultCode code, String messageCode, Map<String, Object> messageArgs) {
+		super(messageCode);
+		this.code = code;
+		this.messageCode = messageCode;
+		this.messageArgs = messageArgs;
+	}
+
+	/**
+	 * 构造器
+	 *
+	 * @param code 代码
+	 * @param messageCode 消息代码
+	 * @param e 异常
+	 */
+	public ActionException(ResultCode code, String messageCode, Throwable e) {
+		super(messageCode, e);
+		this.code = code;
+		this.messageCode = messageCode;
+		this.messageArgs = null;
+	}
+
+	/**
+	 * 转为通用响应
+	 *
+	 * @return 响应
+	 */
+	public Response<?> toResponse() {
+		return new Response<>(code).messageCode(messageCode, messageArgs);
+	}
+
+	public static <T> T required(T t, String messageCode) {
+		if (TimiJava.isEmpty(t)) {
+			throw new ActionException(ResultCode.ARG_MISS, messageCode);
+		}
+		return t;
+	}
+
+	public static <T> T required(T t, String messageCode, Map<String, Object> messageArgs) {
+		if (TimiJava.isEmpty(t)) {
+			throw new ActionException(ResultCode.ARG_MISS, messageCode, messageArgs);
+		}
+		return t;
+	}
+
+	public static <T> void requiredNull(T t, String messageCode) throws ActionException {
+		if (t != null) {
+			throw new ActionException(ResultCode.ERROR, messageCode);
+		}
+	}
+
+	public static <T> void requiredNull(T t, String messageCode, Map<String, Object> messageArgs) throws ActionException {
+		if (t != null) {
+			throw new ActionException(ResultCode.ERROR, messageCode, messageArgs);
+		}
+	}
+
+	public static void requiredTrue(boolean bool, String messageCode) throws ActionException {
+		if (bool) {
+			return;
+		}
+		throw new ActionException(ResultCode.ERROR, messageCode);
+	}
+
+	public static void requiredTrue(boolean bool, String messageCode, Map<String, Object> messageArgs) throws ActionException {
+		if (bool) {
+			return;
+		}
+		throw new ActionException(ResultCode.ERROR, messageCode, messageArgs);
+	}
+
+	public static void requiredTrue(CallbackReturn<Boolean> callback, String messageCode) throws ActionException {
+		ActionException.required(callback, "not found callback");
+		if (callback.handler()) {
+			return;
+		}
+		throw new ActionException(ResultCode.ERROR, messageCode);
+	}
+
+	public static void requiredTrue(CallbackReturn<Boolean> callback, String messageCode, Map<String, Object> messageArgs) throws ActionException {
+		ActionException.required(callback, "not found callback");
+		if (callback.handler()) {
+			return;
+		}
+		throw new ActionException(ResultCode.ERROR, messageCode, messageArgs);
+	}
+}

src/main/java/com/imyeyu/java/bean/BasePage.java

@@ -1,9 +1,18 @@
 package com.imyeyu.java.bean;
 
+import lombok.AllArgsConstructor;
+import lombok.Data;
+import lombok.NoArgsConstructor;
+
 /**
+ * 分页
+ *
  * @author 夜雨
  * @since 2025-07-25 11:04
  */
+@Data
+@NoArgsConstructor
+@AllArgsConstructor
 public class BasePage {
 
 	/** 下标 */
@@ -12,35 +21,31 @@ public class BasePage {
 	/** 数据量 */
 	protected long size = 16;
 
-	public BasePage() {
+	/** 上一页 */
-	}
-
-	public BasePage(int index, long size) {
-		this.index = index;
-		this.size = size;
-	}
-
 	public void prev() {
 		index--;
 	}
 
+	/** 下一页 */
 	public void next() {
 		index++;
 	}
 
-	public int getIndex() {
+	/**
-		return index;
+	 * 获取偏移量
+	 *
+	 * @return 偏移量
+	 */
+	public long getOffset() {
+		return (long) index * size;
 	}
 
-	public void setIndex(int index) {
+	/**
-		this.index = index;
+	 * 获取限制数量
-	}
+	 *
-
+	 * @return 限制数量
-	public long getSize() {
+	 */
+	public long getLimit() {
 		return size;
 	}
-
-	public void setSize(long size) {
-		this.size = size;
-	}
 }

src/main/java/com/imyeyu/java/bean/BasePageResult.java

@@ -1,13 +1,17 @@
 package com.imyeyu.java.bean;
 
 import com.imyeyu.java.TimiJava;
+import lombok.Data;
 
 import java.util.List;
 
 /**
+ * 分页结果
+ *
  * @author 夜雨
  * @since 2025-07-25 11:04
  */
+@Data
 public class BasePageResult<T> {
 
 	/** 总数据量 */
@@ -16,6 +20,7 @@ public class BasePageResult<T> {
 	/** 总页数 */
 	protected int pages;
 
+	/** 分页数据列表 */
 	protected List<T> list;
 
 	/**
@@ -36,15 +41,6 @@ public class BasePageResult<T> {
 		return !isEmpty();
 	}
 
-	/**
-	 * 获取总数据量
-	 *
-	 * @return 总数据量
-	 */
-	public long getTotal() {
-		return total;
-	}
-
 	/**
 	 * 设置总数据量
 	 *
@@ -57,18 +53,15 @@ public class BasePageResult<T> {
 		}
 	}
 
-	public List<T> getList() {
+	/**
-		return list;
+	 * 设置分页数据列表
-	}
+	 *
-
+	 * @param list 分页数据列表
+	 */
 	public void setList(List<T> list) {
 		this.list = list;
 		if (TimiJava.isNotEmpty(list)) {
 			pages = (int) Math.ceil(1D * total / list.size());
 		}
 	}
-
-	public int getPages() {
-		return pages;
-	}
 }

src/main/java/com/imyeyu/java/bean/Callback.java

@@ -11,6 +11,11 @@ public interface Callback {
 	/** 执行程序 */
 	void handler() throws RuntimeException;
 
+	/**
+	 * 非空时执行回调
+	 *
+	 * @param callback 回调
+	 */
 	static void handle(Callback callback) {
 		if (callback == null) {
 			return;

src/main/java/com/imyeyu/java/bean/CallbackArg.java

@@ -21,7 +21,9 @@ public interface CallbackArg<T> {
 	/**
 	 * 非空时执行回调
 	 *
+	 * @param t 参数
 	 * @param callbackArg 回调
+	 * @param <T> 入参类型
 	 */
 	static <T> void handle(T t, CallbackArg<T> callbackArg) {
 		if (callbackArg == null) {

src/main/java/com/imyeyu/java/bean/CallbackArgReturn.java

@@ -23,7 +23,10 @@ public interface CallbackArgReturn<T, R> {
 	/**
 	 * 非空时执行回调
 	 *
+	 * @param t 参数
 	 * @param callbackArgReturn 回调
+	 * @param <T> 入参类型
+	 * @param <R> 返回类型
 	 */
 	static <T, R> R handle(T t, CallbackArgReturn<T, R> callbackArgReturn) {
 		if (callbackArgReturn == null) {

src/main/java/com/imyeyu/java/bean/CallbackReturn.java

@@ -22,6 +22,7 @@ public interface CallbackReturn<R> {
 	 * 非空时执行回调
 	 *
 	 * @param callbackReturn 回调
+	 * @param <R> 返回类型
 	 */
 	static <R> R handle(CallbackReturn<R> callbackReturn) {
 		if (callbackReturn == null) {

src/main/java/com/imyeyu/java/bean/Language.java

@@ -1,134 +0,0 @@
-package com.imyeyu.java.bean;
-
-import com.imyeyu.java.ref.Ref;
-
-/**
- * 多语言
- *
- * @author 夜雨
- * @since 2022-02-23 11:25
- */
-public class Language {
-
-	/**
-	 * @author 夜雨
-	 * @since 2025-12-05 14:31
-	 */
-	public enum Enum {
-
-		/** 英语 */
-		en_US,
-
-		/** 简中 */
-		zh_CN,
-
-		/** 繁中 */
-		zh_TW,
-
-		/** 日语 */
-		ja_JP,
-
-		/** 韩语 */
-		ko_KR,
-
-		/** 俄语 */
-		ru_RU,
-
-		/** 德语 */
-		de_DE;
-	}
-
-	protected String key;
-
-	protected String zhCN;
-
-	protected String zhTW;
-
-	protected String enUS;
-
-	protected String ruRU;
-
-	protected String koKR;
-
-	protected String jaJP;
-
-	protected String deDE;
-
-	/**
-	 * 获取指定语言值
-	 *
-	 * @param language 指定语言
-	 * @return 值
-	 */
-	public String getValue(Enum language) {
-		try {
-			return Ref.getFieldValue(this, language.toString().replace("_", ""), String.class);
-		} catch (IllegalAccessException e) {
-			throw new RuntimeException(e);
-		}
-	}
-
-	public String getKey() {
-		return key;
-	}
-
-	public void setKey(String key) {
-		this.key = key;
-	}
-
-	public String getZhCN() {
-		return zhCN;
-	}
-
-	public void setZhCN(String zhCN) {
-		this.zhCN = zhCN;
-	}
-
-	public String getZhTW() {
-		return zhTW;
-	}
-
-	public void setZhTW(String zhTW) {
-		this.zhTW = zhTW;
-	}
-
-	public String getEnUS() {
-		return enUS;
-	}
-
-	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;
-	}
-}

src/main/java/com/imyeyu/java/bean/LanguageMapping.java

@@ -1,20 +0,0 @@
-package com.imyeyu.java.bean;
-
-import java.util.Map;
-
-/**
- * @author 夜雨
- * @since 2024-04-03 11:27
- */
-public interface LanguageMapping {
-
-	void add(String key, String value);
-
-	boolean has(String key);
-
-	String text(String key);
-
-	String text(String key, String def);
-
-	String textArgs(String key, Map<String, Object> argsMap);
-}

src/main/java/com/imyeyu/java/bean/LanguageMsgMapping.java

@@ -1,28 +0,0 @@
-package com.imyeyu.java.bean;
-
-import java.util.Map;
-
-/**
- * @author 夜雨
- * @since 2024-04-01 10:28
- */
-public interface LanguageMsgMapping<T> {
-
-	T msg(String msg);
-
-	T msgKey(String msgKey);
-
-	T msgKey(String msgKey, Map<String, Object> msgArgs);
-
-	void setMsg(String msg);
-
-	String getMsg();
-
-	void setMsgKey(String msgKey);
-
-	void setMsgKey(String msgKey, Map<String, Object> msgArgs);
-
-	String getMsgKey();
-
-	Map<String, Object> getMsgArgs();
-}

src/main/java/com/imyeyu/java/bean/Response.java

@@ -0,0 +1,135 @@
+package com.imyeyu.java.bean;
+
+import lombok.Getter;
+import lombok.NoArgsConstructor;
+import lombok.Setter;
+
+import java.io.Serializable;
+import java.util.Map;
+
+/**
+ * 通用接口返回对象
+ *
+ * @param <T> 数据类型
+ *
+ * @author 夜雨
+ * @since 2021-07-01 20:18
+ */
+@NoArgsConstructor
+public class Response<T> implements Serializable {
+
+	/** 响应代码 */
+	@Setter
+	@Getter
+	protected Integer code;
+
+	/** 响应消息 */
+	@Getter
+	@Setter
+	protected String message;
+
+	/** 响应消息代码 */
+	@Getter
+	@Setter
+	protected String messageCode;
+
+	/** 消息插值参数 */
+	@Getter
+	@Setter
+	protected transient Map<String, Object> messageArgs;
+
+	/** 数据体 */
+	@Setter
+	@Getter
+	protected T data;
+
+	/**
+	 * 构造器
+	 *
+	 * @param code 代码
+	 */
+	public Response(ResultCode code) {
+		this(code, null);
+	}
+
+	/**
+	 * 构造器
+	 *
+	 * @param code 代码
+	 * @param data 数据体
+	 */
+	public Response(ResultCode code, T data) {
+		this(code, data, null);
+	}
+
+	/**
+	 * 构造器
+	 *
+	 * @param code 代码
+	 * @param data 数据体
+	 * @param message 响应消息
+	 */
+	public Response(ResultCode code, T data, String message) {
+		this.code = code.getValue();
+		this.data = data;
+		this.message = message;
+	}
+
+	/** @return true 为成功，code 为 20000 段 */
+	public boolean isSuccess() {
+		return code != null && code <= 30000;
+	}
+
+	/** @return true 为失败，isSuccess 取反 */
+	public boolean isFail() {
+		return !isSuccess();
+	}
+
+	/**
+	 * 转为通用异常
+	 *
+	 * @return 异常
+	 */
+	public ActionException toException() {
+		ResultCode code = ResultCode.fromCode(this.code);
+		if (code == null) {
+			throw new NullPointerException("unknow timi code: " + this.code);
+		}
+		return new ActionException(code, messageCode == null ? message : messageCode, messageArgs);
+	}
+
+	/**
+	 * 设置响应消息
+	 *
+	 * @param message 响应消息
+	 * @return 本对象
+	 */
+	public Response<T> message(String message) {
+		this.message = message;
+		return this;
+	}
+
+	/**
+	 * 设置响应消息代码
+	 *
+	 * @param messageCode 响应消息代码
+	 * @return 本对象
+	 */
+	public Response<T> messageCode(String messageCode) {
+		this.messageCode = messageCode;
+		return this;
+	}
+
+	/**
+	 * 设置响应消息代码和插值参数
+	 *
+	 * @param messageCode 响应消息代码
+	 * @param messageArgs 插值参数
+	 * @return 本对象
+	 */
+	public Response<T> messageCode(String messageCode, Map<String, Object> messageArgs) {
+		this.messageCode = messageCode;
+		this.messageArgs = messageArgs;
+		return this;
+	}
+}

src/main/java/com/imyeyu/java/bean/ResultCode.java

@@ -1,4 +1,6 @@
-package com.imyeyu.java.bean.timi;
+package com.imyeyu.java.bean;
+
+import lombok.Getter;
 
 /**
  * 通用代码（基于 HTTP 代码扩展）
@@ -6,7 +8,8 @@ package com.imyeyu.java.bean.timi;
  * @author 夜雨
  * @since 2021-05-21 14:32
  */
-public enum TimiCode {
+@Getter
+public enum ResultCode {
 
 	// ---------- 200 正常 ----------
 
@@ -74,9 +77,10 @@ public enum TimiCode {
 	/** 服务繁忙 */
 	ERROR_SERVICE_BUSY(50300);
 
+	/** 代码 */
 	final Integer value;
 
-	TimiCode(Integer value) {
+	ResultCode(Integer value) {
 		this.value = value;
 	}
 
@@ -85,7 +89,7 @@ public enum TimiCode {
 	 *
 	 * @return 异常
 	 */
-	public TimiException toException() {
+	public ActionException toException() {
 		return toException(toString());
 	}
 
@@ -95,8 +99,8 @@ public enum TimiCode {
 	 * @param msg 异常消息
 	 * @return 异常
 	 */
-	public TimiException toException(String msg) {
+	public ActionException toException(String msg) {
-		return new TimiException(this, msg);
+		return new ActionException(this, msg);
 	}
 
 	/**
@@ -104,17 +108,8 @@ public enum TimiCode {
 	 *
 	 * @return 返回对象
 	 */
-	public TimiResponse<?> toResponse() {
+	public Response<?> toResponse() {
-		return new TimiResponse<>(this).msg(toString());
+		return new Response<>(this).message(toString());
-	}
-
-	/**
-	 * 获取代码
-	 *
-	 * @return 代码
-	 */
-	public Integer getValue() {
-		return value;
 	}
 
 	/**
@@ -123,11 +118,11 @@ public enum TimiCode {
 	 * @param code 代码
 	 * @return 对象
 	 */
-	public static TimiCode fromCode(int code) {
+	public static ResultCode fromCode(int code) {
-		TimiCode[] codes = values();
+		ResultCode[] codes = values();
-		for (int i = 0; i < codes.length; i++) {
+		for (ResultCode resultCode : codes) {
-			if (codes[i].getValue() == code) {
+			if (resultCode.getValue() == code) {
-				return codes[i];
+				return resultCode;
 			}
 		}
 		return null;

src/main/java/com/imyeyu/java/bean/timi/TimiError.java

@@ -1,98 +0,0 @@
-package com.imyeyu.java.bean.timi;
-
-import com.imyeyu.java.bean.LanguageMsgMapping;
-
-import java.util.Map;
-
-/**
- * 致命错误
- *
- * @author 夜雨
- * @since 2023-04-27 15:55
- */
-public class TimiError extends AssertionError implements LanguageMsgMapping<TimiError> {
-
-	/** 代码 */
-	protected final TimiCode code;
-
-	protected transient String msgKey;
-
-	protected transient Map<String, Object> msgArgs;
-
-	/** @param code 代码 */
-	public TimiError(TimiCode code) {
-		this.code = code;
-	}
-
-	/**
-	 * 构造器
-	 *
-	 * @param code 代码
-	 * @param msg  消息
-	 */
-	public TimiError(TimiCode code, String msg) {
-		super(msg);
-		this.code = code;
-	}
-
-	/**
-	 * 获取代码
-	 *
-	 * @return 代码
-	 */
-	public TimiCode getCode() {
-		return code;
-	}
-
-	public TimiResponse<?> toResponse() {
-		return new TimiResponse<>(code).msg(getMessage()).msgKey(msgKey, msgArgs);
-	}
-
-	@Override
-	public TimiError msg(String msg) {
-		throw new UnsupportedOperationException("unsupported to change message");
-	}
-
-	@Override
-	public TimiError msgKey(String msgKey) {
-		setMsgKey(msgKey);
-		return this;
-	}
-
-	@Override
-	public TimiError msgKey(String msgKey, Map<String, Object> msgArgs) {
-		setMsgKey(msgKey, msgArgs);
-		return this;
-	}
-
-	@Override
-	public void setMsg(String msg) {
-		throw new UnsupportedOperationException("unsupported to change message");
-	}
-
-	@Override
-	public String getMsg() {
-		return getMessage();
-	}
-
-	@Override
-	public void setMsgKey(String msgKey) {
-		this.msgKey = msgKey;
-	}
-
-	@Override
-	public String getMsgKey() {
-		return msgKey;
-	}
-
-	@Override
-	public void setMsgKey(String msgKey, Map<String, Object> msgArgs) {
-		this.msgKey = msgKey;
-		this.msgArgs = msgArgs;
-	}
-
-	@Override
-	public Map<String, Object> getMsgArgs() {
-		return msgArgs;
-	}
-}

src/main/java/com/imyeyu/java/bean/timi/TimiException.java

@@ -1,167 +0,0 @@
-package com.imyeyu.java.bean.timi;
-
-import com.imyeyu.java.TimiJava;
-import com.imyeyu.java.bean.CallbackReturn;
-import com.imyeyu.java.bean.LanguageMsgMapping;
-
-import java.util.Map;
-
-/**
- * 通用运行时异常，附加通用代码
- *
- * @author 夜雨
- * @since 2021-05-20 15:18
- */
-public class TimiException extends RuntimeException implements LanguageMsgMapping<TimiException> {
-
-	/** 代码 */
-	protected final TimiCode code;
-
-	protected transient String msgKey;
-
-	protected transient Map<String, Object> msgArgs;
-
-	/** @param code 代码 */
-	public TimiException(TimiCode code) {
-		this.code = code;
-	}
-
-	/**
-	 * 构造器
-	 *
-	 * @param code 代码
-	 * @param msg  消息
-	 */
-	public TimiException(TimiCode code, String msg) {
-		super(msg);
-		this.code = code;
-	}
-
-	/**
-	 * 构造器
-	 *
-	 * @param code 代码
-	 * @param msg  消息
-	 */
-	public TimiException(TimiCode code, String msg, Throwable e) {
-		super(msg, e);
-		this.code = code;
-	}
-
-	/**
-	 * 获取代码
-	 *
-	 * @return 代码
-	 */
-	public TimiCode getCode() {
-		return code;
-	}
-
-	public TimiResponse<?> toResponse() {
-		return new TimiResponse<>(code).msg(getMessage()).msgKey(msgKey, msgArgs);
-	}
-
-	@Override
-	public TimiException msg(String msg) {
-		throw new UnsupportedOperationException("unsupported to change message");
-	}
-
-	@Override
-	public TimiException msgKey(String msgKey) {
-		setMsgKey(msgKey);
-		return this;
-	}
-
-	@Override
-	public TimiException msgKey(String msgKey, Map<String, Object> msgArgs) {
-		setMsgKey(msgKey, msgArgs);
-		return this;
-	}
-
-	@Override
-	public void setMsg(String msg) {
-		throw new UnsupportedOperationException("unsupported to change message");
-	}
-
-	@Override
-	public String getMsg() {
-		return getMessage();
-	}
-
-	@Override
-	public void setMsgKey(String msgKey) {
-		this.msgKey = msgKey;
-	}
-
-	@Override
-	public void setMsgKey(String msgKey, Map<String, Object> msgArgs) {
-		this.msgKey = msgKey;
-		this.msgArgs = msgArgs;
-	}
-
-	@Override
-	public String getMsgKey() {
-		return msgKey;
-	}
-
-	@Override
-	public Map<String, Object> getMsgArgs() {
-		return msgArgs;
-	}
-
-	public static <T> T required(T t, String message) {
-		if (TimiJava.isEmpty(t)) {
-			throw new TimiException(TimiCode.ARG_MISS, message);
-		}
-		return t;
-	}
-
-	public static <T> T required(T t, String message, String msgKey) {
-		if (TimiJava.isEmpty(t)) {
-			throw new TimiException(TimiCode.ARG_MISS, message).msgKey(msgKey);
-		}
-		return t;
-	}
-
-	public static <T> void requiredNull(T t, String message) throws TimiException {
-		if (t != null) {
-			throw new TimiException(TimiCode.ERROR, message);
-		}
-	}
-
-	public static <T> void requiredNull(T t, String message, String msgKey) throws TimiException {
-		if (t != null) {
-			throw new TimiException(TimiCode.ERROR, message).msgKey(msgKey);
-		}
-	}
-
-	public static void requiredTrue(boolean bool, String message) throws TimiException {
-		if (bool) {
-			return;
-		}
-		throw new TimiException(TimiCode.ERROR, message);
-	}
-
-	public static void requiredTrue(boolean bool, String message, String msgKey) throws TimiException {
-		if (bool) {
-			return;
-		}
-		throw new TimiException(TimiCode.ERROR, message).msgKey(msgKey);
-	}
-
-	public static void requiredTrue(CallbackReturn<Boolean> callback, String message) throws TimiException {
-		TimiException.required(callback, "not found callback");
-		if (callback.handler()) {
-			return;
-		}
-		throw new TimiException(TimiCode.ERROR, message);
-	}
-
-	public static void requiredTrue(CallbackReturn<Boolean> callback, String message, String msgKey) throws TimiException {
-		TimiException.required(callback, "not found callback");
-		if (callback.handler()) {
-			return;
-		}
-		throw new TimiException(TimiCode.ERROR, message).msgKey(msgKey);
-	}
-}

src/main/java/com/imyeyu/java/bean/timi/TimiResponse.java

@@ -1,188 +0,0 @@
-package com.imyeyu.java.bean.timi;
-
-import com.imyeyu.java.bean.LanguageMsgMapping;
-
-import java.io.Serializable;
-import java.util.Map;
-
-/**
- * 通用接口返回对象
- *
- * @author 夜雨
- * @since 2021-07-01 20:18
- */
-public class TimiResponse<T> implements Serializable, LanguageMsgMapping<TimiResponse<T>> {
-
-	/** 代码 */
-	protected Integer code;
-
-	/** 消息 */
-	protected String msg;
-
-	protected transient String msgKey;
-
-	protected transient Map<String, Object> msgArgs;
-
-	/** 数据体 */
-	protected T data;
-
-	/** 默认构造器 */
-	public TimiResponse() {
-	}
-
-	/**
-	 * 构造器
-	 *
-	 * @param code 代码
-	 */
-	public TimiResponse(TimiCode code) {
-		this(code, null);
-	}
-
-	/**
-	 * 构造器
-	 *
-	 * @param code 代码
-	 * @param data 数据体
-	 */
-	public TimiResponse(TimiCode code, T data) {
-		this(code, data, null);
-	}
-
-	/**
-	 * 构造器
-	 *
-	 * @param code 代码
-	 * @param data 数据体
-	 * @param msg  消息
-	 */
-	public TimiResponse(TimiCode code, T data, String msg) {
-		this.code = code.getValue();
-		this.data = data;
-		this.msg  = msg;
-	}
-
-	/** @return true 为成功，code 为 20000 段 */
-	public boolean isSuccess() {
-		return code != null && code <= 30000;
-	}
-
-	/** @return true 为失败，isSuccess 取反 */
-	public boolean isFail() {
-		return !isSuccess();
-	}
-
-	/**
-	 * 转为通用异常
-	 *
-	 * @return 异常
-	 */
-	public TimiException toException() {
-		TimiCode code = TimiCode.fromCode(this.code);
-		if (code == null) {
-			throw new NullPointerException("unknow timi code: " + this.code);
-		}
-		return code.toException(msg);
-	}
-
-	/**
-	 * 获取代码
-	 *
-	 * @return 代码
-	 */
-	public Integer getCode() {
-		return code;
-	}
-
-	/**
-	 * 设置代码
-	 *
-	 * @param code 代码
-	 */
-	public void setCode(Integer code) {
-		this.code = code;
-	}
-
-	/**
-	 * 获取数据体
-	 *
-	 * @return 数据体
-	 */
-	public T getData() {
-		return data;
-	}
-
-	/**
-	 * 设置数据体
-	 *
-	 * @param data 数据体
-	 */
-	public void setData(T data) {
-		this.data = data;
-	}
-
-	/**
-	 * 追加消息（避免和泛型字符串冲突）
-	 *
-	 * @param msg 消息
-	 * @return 本对象
-	 */
-	@Override
-	public TimiResponse<T> msg(String msg) {
-		this.msg = msg;
-		return this;
-	}
-
-	/**
-	 * 获取消息
-	 *
-	 * @return 消息
-	 */
-	@Override
-	public String getMsg() {
-		return msg;
-	}
-
-	/**
-	 * 设置消息
-	 *
-	 * @param msg 消息
-	 */
-	@Override
-	public void setMsg(String msg) {
-		this.msg = msg;
-	}
-
-	@Override
-	public TimiResponse<T> msgKey(String msgKey) {
-		this.msgKey = msgKey;
-		return this;
-	}
-
-	@Override
-	public TimiResponse<T> msgKey(String msgKey, Map<String, Object> msgArgs) {
-		setMsgKey(msgKey, msgArgs);
-		return this;
-	}
-
-	@Override
-	public String getMsgKey() {
-		return msgKey;
-	}
-
-	@Override
-	public void setMsgKey(String msgKey) {
-		this.msgKey = msgKey;
-	}
-
-	@Override
-	public void setMsgKey(String msgKey, Map<String, Object> msgArgs) {
-		this.msgKey = msgKey;
-		this.msgArgs = msgArgs;
-	}
-
-	@Override
-	public Map<String, Object> getMsgArgs() {
-		return msgArgs;
-	}
-}

src/main/java/com/imyeyu/java/bean/timi/package-info.java

@@ -1,2 +0,0 @@
-/** 个人常用的通用类 */
-package com.imyeyu.java.bean.timi;

src/main/java/com/imyeyu/java/obs/ChangeListener.java

@@ -3,16 +3,33 @@ package com.imyeyu.java.obs;
 import java.util.List;
 
 /**
+ * 值变更监听器
+ *
+ * @param <T> 监听值类型
  * @author 夜雨
  * @since 2024-09-01 15:15
  */
 public interface ChangeListener<T> {
 
+	/**
+	 * 处理值变更事件
+	 *
+	 * @param from 变更前值
+	 * @param to 变更后值
+	 */
 	void handler(T from, T to);
 
+	/**
+	 * 通知全部监听器处理本次变更
+	 *
+	 * @param listenerList 监听器列表
+	 * @param from 变更前值
+	 * @param to 变更后值
+	 * @param <T> 监听值类型
+	 */
 	static <T> void notifyListener(List<ChangeListener<T>> listenerList, T from, T to) {
-		for (int i = 0; i < listenerList.size(); i++) {
+		for (ChangeListener<T> listener : listenerList) {
-			listenerList.get(i).handler(from, to);
+			listener.handler(from, to);
 		}
 	}
 }

src/main/java/com/imyeyu/java/obs/CollectionChangeListener.java

@@ -3,27 +3,49 @@ package com.imyeyu.java.obs;
 import java.util.List;
 
 /**
+ * 集合元素变更监听器
+ *
+ * @param <E> 元素类型
  * @author 夜雨
  * @since 2024-09-01 15:59
  */
 public interface CollectionChangeListener<E> {
 
 	/**
+	 * 集合变更类型
+	 *
 	 * @author 夜雨
 	 * @since 2024-09-01 19:47
 	 */
 	enum ChangeType {
 
+		/** 新增元素 */
 		ADD,
 
+		/** 删除元素 */
 		REMOVE
 	}
 
+	/**
+	 * 处理集合元素变更
+	 *
+	 * @param type 变更类型
+	 * @param e 本次变更元素
+	 * @throws RuntimeException 监听器处理失败时抛出
+	 */
 	void handler(ChangeType type, E e) throws RuntimeException;
 
+	/**
+	 * 通知全部集合监听器处理本次变更
+	 *
+	 * @param listenerList 监听器列表
+	 * @param type 变更类型
+	 * @param element 本次变更元素
+	 * @param <E> 元素类型
+	 */
 	static <E> void notifyListener(List<CollectionChangeListener<E>> listenerList, ChangeType type, E element) {
-		for (int i = 0; i < listenerList.size(); i++) {
+		for (CollectionChangeListener<E> listener : listenerList) {
-			listenerList.get(i).handler(type, element);
+			listener.handler(type, element);
 		}
 	}
 }

src/main/java/com/imyeyu/java/obs/MapChangeListener.java

@@ -3,32 +3,56 @@ package com.imyeyu.java.obs;
 import java.util.List;
 
 /**
+ * 映射变更监听器
+ *
+ * @param <K> 键类型
+ * @param <V> 值类型
  * @author 夜雨
  * @since 2024-09-01 18:01
  */
 public interface MapChangeListener<K, V> {
 
 	/**
-	 *
+	 * 映射变更类型
 	 *
 	 * @author 夜雨
 	 * @since 2024-09-01 23:51
 	 */
 	enum ChangeType {
 
+		/** 新增键值对 */
 		ADD,
 
+		/** 更新既有键值对 */
 		UPDATE,
 
+		/** 删除键值对 */
 		REMOVE
 	}
 
+	/**
+	 * 处理映射变更
+	 *
+	 * @param type 变更类型
+	 * @param key 变更键
+	 * @param value 变更值
+	 */
 	void handler(ChangeType type, K key, V value);
 
+	/**
+	 * 通知全部映射监听器处理本次变更
+	 *
+	 * @param listenerList 监听器列表
+	 * @param type 变更类型
+	 * @param key 变更键
+	 * @param value 变更值
+	 * @param <K> 键类型
+	 * @param <V> 值类型
+	 */
 	@SuppressWarnings("unchecked")
 	static <K, V> void notifyListener(List<MapChangeListener<K, V>> listenerList, ChangeType type, Object key, V value) {
-		for (int i = 0; i < listenerList.size(); i++) {
+		for (MapChangeListener<K, V> kvMapChangeListener : listenerList) {
-			listenerList.get(i).handler(type, (K) key, value);
+			kvMapChangeListener.handler(type, (K) key, value);
 		}
 	}
 }

src/main/java/com/imyeyu/java/obs/Observable.java

@@ -1,16 +1,39 @@
 package com.imyeyu.java.obs;
 
 /**
+ * 可观察对象接口
+ *
+ * @param <T> 可观察值类型
  * @author 夜雨
  * @since 2024-09-01 15:07
  */
 public interface Observable<T> {
 
+	/**
+	 * 获取当前值
+	 *
+	 * @return 当前值
+	 */
 	T get();
 
+	/**
+	 * 设置当前值
+	 *
+	 * @param value 新值
+	 */
 	void set(T value);
 
+	/**
+	 * 添加值变更监听器
+	 *
+	 * @param changeListener 值变更监听器
+	 */
 	void addListener(ChangeListener<T> changeListener);
 
+	/**
+	 * 移除值变更监听器
+	 *
+	 * @param changeListener 值变更监听器
+	 */
 	void removeListener(ChangeListener<T> changeListener);
 }

src/main/java/com/imyeyu/java/obs/ObservableBoolean.java

@@ -1,15 +1,21 @@
 package com.imyeyu.java.obs;
 
+import lombok.NoArgsConstructor;
+
 /**
+ * 可观察布尔值
+ *
  * @author 夜雨
  * @since 2024-09-01 18:43
  */
+@NoArgsConstructor
 public class ObservableBoolean extends ObservableObject<Boolean> {
 
-	public ObservableBoolean() {
+	/**
-		super();
+	 * 使用指定初始值创建可观察布尔值
-	}
+	 *
-
+	 * @param value 初始值
+	 */
 	public ObservableBoolean(Boolean value) {
 		super(value);
 	}

src/main/java/com/imyeyu/java/obs/ObservableDouble.java

@@ -1,15 +1,21 @@
 package com.imyeyu.java.obs;
 
+import lombok.NoArgsConstructor;
+
 /**
+ * 可观察双精度值
+ *
  * @author 夜雨
  * @since 2024-09-01 18:43
  */
+@NoArgsConstructor
 public class ObservableDouble extends ObservableObject<Double> {
 
-	public ObservableDouble() {
+	/**
-		super();
+	 * 使用指定数值创建可观察双精度值
-	}
+	 *
-
+	 * @param value 初始值
+	 */
 	public ObservableDouble(Number value) {
 		super(value.doubleValue());
 	}

src/main/java/com/imyeyu/java/obs/ObservableFloat.java

@@ -1,15 +1,21 @@
 package com.imyeyu.java.obs;
 
+import lombok.NoArgsConstructor;
+
 /**
+ * 可观察浮点值
+ *
  * @author 夜雨
  * @since 2024-09-01 18:43
  */
+@NoArgsConstructor
 public class ObservableFloat extends ObservableObject<Float> {
 
-	public ObservableFloat() {
+	/**
-		super();
+	 * 使用指定初始值创建可观察浮点值
-	}
+	 *
-
+	 * @param value 初始值
+	 */
 	public ObservableFloat(Float value) {
 		super(value);
 	}

src/main/java/com/imyeyu/java/obs/ObservableInteger.java

@@ -1,14 +1,21 @@
 package com.imyeyu.java.obs;
 
+import lombok.NoArgsConstructor;
+
 /**
+ * 可观察整型值
+ *
  * @author 夜雨
  * @since 2024-09-01 15:06
  */
+@NoArgsConstructor
 public class ObservableInteger extends ObservableObject<Integer> {
 
-	public ObservableInteger() {
+	/**
-	}
+	 * 使用指定初始值创建可观察整型值
-
+	 *
+	 * @param value 初始值
+	 */
 	public ObservableInteger(Integer value) {
 		super(value);
 	}

src/main/java/com/imyeyu/java/obs/ObservableList.java

@@ -7,28 +7,56 @@ import java.util.List;
 import java.util.function.Predicate;
 
 /**
+ * 可观察列表，支持监听元素新增和删除事件
+ *
+ * @param <E> 元素类型
  * @author 夜雨
  * @since 2024-09-01 17:51
  */
 public class ObservableList<E> extends ArrayList<E> {
 
+	/** 集合变更监听器列表 */
 	private final List<CollectionChangeListener<E>> changeListenerList = new ArrayList<>();
 
+	/**
+	 * 创建空的可观察列表
+	 */
 	public ObservableList() {
 	}
 
+	/**
+	 * 使用指定集合创建可观察列表
+	 *
+	 * @param c 初始化集合
+	 */
 	public ObservableList(Collection<? extends E> c) {
 		super(c);
 	}
 
+	/**
+	 * 添加集合变更监听器
+	 *
+	 * @param listener 集合变更监听器
+	 */
 	public void addChangeListener(CollectionChangeListener<E> listener) {
 		changeListenerList.add(listener);
 	}
 
+	/**
+	 * 移除集合变更监听器
+	 *
+	 * @param listener 集合变更监听器
+	 */
 	public void removeChangeListener(CollectionChangeListener<E> listener) {
-		changeListenerList.add(listener);
+		changeListenerList.remove(listener);
 	}
 
+	/**
+	 * 新增元素并通知监听器
+	 *
+	 * @param e 待新增元素
+	 * @return true 表示列表发生变化
+	 */
 	@Override
 	public boolean add(E e) {
 		boolean result = super.add(e);
@@ -38,12 +66,24 @@ public class ObservableList<E> extends ArrayList<E> {
 		return result;
 	}
 
+	/**
+	 * 在指定下标新增元素并通知监听器
+	 *
+	 * @param index 插入下标
+	 * @param element 待新增元素
+	 */
 	@Override
 	public void add(int index, E element) {
 		super.add(index, element);
 		CollectionChangeListener.notifyListener(changeListenerList, CollectionChangeListener.ChangeType.ADD, element);
 	}
 
+	/**
+	 * 批量新增元素并逐个通知监听器
+	 *
+	 * @param c 待新增元素集合
+	 * @return true 表示列表发生变化
+	 */
 	@Override
 	public boolean addAll(Collection<? extends E> c) {
 		boolean result = super.addAll(c);
@@ -55,6 +95,13 @@ public class ObservableList<E> extends ArrayList<E> {
 		return result;
 	}
 
+	/**
+	 * 从指定下标开始批量新增元素并逐个通知监听器
+	 *
+	 * @param index 起始下标
+	 * @param c 待新增元素集合
+	 * @return true 表示列表发生变化
+	 */
 	@Override
 	public boolean addAll(int index, Collection<? extends E> c) {
 		boolean result = super.addAll(index, c);
@@ -66,6 +113,12 @@ public class ObservableList<E> extends ArrayList<E> {
 		return result;
 	}
 
+	/**
+	 * 删除指定下标元素并通知监听器
+	 *
+	 * @param index 待删除元素下标
+	 * @return 被删除元素
+	 */
 	@Override
 	public E remove(int index) {
 		E removed = super.remove(index);
@@ -75,11 +128,23 @@ public class ObservableList<E> extends ArrayList<E> {
 		return removed;
 	}
 
+	/**
+	 * 删除指定元素并通知监听器
+	 *
+	 * @param o 待删除元素
+	 * @return true 表示删除成功
+	 */
 	@Override
 	public boolean remove(Object o) {
 		return remove(indexOf(o)) != null;
 	}
 
+	/**
+	 * 批量删除元素并逐个通知监听器
+	 *
+	 * @param c 待删除元素集合
+	 * @return true 表示列表发生变化
+	 */
 	@SuppressWarnings("unchecked")
 	@Override
 	public boolean removeAll(Collection<?> c) {
@@ -92,6 +157,12 @@ public class ObservableList<E> extends ArrayList<E> {
 		return result;
 	}
 
+	/**
+	 * 按条件删除元素
+	 *
+	 * @param filter 删除条件
+	 * @return true 表示至少删除一个元素
+	 */
 	@Override
 	public boolean removeIf(Predicate<? super E> filter) {
 		boolean removed = false;
@@ -106,6 +177,13 @@ public class ObservableList<E> extends ArrayList<E> {
 		return removed;
 	}
 
+	/**
+	 * 获取子列表的可观察副本
+	 *
+	 * @param fromIndex 起始下标（含）
+	 * @param toIndex 结束下标（不含）
+	 * @return 子列表副本
+	 */
 	@Override
 	public ObservableList<E> subList(int fromIndex, int toIndex) {
 		List<E> subList = super.subList(fromIndex, toIndex);

src/main/java/com/imyeyu/java/obs/ObservableLong.java

@@ -1,15 +1,21 @@
 package com.imyeyu.java.obs;
 
+import lombok.NoArgsConstructor;
+
 /**
+ * 可观察长整型值
+ *
  * @author 夜雨
  * @since 2024-09-01 18:43
  */
+@NoArgsConstructor
 public class ObservableLong extends ObservableObject<Long> {
 
-	public ObservableLong() {
+	/**
-		super();
+	 * 使用指定初始值创建可观察长整型值
-	}
+	 *
-
+	 * @param value 初始值
+	 */
 	public ObservableLong(Long value) {
 		super(value);
 	}

src/main/java/com/imyeyu/java/obs/ObservableMap.java

@@ -6,21 +6,43 @@ import java.util.List;
 import java.util.Map;
 
 /**
+ * 可观察映射，支持监听键值对新增、更新和删除事件
+ *
+ * @param <K> 键类型
+ * @param <V> 值类型
  * @author 夜雨
  * @since 2024-09-01 18:32
  */
 public class ObservableMap<K, V> extends HashMap<K, V> {
 
+	/** 映射变更监听器列表 */
 	private final List<MapChangeListener<K, V>> changeListenerList = new ArrayList<>();
 
+	/**
+	 * 添加映射变更监听器
+	 *
+	 * @param listener 映射变更监听器
+	 */
 	public void addChangeListener(MapChangeListener<K, V> listener) {
 		changeListenerList.add(listener);
 	}
 
+	/**
+	 * 移除映射变更监听器
+	 *
+	 * @param listener 映射变更监听器
+	 */
 	public void removeChangeListener(MapChangeListener<K, V> listener) {
-		changeListenerList.add(listener);
+		changeListenerList.remove(listener);
 	}
 
+	/**
+	 * 写入键值对并在必要时通知监听器
+	 *
+	 * @param key 键
+	 * @param value 值
+	 * @return 旧值，不存在则为 null
+	 */
 	@Override
 	public V put(K key, V value) {
 		V v = super.put(key, value);
@@ -32,6 +54,11 @@ public class ObservableMap<K, V> extends HashMap<K, V> {
 		return v;
 	}
 
+	/**
+	 * 批量写入键值对
+	 *
+	 * @param m 待写入映射
+	 */
 	@Override
 	public void putAll(Map<? extends K, ? extends V> m) {
 		for (Map.Entry<? extends K, ? extends V> item : m.entrySet()) {
@@ -39,6 +66,12 @@ public class ObservableMap<K, V> extends HashMap<K, V> {
 		}
 	}
 
+	/**
+	 * 删除指定键并通知监听器
+	 *
+	 * @param key 键
+	 * @return 被删除值，不存在则为 null
+	 */
 	@Override
 	public V remove(Object key) {
 		V removed = super.remove(key);
@@ -48,6 +81,13 @@ public class ObservableMap<K, V> extends HashMap<K, V> {
 		return removed;
 	}
 
+	/**
+	 * 仅当键值都匹配时删除并通知监听器
+	 *
+	 * @param key 键
+	 * @param value 值
+	 * @return true 表示删除成功
+	 */
 	@SuppressWarnings("unchecked")
 	@Override
 	public boolean remove(Object key, Object value) {

src/main/java/com/imyeyu/java/obs/ObservableObject.java

@@ -1,30 +1,42 @@
 package com.imyeyu.java.obs;
 
+import lombok.NoArgsConstructor;
+
 import java.util.ArrayList;
 import java.util.List;
 
 /**
+ * 可观察对象抽象基类
+ *
+ * @param <T> 可观察值类型
  * @author 夜雨
  * @since 2024-09-01 15:22
  */
+@NoArgsConstructor
 public abstract class ObservableObject<T> implements Observable<T> {
 
+	/** 值变更监听器列表 */
 	private final List<ChangeListener<T>> changeListenerList = new ArrayList<>();
 
+	/** 当前值 */
 	private T value;
 
-	public ObservableObject() {
+	/**
-	}
+	 * 使用指定初始值创建可观察对象
-
+	 *
+	 * @param value 初始值
+	 */
 	public ObservableObject(T value) {
 		this.value = value;
 	}
 
+	/** {@inheritDoc} */
 	@Override
 	public final T get() {
 		return value;
 	}
 
+	/** {@inheritDoc} */
 	@Override
 	public final void set(T toValue) {
 		final T from = this.value;
@@ -35,11 +47,13 @@ public abstract class ObservableObject<T> implements Observable<T> {
 		}
 	}
 
+	/** {@inheritDoc} */
 	@Override
 	public void addListener(ChangeListener<T> changeListener) {
 		changeListenerList.add(changeListener);
 	}
 
+	/** {@inheritDoc} */
 	@Override
 	public void removeListener(ChangeListener<T> changeListener) {
 		changeListenerList.remove(changeListener);

src/main/java/com/imyeyu/java/obs/ObservableSet.java

@@ -8,21 +8,41 @@ import java.util.List;
 import java.util.function.Predicate;
 
 /**
+ * 可观察集合，支持监听元素新增和删除事件
+ *
+ * @param <E> 元素类型
  * @author 夜雨
  * @since 2024-09-01 18:29
  */
 public class ObservableSet<E> extends HashSet<E> {
 
+	/** 集合变更监听器列表 */
 	private final List<CollectionChangeListener<E>> changeListenerList = new ArrayList<>();
 
+	/**
+	 * 添加集合变更监听器
+	 *
+	 * @param listener 集合变更监听器
+	 */
 	public void addChangeListener(CollectionChangeListener<E> listener) {
 		changeListenerList.add(listener);
 	}
 
+	/**
+	 * 移除集合变更监听器
+	 *
+	 * @param listener 集合变更监听器
+	 */
 	public void removeChangeListener(CollectionChangeListener<E> listener) {
-		changeListenerList.add(listener);
+		changeListenerList.remove(listener);
 	}
 
+	/**
+	 * 新增元素并通知监听器
+	 *
+	 * @param e 待新增元素
+	 * @return true 表示集合发生变化
+	 */
 	@Override
 	public boolean add(E e) {
 		boolean result = super.add(e);
@@ -32,6 +52,12 @@ public class ObservableSet<E> extends HashSet<E> {
 		return result;
 	}
 
+	/**
+	 * 批量新增元素并逐个通知监听器
+	 *
+	 * @param c 待新增元素集合
+	 * @return true 表示集合发生变化
+	 */
 	@Override
 	public boolean addAll(Collection<? extends E> c) {
 		boolean result = super.addAll(c);
@@ -43,6 +69,12 @@ public class ObservableSet<E> extends HashSet<E> {
 		return result;
 	}
 
+	/**
+	 * 删除指定元素并通知监听器
+	 *
+	 * @param o 待删除元素
+	 * @return true 表示删除成功
+	 */
 	@SuppressWarnings("unchecked")
 	@Override
 	public boolean remove(Object o) {
@@ -53,6 +85,12 @@ public class ObservableSet<E> extends HashSet<E> {
 		return removed;
 	}
 
+	/**
+	 * 批量删除元素并逐个通知监听器
+	 *
+	 * @param c 待删除元素集合
+	 * @return true 表示集合发生变化
+	 */
 	@SuppressWarnings("unchecked")
 	@Override
 	public boolean removeAll(Collection<?> c) {
@@ -65,6 +103,12 @@ public class ObservableSet<E> extends HashSet<E> {
 		return result;
 	}
 
+	/**
+	 * 按条件删除元素
+	 *
+	 * @param filter 删除条件
+	 * @return true 表示至少删除一个元素
+	 */
 	@Override
 	public boolean removeIf(Predicate<? super E> filter) {
 		boolean removed = false;

src/main/java/com/imyeyu/java/obs/ObservableString.java

@@ -1,27 +1,48 @@
 package com.imyeyu.java.obs;
 
+import lombok.NoArgsConstructor;
+
 /**
+ * 可观察字符串值
+ *
  * @author 夜雨
  * @since 2024-09-01 18:43
  */
+@NoArgsConstructor
 public class ObservableString extends ObservableObject<String> {
 
-	public ObservableString() {
+	/**
-		super();
+	 * 使用指定初始值创建可观察字符串值
-	}
+	 *
-
+	 * @param value 初始值
+	 */
 	public ObservableString(String value) {
 		super(value);
 	}
 
+	/**
+	 * 判断当前字符串是否为空或全空白
+	 *
+	 * @return true 表示空串或全空白
+	 */
 	public boolean isEmpty() {
 		return get().isEmpty() || get().trim().isEmpty();
 	}
 
+	/**
+	 * 判断当前字符串是否非空且非全空白
+	 *
+	 * @return true 表示非空且包含非空白字符
+	 */
 	public boolean isNotEmpty() {
 		return !isEmpty();
 	}
 
+	/**
+	 * 获取当前字符串值
+	 *
+	 * @return 当前字符串值
+	 */
 	@Override
 	public String toString() {
 		return get();

src/main/java/com/imyeyu/java/ref/Ref.java

@@ -7,7 +7,7 @@ import java.util.Collections;
 import java.util.List;
 
 /**
- * 反射相关
+ * 反射工具类，提供字段与方法查找、字段读写、字符串转枚举等能力
  *
  * @author 夜雨
  * @since 2023-05-04 15:05
@@ -15,9 +15,9 @@ import java.util.List;
 public class Ref {
 
 	/**
-	 * 获取类字段列表
+	 * 获取指定类声明的字段列表（不包含父类）
 	 *
-	 * @param clazz 类
+	 * @param clazz 类型对象
 	 * @return 字段列表
 	 */
 	public static List<Field> listFields(Class<?> clazz) {
@@ -25,9 +25,9 @@ public class Ref {
 	}
 
 	/**
-	 * 获取类字段列表（包括父类）
+	 * 获取指定类及其父类声明的字段列表（直到 {@link Object} 之前）
 	 *
-	 * @param clazz 类
+	 * @param clazz 类型对象
 	 * @return 字段列表
 	 */
 	public static List<Field> listAllFields(Class<?> clazz) {
@@ -40,20 +40,21 @@ public class Ref {
 	}
 
 	/**
+	 * 将外部键名转换为 Java 字段名
 	 *
-	 * @param keyName
+	 * @param keyName 外部键名，支持中划线、下划线和空格分隔
-	 * @return
+	 * @return 驼峰命名字段名
 	 */
 	public static String getFieldName(String keyName) {
 		String[] splits = {"-", "_", " "};
 		StringBuilder full = new StringBuilder(keyName.substring(0, 1).toUpperCase() + keyName.substring(1));
-		for (int i = 0; i < splits.length; i++) {
+		for (String split : splits) {
-			if (keyName.contains(splits[i])) {
+			if (keyName.contains(split)) {
-				// 存在分隔符
+				// 存在分隔符时，先按分隔符拆词，再按驼峰拼接
 				full.setLength(0);
-				String[] word = keyName.split(splits[i]);
+				String[] word = keyName.split(split);
-				for (int j = 0; j < word.length; j++) {
+				for (String s : word) {
-					full.append(word[j].substring(0, 1).toUpperCase()).append(word[j].substring(1));
+					full.append(s.substring(0, 1).toUpperCase()).append(s.substring(1));
 				}
 				break;
 			}
@@ -62,11 +63,12 @@ public class Ref {
 	}
 
 	/**
-	 * 反射获取对象字段，包括父级类，直至 {@link Object}，如果都不存在则返回 null
+	 * 反射获取对象字段，包括父级类，直至 {@link Object}，如果都不存在则抛出异常
 	 *
 	 * @param clazz     类
 	 * @param fieldName 字段名
-	 * @return 字段
+	 * @return 字段对象
+	 * @throws NullPointerException 找不到字段时抛出异常
 	 */
 	public static Field getField(Class<?> clazz, String fieldName) {
 		do {
@@ -78,7 +80,7 @@ public class Ref {
 				clazz = clazz.getSuperclass();
 			}
 		} while (clazz != Object.class);
-		throw new NullPointerException(String.format("not found field: %s in %s", fieldName, clazz));
+		throw new NullPointerException("not found field: %s in %s".formatted(fieldName, clazz));
 	}
 
 	/**
@@ -105,7 +107,7 @@ public class Ref {
 	 * @param <T>     返回类型
 	 * @return 字段值
 	 * @throws IllegalAccessException 反射访问失败
-	 * @throws NullPointerException   向上反射直至 {@link Object} 也找不到该字段
+	 * @throws NullPointerException   字段对象为空
 	 */
 	public static <T> T getFieldValue(Object object, Field field, Class<? extends T> toClass) throws IllegalAccessException, NullPointerException {
 		if (field == null) {
@@ -120,7 +122,7 @@ public class Ref {
 	 *
 	 * @param objectClass 类
 	 * @param fieldName   字段名
-	 * @return 字段
+	 * @return 字段对象，不存在时返回 null
 	 */
 	public static Field getClassField(Class<?> objectClass, String fieldName) {
 		try {
@@ -142,7 +144,7 @@ public class Ref {
 	 * @param <T>         值类型
 	 * @return 字段值
 	 * @throws IllegalAccessException 反射访问失败
-	 * @throws NoSuchFieldException 字段不存在
+	 * @throws NoSuchFieldException  字段不存在
 	 */
 	public static <T> T getClassFieldValue(Object object, Class<?> objectClass, String fieldName, Class<T> toClass) throws IllegalAccessException, NoSuchFieldException {
 		Field field = getClassField(objectClass, fieldName);
@@ -160,16 +162,19 @@ public class Ref {
 	 * @param fieldName 字段名
 	 * @param value     字段值
 	 * @throws IllegalAccessException 反射访问失败
-	 * @throws NoSuchFieldException 向上反射直至 {@link Object} 也找不到该字段
 	 */
-	public static void setFieldValue(Object object, String fieldName, Object value) throws IllegalAccessException, NoSuchFieldException {
+	public static void setFieldValue(Object object, String fieldName, Object value) throws IllegalAccessException {
-		Field field = getField(object.getClass(), fieldName);
+		setFieldValue(object, getField(object.getClass(), fieldName), value);
-		if (field == null) {
-			throw new NoSuchFieldException("not found " + fieldName + " field in " + object.getClass().getSimpleName());
-		}
-		setFieldValue(object, field, value);
 	}
 
+	/**
+	 * 反射设置对象字段值
+	 *
+	 * @param object 对象
+	 * @param field  字段对象
+	 * @param value  字段值
+	 * @throws IllegalAccessException 反射访问失败
+	 */
 	public static void setFieldValue(Object object, Field field, Object value) throws IllegalAccessException {
 		field.setAccessible(true);
 		field.set(object, value);
@@ -200,7 +205,8 @@ public class Ref {
 	 * @param clazz          类
 	 * @param methodName     方法名
 	 * @param parameterTypes 可选参
-	 * @return 方法对象
+	 * @return 方法对象，不存在时返回 null
+	 * @throws NullPointerException 类对象为空
 	 */
 	public static Method getMethod(Class<?> clazz, String methodName, Class<?>... parameterTypes) {
 		if (clazz == null) {
@@ -224,7 +230,8 @@ public class Ref {
 	 * @param clazz  枚举类
 	 * @param string 字符串
 	 * @param <T>    泛型
-	 * @return 泛型
+	 * @return 匹配到的枚举值，找不到或输入为空时返回 null
+	 * @throws IllegalArgumentException 传入类型不是枚举类型
 	 */
 	public static <T extends Enum<?>> T toType(Class<T> clazz, String string) {
 		if (string == null) {
@@ -234,31 +241,32 @@ public class Ref {
 		if (ts == null) {
 			throw new IllegalArgumentException(clazz.getName() + " is not an enum type");
 		}
-		for (int i = 0; i < ts.length; i++) {
+		for (T t : ts) {
-			if (ts[i].name().equalsIgnoreCase(string)) {
+			if (t.name().equalsIgnoreCase(string)) {
-				return ts[i];
+				return t;
 			}
 		}
 		return null;
 	}
 
 	/**
+	 * 创建字段反射元信息对象
 	 *
-	 *
+	 * @param owner 字段所属类型
-	 * @param owner
+	 * @param keyName 字段键名
-	 * @param keyName
+	 * @return 字段反射元信息
-	 * @return
 	 */
 	public static RefField field(Class<?> owner, String keyName) {
 		return new RefField(owner, keyName);
 	}
 
 	/**
+	 * 通过无参构造器创建实例
 	 *
-	 * @param type
+	 * @param type 类型对象
-	 * @return
+	 * @param <T>  泛型类型
-	 * @param <T>
+	 * @return 新实例
-	 * @throws Exception
+	 * @throws Exception 反射创建实例异常
 	 */
 	public static <T> T newInstance(Class<T> type) throws Exception {
 		return type.getDeclaredConstructor().newInstance();

src/main/java/com/imyeyu/java/ref/RefField.java

@@ -1,21 +1,39 @@
 package com.imyeyu.java.ref;
 
+import lombok.Getter;
+import lombok.Setter;
+
 import java.lang.reflect.Field;
 import java.lang.reflect.Method;
 
 /**
- *
+ * 字段反射元信息，包含字段类型以及对应的 getter/setter 方法
  *
  * @author 夜雨
  * @since 2024-04-26 15:46
  */
+@Getter
+@Setter
 public class RefField {
 
+	/** 字段类型 */
 	private Class<?> type;
+
+	/** 字段对象 */
 	private Field field;
+
+	/** 字段 setter 方法 */
 	private Method setter;
+
+	/** 字段 getter 方法 */
 	private Method getter;
 
+	/**
+	 * 根据拥有者类型和键名构建字段反射元信息
+	 *
+	 * @param owner 字段所属类型
+	 * @param keyName 字段键名，支持中划线、下划线和空格形式
+	 */
 	RefField(Class<?> owner, String keyName) {
 		String fieldName = Ref.getFieldName(keyName);
 		String fieldNameUpper = String.valueOf(fieldName.charAt(0)).toUpperCase() + fieldName.substring(1);
@@ -38,40 +56,7 @@ public class RefField {
 			setterName = "set" + fieldNameUpper;
 			getterName = "get" + fieldNameUpper;
 		}
-
 		setter = Ref.getMethod(owner, setterName, field.getType());
 		getter = Ref.getMethod(owner, getterName);
 	}
-
-	public Class<?> getType() {
-		return type;
-	}
-
-	public void setType(Class<?> type) {
-		this.type = type;
-	}
-
-	public Field getField() {
-		return field;
-	}
-
-	public void setField(Field field) {
-		this.field = field;
-	}
-
-	public Method getSetter() {
-		return setter;
-	}
-
-	public void setSetter(Method setter) {
-		this.setter = setter;
-	}
-
-	public Method getGetter() {
-		return getter;
-	}
-
-	public void setGetter(Method getter) {
-		this.getter = getter;
-	}
 }

src/main/java/com/imyeyu/java/thread/AsyncRetryExecutor.java

@@ -2,10 +2,17 @@ package com.imyeyu.java.thread;
 
 import com.imyeyu.java.bean.Callback;
 import com.imyeyu.java.bean.CallbackArg;
+import com.imyeyu.java.bean.ActionException;
+import lombok.AllArgsConstructor;
+import lombok.Builder;
+import lombok.Data;
+import lombok.Getter;
+import lombok.NoArgsConstructor;
 
 import java.util.concurrent.TimeUnit;
 
 /**
+ * 异步可重试执行器
  *
  * @author 夜雨
  * @since 2025-11-06 17:45
@@ -24,16 +31,65 @@ public class AsyncRetryExecutor {
 	/** true 为守护进程 */
 	private static final boolean DEFAULT_DAEMON = false;
 
+	/** 实际执行重试逻辑的线程 */
 	private final Thread thread;
+
+	/** true 为执行成功 */
+	@Getter
 	private volatile boolean isSuccess = false;
+
+	/** true 为处于运行状态 */
+	@Getter
 	private volatile boolean isRunning = false;
 
-	private AsyncRetryExecutor(Builder builder) {
+	/**
+	 * 任务
+	 *
+	 * @author 夜雨
+	 * @since 2025-11-06 23:37
+	 */
+	@Data
+	@Builder
+	@NoArgsConstructor
+	@AllArgsConstructor
+	public static class Task {
+
+		/** 必填回调方法 */
+		private Callback callback;
+
+		/** 最大重试次数，-1 为无限重试 */
+		@Builder.Default
+		private int maxRetry = DEFAULT_MAX_RETRY;
+
+		/** 重试间隔毫秒数 */
+		@Builder.Default
+		private long retryInterval = DEFAULT_RETRY_INTERVAL;
+
+		/** 线程名前缀 */
+		@Builder.Default
+		private String threadNamePrefix = DEFAULT_THREAD_NAME_PREFIX;
+
+		/** 是否设置为守护线程 */
+		@Builder.Default
+		private boolean daemon = DEFAULT_DAEMON;
+
+		/** 重试耗尽时的异常回调 */
+		private CallbackArg<Exception> onRetryExhausted;
+	}
+
+	/**
+	 * 根据构建器参数创建异步重试执行器
+	 *
+	 * @param task 构建器对象
+	 */
+	private AsyncRetryExecutor(Task task) {
+		ActionException.required(task, "not found task");
+		ActionException.required(task.getCallback(), "not found task.callback");
 		thread = new Thread(() -> {
 			int retryCount = 0;
-			while (isRunning && !isSuccess && (builder.maxRetry < 0 || retryCount <= builder.maxRetry)) {
+			while (isRunning && !isSuccess && (task.maxRetry < 0 || retryCount <= task.maxRetry)) {
 				try {
-					builder.callback.handler();
+					task.callback.handler();
 					isSuccess = true;
 				} catch (Exception e) {
 					retryCount++;
@@ -41,88 +97,71 @@ public class AsyncRetryExecutor {
 						// 中断
 						break;
 					}
-					if (0 < builder.maxRetry && builder.maxRetry < retryCount) {
+					if (0 < task.maxRetry && task.maxRetry < retryCount) {
 						// 超过重试次数
-						builder.onRetryExhausted.handler(e);
+						if (task.onRetryExhausted != null) {
+							task.onRetryExhausted.handler(e);
+						}
 						break;
 					}
 					// 重试
 					try {
-						TimeUnit.MILLISECONDS.sleep(builder.retryInterval);
+						TimeUnit.MILLISECONDS.sleep(task.retryInterval);
 					} catch (InterruptedException ex) {
 						Thread.currentThread().interrupt();
 						break;
 					}
 				}
 			}
-		}, builder.threadNamePrefix + Thread.currentThread().threadId());
+		}, task.threadNamePrefix + Thread.currentThread().threadId());
-		thread.setDaemon(builder.daemon);
+		thread.setDaemon(task.daemon);
 	}
 
 	/**
-	 * 构造器
+	 * 使用默认参数创建执行器
 	 *
-	 * @author 夜雨
+	 * @param task 任务
-	 * @since 2025-11-06 23:37
+	 * @return 执行器实例
 	 */
-	public static class Builder {
+	public static AsyncRetryExecutor create(Task task) {
-
+		return new AsyncRetryExecutor(task);
-		// 必需参数
-		private final Callback callback;
-
-		// 可选参数（带默认值）
-		private int maxRetry = DEFAULT_MAX_RETRY;
-		private long retryInterval = DEFAULT_RETRY_INTERVAL;
-		private String threadNamePrefix = DEFAULT_THREAD_NAME_PREFIX;
-		private boolean daemon = DEFAULT_DAEMON;
-		private CallbackArg<Exception> onRetryExhausted;
-
-		public Builder(Callback callback) {
-			this.callback = callback;
-		}
-
-		public Builder maxRetry(int maxRetry) {
-			this.maxRetry = maxRetry;
-			return this;
-		}
-
-		public Builder retryInterval(long retryInterval) {
-			this.retryInterval = retryInterval;
-			return this;
-		}
-
-		public Builder threadNamePrefix(String prefix) {
-			this.threadNamePrefix = prefix;
-			return this;
-		}
-
-		public Builder daemon(boolean daemon) {
-			this.daemon = daemon;
-			return this;
-		}
-
-		public Builder onRetryExhausted(CallbackArg<Exception> onRetryExhausted) {
-			this.onRetryExhausted = onRetryExhausted;
-			return this;
-		}
-
-		public AsyncRetryExecutor build() {
-			return new AsyncRetryExecutor(this);
-		}
 	}
 
+	/**
+	 * 使用默认参数创建执行器
+	 *
+	 * @param callback 执行回调
+	 * @return 执行器实例
+	 */
 	public static AsyncRetryExecutor create(Callback callback) {
-		return new Builder(callback).build();
+		return new AsyncRetryExecutor(Task.builder().callback(callback).build());
 	}
 
+	/**
+	 * 使用指定最大重试次数创建执行器
+	 *
+	 * @param callback 执行回调
+	 * @param maxRetry 最大重试次数
+	 * @return 执行器实例
+	 */
 	public static AsyncRetryExecutor create(Callback callback, int maxRetry) {
-		return new Builder(callback).maxRetry(maxRetry).build();
+		return new AsyncRetryExecutor(Task.builder().callback(callback).maxRetry(maxRetry).build());
 	}
 
+	/**
+	 * 使用指定重试间隔创建执行器
+	 *
+	 * @param callback 执行回调
+	 * @param interval 重试间隔毫秒数
+	 * @return 执行器实例
+	 */
 	public static AsyncRetryExecutor create(Callback callback, long interval) {
-		return new Builder(callback).retryInterval(interval).build();
+		return new AsyncRetryExecutor(Task.builder().callback(callback).retryInterval(interval).build());
 	}
 
+	/**
+	 * 启动异步执行
+	 */
 	public void start() {
 		if (!isRunning) {
 			isRunning = true;
@@ -131,18 +170,13 @@ public class AsyncRetryExecutor {
 		}
 	}
 
+	/**
+	 * 中断执行并停止后续重试
+	 */
 	public void interrupt() {
 		isRunning = false;
 		if (thread.isAlive() && !thread.isInterrupted()) {
 			thread.interrupt();
 		}
 	}
-
-	public boolean isSuccess() {
-		return isSuccess;
-	}
-
-	public boolean isRunning() {
-		return isRunning;
-	}
 }

src/test/java/com/imyeyu/java/AsyncRetryExecutorTest.java

@@ -1,14 +1,23 @@
-package test;
+package com.imyeyu.java;
 
 import com.imyeyu.java.thread.AsyncRetryExecutor;
 import org.junit.jupiter.api.Test;
 
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
 /**
+ * 线程工具相关测试
+ *
  * @author 夜雨
  * @since 2025-11-06 23:59
  */
-public class TestThread {
+public class AsyncRetryExecutorTest {
 
+	/**
+	 * 验证异步重试执行器在成功后状态为成功
+	 *
+	 * @throws InterruptedException 等待异步完成时中断异常
+	 */
 	@Test
 	public void testAsyncRetryExecutor() throws InterruptedException {
 		Object lock = new Object();
@@ -25,11 +34,9 @@ public class TestThread {
 			}
 		});
 		executor.start();
-
 		synchronized (lock) {
 			lock.wait();
 		}
-
+		assertTrue(executor.isSuccess());
-		assert executor.isSuccess();
 	}
-}
+}

src/test/java/com/imyeyu/java/ObservableTest.java

@@ -1,4 +1,4 @@
-package test;
+package com.imyeyu.java;
 
 import com.imyeyu.java.obs.ObservableList;
 import com.imyeyu.java.obs.ObservableMap;
@@ -7,12 +7,18 @@ import org.junit.jupiter.api.Test;
 
 import java.util.List;
 
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+
 /**
+ * 可观察对象相关测试
+ *
  * @author 夜雨
  * @since 2024-09-01 23:26
  */
-public class TestObs {
+public class ObservableTest {
 
+	/** 验证可观察字符串赋值后值会更新 */
 	@Test
 	public void testString() {
 		ObservableString obsString = new ObservableString("test1");
@@ -20,9 +26,10 @@ public class TestObs {
 		obsString.addListener((from, to) -> System.out.printf("from %s to %s%n", from, to));
 		obsString.set("test2");
 		System.out.println("now value = " + obsString);
-		assert obsString.get().equals("test2");
+		assertEquals("test2", obsString.get());
 	}
 
+	/** 验证可观察列表在多次增删后的最终状态 */
 	@Test
 	public void testList() {
 		ObservableList<String> list = new ObservableList<>();
@@ -40,8 +47,10 @@ public class TestObs {
 		list.removeAll(List.of("test3", "test4"));
 		list.removeIf(item -> item.equals("test1")); // 移除 0, 1, 2, 3, 4
 		System.out.println(list);
+		assertEquals(List.of("test5", "test7", "test8"), list);
 	}
 
+	/** 验证可观察映射在新增、更新与删除后的最终状态 */
 	@Test
 	public void testMap() {
 		ObservableMap<String, String> map = new ObservableMap<>();
@@ -56,5 +65,11 @@ public class TestObs {
 		map.remove("t1");
 		map.remove("t2", "test2");
 		System.out.println(map);
+		assertEquals(3, map.size());
+		assertEquals("test3", map.get("t3"));
+		assertEquals("test4", map.get("t4"));
+		assertEquals("test5", map.get("t5"));
+		assertFalse(map.containsKey("t1"));
+		assertFalse(map.containsKey("t2"));
 	}
 }

src/test/java/com/imyeyu/java/RefTest.java

@@ -0,0 +1,109 @@
+package com.imyeyu.java;
+
+import com.imyeyu.java.ref.Ref;
+import com.imyeyu.java.ref.RefField;
+import lombok.Data;
+import org.junit.jupiter.api.Test;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+
+/**
+ * 反射工具相关测试
+ *
+ * @author 夜雨
+ * @since 2024-04-26 11:05
+ */
+@Data
+public class RefTest {
+
+	/** 布尔字段，使用 is 前缀 */
+	private boolean isBoy;
+	/** 布尔字段，不使用 is 前缀 */
+	private boolean boy;
+	/** 普通字符串字段 */
+	private String fieldName;
+
+	/** 验证字段名标准化转换规则 */
+	@Test
+	public void test() {
+		String t1 = Ref.getFieldName("is-boy");
+		assertEquals("isBoy", t1);
+		String t2 = Ref.getFieldName("is_boy");
+		assertEquals("isBoy", t2);
+		String t3 = Ref.getFieldName("is boy");
+		assertEquals("isBoy", t3);
+		String t4 = Ref.getFieldName("isBoy");
+		assertEquals("isBoy", t4);
+		String t5 = Ref.getFieldName("boy");
+		assertEquals("boy", t5);
+		String t6 = Ref.getFieldName("fieldName");
+		assertEquals("fieldName", t6);
+		String t7 = Ref.getFieldName("field name");
+		assertEquals("fieldName", t7);
+		String t8 = Ref.getFieldName("field-Name");
+		assertEquals("fieldName", t8);
+		String t9 = Ref.getFieldName("field_Name");
+		assertEquals("fieldName", t9);
+	}
+
+	/** 验证布尔字段 is-boy 能映射到标准 getter/setter */
+	@Test
+	public void refBooleanField() {
+		RefField refField = Ref.field(RefTest.class, "is-boy");
+		assertNotNull(refField.getSetter());
+		assertEquals("setBoy", refField.getSetter().getName());
+		assertNotNull(refField.getGetter());
+		assertEquals("isBoy", refField.getGetter().getName());
+	}
+
+	/** 验证布尔字段 boy 能映射到标准 getter/setter */
+	@Test
+	public void refBoolean2Field() {
+		RefField refField = Ref.field(RefTest.class, "boy");
+		assertNotNull(refField.getSetter());
+		assertEquals("setBoy", refField.getSetter().getName());
+		assertNotNull(refField.getGetter());
+		assertEquals("isBoy", refField.getGetter().getName());
+	}
+
+	/** 验证字段名 fieldName 能映射到标准 getter/setter */
+	@Test
+	public void refStringField() {
+		RefField refField = Ref.field(RefTest.class, "fieldName");
+		assertNotNull(refField.getSetter());
+		assertEquals("setFieldName", refField.getSetter().getName());
+		assertNotNull(refField.getGetter());
+		assertEquals("getFieldName", refField.getGetter().getName());
+	}
+
+	/** 验证字段名 field-name 能映射到标准 getter/setter */
+	@Test
+	public void refString2Field() {
+		RefField refField = Ref.field(RefTest.class, "field-name");
+		assertNotNull(refField.getSetter());
+		assertEquals("setFieldName", refField.getSetter().getName());
+		assertNotNull(refField.getGetter());
+		assertEquals("getFieldName", refField.getGetter().getName());
+	}
+
+	/** 验证字段名 field_name 能映射到标准 getter/setter */
+	@Test
+	public void refString3Field() {
+		RefField refField = Ref.field(RefTest.class, "field_name");
+		assertNotNull(refField.getSetter());
+		assertEquals("setFieldName", refField.getSetter().getName());
+		assertNotNull(refField.getGetter());
+		assertEquals("getFieldName", refField.getGetter().getName());
+	}
+
+	/** 验证字段名 field name 能映射到标准 getter/setter */
+	@Test
+	public void refString4Field() {
+		RefField refField = Ref.field(RefTest.class, "field name");
+		assertNotNull(refField.getSetter());
+		assertEquals("setFieldName", refField.getSetter().getName());
+		assertNotNull(refField.getGetter());
+		assertEquals("getFieldName", refField.getGetter().getName());
+	}
+}

src/test/java/com/imyeyu/java/TimiJavaTest.java

@@ -0,0 +1,87 @@
+package com.imyeyu.java;
+
+import org.junit.jupiter.api.Test;
+
+import java.util.Collections;
+import java.util.List;
+import java.util.Map;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertIterableEquals;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertNull;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+/**
+ * {@link TimiJava} 静态工具方法测试
+ *
+ * @author 夜雨
+ * @since 2026-04-27 10:00
+ */
+public class TimiJavaTest {
+
+	/** 验证 isEmpty 与 isNotEmpty 的主要判空分支 */
+	@Test
+	public void testEmptyCheck() {
+		assertTrue(TimiJava.isEmpty(null));
+		assertTrue(TimiJava.isEmpty(""));
+		assertTrue(TimiJava.isEmpty(" "));
+		assertTrue(TimiJava.isEmpty(Collections.emptyList()));
+		assertTrue(TimiJava.isEmpty(Collections.emptyMap()));
+		assertFalse(TimiJava.isEmpty("value"));
+		assertTrue(TimiJava.isNotEmpty("value"));
+	}
+
+	/** 验证 defaultIfNull 与 defaultIfEmpty 返回默认值逻辑 */
+	@Test
+	public void testDefaultValue() {
+		assertEquals("default", TimiJava.defaultIfNull(null, "default"));
+		assertEquals("value", TimiJava.defaultIfNull("value", "default"));
+		assertEquals("default", TimiJava.defaultIfEmpty(" ", "default"));
+		assertEquals("value", TimiJava.defaultIfEmpty("value", "default"));
+	}
+
+	/** 验证 firstNotNull 与 firstNotEmpty 的首个命中逻辑 */
+	@Test
+	public void testFirstValue() {
+		assertEquals("v1", TimiJava.firstNotNull(null, "v1", "v2"));
+		assertNull(TimiJava.firstNotNull(null, null));
+		assertEquals("v1", TimiJava.firstNotEmpty("", " ", "v1", "v2"));
+		assertNull(TimiJava.firstNotEmpty("", " ", null));
+	}
+
+	/** 验证异常序列化结果包含异常类型与消息 */
+	@Test
+	public void testSerializeThrowable() {
+		String text = TimiJava.serializeThrowable(new IllegalArgumentException("bad"));
+		assertTrue(text.contains(IllegalArgumentException.class.getName()));
+		assertTrue(text.contains("bad"));
+	}
+
+	/** 验证 safeIterable 在空值与非空场景下都可安全迭代 */
+	@Test
+	public void testSafeIterable() {
+		Iterable<String> empty = TimiJava.safeIterable(null);
+		assertNotNull(empty);
+		assertFalse(empty.iterator().hasNext());
+
+		Iterable<String> values = TimiJava.safeIterable(List.of("a", "b"));
+		assertIterableEquals(List.of("a", "b"), values);
+	}
+
+	/** 验证 ZERO_UUID 常量值 */
+	@Test
+	public void testZeroUuid() {
+		assertEquals("00000000-0000-0000-0000-000000000000", TimiJava.ZERO_UUID);
+	}
+
+	/** 验证数组和映射判空路径 */
+	@Test
+	public void testArrayAndMapEmptyCheck() {
+		assertTrue(TimiJava.isEmpty(new String[]{}));
+		assertFalse(TimiJava.isEmpty(new String[]{"v"}));
+		assertTrue(TimiJava.isEmpty(Map.of()));
+		assertFalse(TimiJava.isEmpty(Map.of("k", "v")));
+	}
+}

src/test/java/test/TestRef.java

@@ -1,96 +0,0 @@
-package test;
-
-import com.imyeyu.java.ref.Ref;
-import com.imyeyu.java.ref.RefField;
-import org.junit.jupiter.api.Test;
-
-/**
- * @author 夜雨
- * @since 2024-04-26 11:05
- */
-public class TestRef {
-
-	private boolean isBoy;
-	private boolean boy;
-	private String fieldName;
-
-	@Test
-	public void test() {
-		String t1 = Ref.getFieldName("is-boy");
-		assert t1.equals("isBoy");
-		String t2 = Ref.getFieldName("is_boy");
-		assert t2.equals("isBoy");
-		String t3 = Ref.getFieldName("is boy");
-		assert t3.equals("isBoy");
-		String t4 = Ref.getFieldName("isBoy");
-		assert t4.equals("isBoy");
-		String t5 = Ref.getFieldName("boy");
-		assert t5.equals("boy");
-		String t6 = Ref.getFieldName("fieldName");
-		assert t6.equals("fieldName");
-		String t7 = Ref.getFieldName("field name");
-		assert t7.equals("fieldName");
-		String t8 = Ref.getFieldName("field-Name");
-		assert t8.equals("fieldName");
-		String t9 = Ref.getFieldName("field_Name");
-		assert t9.equals("fieldName");
-	}
-
-	@Test
-	public void refBooleanField() {
-		RefField refField = Ref.field(TestRef.class, "is-boy");
-		assert refField.getSetter() != null && refField.getSetter().getName().equals("setBoy");
-		assert refField.getGetter() != null && refField.getGetter().getName().equals("isBoy");
-	}
-
-	@Test
-	public void refBoolean2Field() {
-		RefField refField = Ref.field(TestRef.class, "boy");
-		assert refField.getSetter() != null && refField.getSetter().getName().equals("setBoy");
-		assert refField.getGetter() != null && refField.getGetter().getName().equals("isBoy");
-	}
-
-	@Test
-	public void refStringField() {
-		RefField refField = Ref.field(TestRef.class, "fieldName");
-		assert refField.getSetter() != null && refField.getSetter().getName().equals("setFieldName");
-		assert refField.getGetter() != null && refField.getGetter().getName().equals("getFieldName");
-	}
-
-	@Test
-	public void refString2Field() {
-		RefField refField = Ref.field(TestRef.class, "field-name");
-		assert refField.getSetter() != null && refField.getSetter().getName().equals("setFieldName");
-		assert refField.getGetter() != null && refField.getGetter().getName().equals("getFieldName");
-	}
-
-	@Test
-	public void refString3Field() {
-		RefField refField = Ref.field(TestRef.class, "field_name");
-		assert refField.getSetter() != null && refField.getSetter().getName().equals("setFieldName");
-		assert refField.getGetter() != null && refField.getGetter().getName().equals("getFieldName");
-	}
-
-	@Test
-	public void refString4Field() {
-		RefField refField = Ref.field(TestRef.class, "field name");
-		assert refField.getSetter() != null && refField.getSetter().getName().equals("setFieldName");
-		assert refField.getGetter() != null && refField.getGetter().getName().equals("getFieldName");
-	}
-
-	public boolean isBoy() {
-		return isBoy;
-	}
-
-	public void setBoy(boolean boy) {
-		isBoy = boy;
-	}
-
-	public String getFieldName() {
-		return fieldName;
-	}
-
-	public void setFieldName(String fieldName) {
-		this.fieldName = fieldName;
-	}
-}