Merge pull request 'v0.0.2' (#1) from dev into master

Reviewed-on: #1

.gitea/workflows/ci.yml

@@ -0,0 +1,111 @@
+name: CI/CD
+
+on:
+  pull_request:
+    branches:
+      - master
+    types:
+      - closed
+
+jobs:
+  build-deploy:
+    runs-on: act_runner_java
+    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 }}
+          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

.gitignore

@@ -1,3 +1,7 @@
+/.claude
+/CLAUDE.md
+/AGENTS.md
+
 target/
 !.mvn/wrapper/maven-wrapper.jar
 !**/src/main/**/target/

pom.xml

@@ -27,29 +27,11 @@
 				<groupId>org.apache.maven.plugins</groupId>
 				<artifactId>maven-source-plugin</artifactId>
 				<version>3.3.1</version>
-				<executions>
-					<execution>
-						<id>attach-sources</id>
-						<phase>package</phase>
-						<goals>
-							<goal>jar-no-fork</goal>
-						</goals>
-					</execution>
-				</executions>
 			</plugin>
 			<plugin>
 				<groupId>org.apache.maven.plugins</groupId>
 				<artifactId>maven-javadoc-plugin</artifactId>
 				<version>3.11.2</version>
-				<executions>
-					<execution>
-						<id>attach-javadocs</id>
-						<phase>package</phase>
-						<goals>
-							<goal>jar</goal>
-						</goals>
-					</execution>
-				</executions>
 			</plugin>
 		</plugins>
 	</build>

src/main/java/com/imyeyu/lang/mapper/AbstractLanguageMapper.java

@@ -7,35 +7,69 @@ import com.imyeyu.utils.StringInterpolator;
 import java.util.Map;
 
 /**
+ * 抽象语言映射器，提供语言映射的基础实现，提供字符串插值、调试模式等基础功能
+ *
  * @author 夜雨
  * @version 2024-04-01 16:25
  */
 public abstract class AbstractLanguageMapper implements LanguageMapping {
 
+	/** 字符串插值器，用于处理占位符替换 */
 	protected final StringInterpolator INTERPOLATOR = StringInterpolator.createDollarInterpolator();
 
-	protected final Language language;
+	/** 当前映射器所属语言 */
+	protected final Language.Enum language;
 
+	/** 是否启用调试模式，启用后将抛出异常而不是返回默认值 */
 	protected boolean isDebugging = false;
 
-	public AbstractLanguageMapper(Language language) {
+	/**
+	 * 构造语言映射器
+	 *
+	 * @param language 所属语言
+	 */
+	public AbstractLanguageMapper(Language.Enum language) {
 		this.language = language;
 	}
 
-	public Language getLanguage() {
+	/**
+	 * 获取当前映射器所属语言
+	 *
+	 * @return 语言枚举
+	 */
+	public Language.Enum getLanguage() {
 		return language;
 	}
 
+	/**
+	 * 设置调试模式，调试模式下，找不到映射时将抛出异常而不是返回默认值
+	 *
+	 * @param debugging true 为启用调试模式
+	 */
 	public void setDebugging(boolean debugging) {
 		isDebugging = debugging;
 	}
 
+	/**
+	 * 获取文本
+	 *
+	 * @param key 键
+	 * @param def 默认值（没有找到映射值时）
+	 * @return 获取结果
+	 */
 	@Override
 	public String text(String key, String def) {
 		String result = text(key);
 		return result.equals(key) ? def : result;
 	}
 
+	/**
+	 * 插入参数获取文本，使用 ${key} 格式进行占位符替换
+	 *
+	 * @param key  键
+	 * @param args 参数映射表
+	 * @return 替换占位符后的文本
+	 */
 	@Override
 	public String textArgs(String key, Map<String, Object> args) {
 		return INTERPOLATOR.inject(text(key), args);

src/main/java/com/imyeyu/lang/mapper/FileLanguageMap.java

@@ -8,6 +8,8 @@ import java.io.InputStreamReader;
 import java.util.Properties;
 
 /**
+ * 文件语言映射
+ *
  * @author 夜雨
  * @version 2024-04-09 01:00
  */
@@ -18,10 +20,15 @@ public class FileLanguageMap extends PropertiesLanguageMap {
 	 *
 	 * @param language 所属语言
 	 */
-	public FileLanguageMap(Language language) {
+	public FileLanguageMap(Language.Enum language) {
 		super(language);
 	}
 
+	/**
+	 * 加载资源文件，格式化 % 为 {@link Language.Enum#toString()}，示例：lang/app_%s.lang
+	 *
+	 * @param path 路径
+	 */
 	public void load(String path) {
 		try {
 			InputStream is = IO.getInputStream(path.formatted(language.toString()));

src/main/java/com/imyeyu/lang/mapper/LanguageMap.java

@@ -10,13 +10,20 @@ import java.util.LinkedHashMap;
 import java.util.Map;
 
 /**
+ * 基于内存的语言映射实现
+ * <p>
+ * 使用 HashMap 存储语言映射关系，支持二次映射、模糊匹配等功能
+ * </p>
+ *
  * @author 夜雨
  * @version 2024-04-03 10:11
  */
 public class LanguageMap extends AbstractLanguageMapper {
 
+	/** 语言键值映射表 */
 	protected final Map<String, String> map;
 
+	// 初始化字符串插值器过滤器，支持 @key 格式的语言映射引用
 	{
 		INTERPOLATOR.putFilter("lang", value -> {
 			if (value.startsWith("@")) {
@@ -31,20 +38,40 @@ public class LanguageMap extends AbstractLanguageMapper {
 	 *
 	 * @param language 所属语言
 	 */
-	public LanguageMap(Language language) {
+	public LanguageMap(Language.Enum language) {
 		super(language);
 		this.map = new HashMap<>();
 	}
 
+	/**
+	 * 合并另一个语言映射表
+	 * <p>
+	 * 将另一个映射表的所有键值对合并到当前映射表中，如果存在相同键则覆盖
+	 * </p>
+	 *
+	 * @param map 要合并的语言映射表
+	 */
 	public void union(LanguageMap map) {
 		this.map.putAll(map.map);
 	}
 
+	/**
+	 * 添加语言映射
+	 *
+	 * @param key   键
+	 * @param value 值
+	 */
 	@Override
 	public void add(String key, String value) {
 		map.put(key, value);
 	}
 
+	/**
+	 * 检查是否存在指定键的映射
+	 *
+	 * @param key 键
+	 * @return true 为存在
+	 */
 	@Override
 	public boolean has(String key) {
 		return map.containsKey(key);

src/main/java/com/imyeyu/lang/mapper/PropertiesLanguageMap.java

@@ -6,6 +6,8 @@ import java.util.HashMap;
 import java.util.Properties;
 
 /**
+ * 基于 Properties 的语言映射实现
+ *
  * @author 夜雨
  * @version 2024-04-09 00:50
  */
@@ -16,10 +18,15 @@ public class PropertiesLanguageMap extends LanguageMap {
 	 *
 	 * @param language 所属语言
 	 */
-	public PropertiesLanguageMap(Language language) {
+	public PropertiesLanguageMap(Language.Enum language) {
 		super(language);
 	}
 
+	/**
+	 * 从 Properties 对象加载语言映射数据
+	 *
+	 * @param properties 属性对象
+	 */
 	@SuppressWarnings({"unchecked", "rawtypes"})
 	public void load(Properties properties) {
 		map.putAll(new HashMap(properties));

src/main/java/com/imyeyu/lang/mapper/ResourcesLanguageMap.java

@@ -9,19 +9,27 @@ import java.io.InputStreamReader;
 import java.util.Properties;
 
 /**
+ * 资源文件语言映射
+ *
  * @author 夜雨
  * @version 2024-04-09 00:55
  */
 public class ResourcesLanguageMap extends PropertiesLanguageMap {
+
 	/**
 	 * 默认构造
 	 *
 	 * @param language 所属语言
 	 */
-	public ResourcesLanguageMap(Language language) {
+	public ResourcesLanguageMap(Language.Enum language) {
 		super(language);
 	}
 
+	/**
+	 * 加载资源文件，格式化 % 为 {@link Language.Enum#toString()}，示例：lang/app_%s.lang
+	 *
+	 * @param path 路径
+	 */
 	public void load(String path) {
 		try {
 			InputStream is = IO.resourceToInputStream(getClass(), path.formatted(language.toString()));

src/main/java/com/imyeyu/lang/multi/FileMultilingual.java

@@ -6,13 +6,36 @@ import com.imyeyu.lang.mapper.FileLanguageMap;
 import com.imyeyu.lang.mapper.LanguageMap;
 
 /**
+ * 文件多语言实例，从文件系统加载多语言配置文件
+ *
  * @author 夜雨
  * @version 2024-04-09 01:06
  */
 public class FileMultilingual extends Multilingual {
 
+	public FileMultilingual() {
+	}
+
+	/**
+	 * 构造并批量加载所有支持的语言文件
+	 *
+	 * @param path 文件路径模板，使用 %s 作为语言代码占位符，例如：lang/app_%s.lang
+	 */
+	public FileMultilingual(String path) {
+		addAll(path);
+	}
+
+	/**
+	 * 批量加载所有支持的语言文件
+	 * <p>
+	 * 遍历 {@link Language.Enum} 中定义的所有语言，为每种语言创建对应的映射器并加载文件。
+	 * 如果已存在相同语言的映射器，则合并映射数据
+	 * </p>
+	 *
+	 * @param path 文件路径模板，使用 %s 作为语言代码占位符，例如：lang/app_%s.lang
+	 */
 	public void addAll(String path) {
-		Language[] values = Language.values();
+		Language.Enum[] values = Language.Enum.values();
 		for (int i = 0; i < values.length; i++) {
 			FileLanguageMap mapper = new FileLanguageMap(values[i]);
 			mapper.load(path);

src/main/java/com/imyeyu/lang/multi/Multilingual.java

@@ -42,26 +42,42 @@ import java.util.Objects;
  */
 public class Multilingual implements LanguageMapping {
 
-	protected final Map<Language, AbstractLanguageMapper> multilingualMap;
+	/** 多语言映射表，存储各语言对应的映射器 */
-	protected final List<CallbackArg<Language>> updateActiveListeners;
+	protected final Map<Language.Enum, AbstractLanguageMapper> multilingualMap;
+
+	/** 激活语言更新回调列表 */
+	protected final List<CallbackArg<Language.Enum>> updateActiveListeners;
 
 	/** 当前激活语言 */
-	protected Language activated;
+	protected Language.Enum activated;
 
+	/** 是否启用调试模式 */
 	protected boolean isDebugging = false;
 
+	/**
+	 * 默认构造
+	 * <p>
+	 * 根据系统默认 Locale 初始化激活语言，如果无法识别则默认为中文
+	 * </p>
+	 */
 	public Multilingual() {
 		multilingualMap = new HashMap<>();
 		updateActiveListeners = new ArrayList<>();
 
-		activated = Ref.toType(Language.class, Locale.getDefault().toString());
+		activated = Ref.toType(Language.Enum.class, Locale.getDefault().toString());
 
 		if (activated == null) {
-			activated = Language.zh_CN;
+			activated = Language.Enum.zh_CN;
 		}
 	}
 
-	public void add(Language language, AbstractLanguageMapper mapper) {
+	/**
+	 * 添加语言映射器
+	 *
+	 * @param language 语言
+	 * @param mapper   语言映射器
+	 */
+	public void add(Language.Enum language, AbstractLanguageMapper mapper) {
 		mapper.setDebugging(isDebugging);
 		multilingualMap.put(language, mapper);
 	}
@@ -71,7 +87,7 @@ public class Multilingual implements LanguageMapping {
 	 *
 	 * @param callback 回调
 	 */
-	public void addUpdateActiveListeners(CallbackArg<Language> callback) {
+	public void addUpdateActiveListeners(CallbackArg<Language.Enum> callback) {
 		updateActiveListeners.add(callback);
 	}
 
@@ -90,7 +106,7 @@ public class Multilingual implements LanguageMapping {
 	 * @param languageName 激活语言
 	 */
 	public void setActivated(String languageName) {
-		setActivated(Ref.toType(Language.class, languageName));
+		setActivated(Ref.toType(Language.Enum.class, languageName));
 	}
 
 	/**
@@ -98,7 +114,7 @@ public class Multilingual implements LanguageMapping {
 	 *
 	 * @param activated 激活语言
 	 */
-	public void setActivated(Language activated) {
+	public void setActivated(Language.Enum activated) {
 		Objects.requireNonNull(activated);
 		this.activated = activated;
 
@@ -110,13 +126,26 @@ public class Multilingual implements LanguageMapping {
 		}
 	}
 
-	public Language getActivated() {
+	/**
+	 * 获取当前激活的语言
+	 *
+	 * @return 当前激活语言
+	 */
+	public Language.Enum getActivated() {
 		return activated;
 	}
 
+	/**
+	 * 设置调试模式
+	 * <p>
+	 * 同时会将所有已加载的语言映射器设置为调试模式
+	 * </p>
+	 *
+	 * @param debugging true 为启用调试模式
+	 */
 	public void setDebugging(boolean debugging) {
 		isDebugging = debugging;
-		for (Map.Entry<Language, AbstractLanguageMapper> item : multilingualMap.entrySet()) {
+		for (Map.Entry<Language.Enum, AbstractLanguageMapper> item : multilingualMap.entrySet()) {
 			item.getValue().setDebugging(true);
 		}
 	}
@@ -128,7 +157,7 @@ public class Multilingual implements LanguageMapping {
 	 * @return 映射表
 	 */
 	public AbstractLanguageMapper map(String lang) {
-		Language language = Ref.toType(Language.class, lang);
+		Language.Enum language = Ref.toType(Language.Enum.class, lang);
 		if (language == null) {
 			throw new RuntimeException("not support language: " + lang);
 		}
@@ -141,10 +170,16 @@ public class Multilingual implements LanguageMapping {
 	 * @param lang 语言
 	 * @return 映射表
 	 */
-	public AbstractLanguageMapper map(Language lang) {
+	public AbstractLanguageMapper map(Language.Enum lang) {
 		return multilingualMap.get(lang);
 	}
 
+	/**
+	 * 向当前激活语言的映射表添加键值对
+	 *
+	 * @param key   键
+	 * @param value 值
+	 */
 	@Override
 	public void add(String key, String value) {
 		multilingualMap.get(getActivated()).add(key, value);

src/main/java/com/imyeyu/lang/multi/ResourcesMultilingual.java

@@ -6,13 +6,39 @@ import com.imyeyu.lang.mapper.LanguageMap;
 import com.imyeyu.lang.mapper.ResourcesLanguageMap;
 
 /**
+ * 资源文件多语言实例
+ * <p>
+ * 从 classpath 资源文件加载多语言配置
+ * </p>
+ *
  * @author 夜雨
  * @version 2024-04-09 01:03
  */
 public class ResourcesMultilingual extends Multilingual {
 
+	public ResourcesMultilingual() {
+	}
+
+	/**
+	 * 构造并批量加载所有支持的语言资源文件
+	 *
+	 * @param path 资源文件路径模板，使用 %s 作为语言代码占位符，例如：lang/app_%s.lang
+	 */
+	public ResourcesMultilingual(String path) {
+		addAll(path);
+	}
+
+	/**
+	 * 批量加载所有支持的语言资源文件
+	 * <p>
+	 * 遍历 {@link Language.Enum} 中定义的所有语言，为每种语言创建对应的映射器并从 classpath 加载资源。
+	 * 如果已存在相同语言的映射器，则合并映射数据
+	 * </p>
+	 *
+	 * @param path 资源文件路径模板，使用 %s 作为语言代码占位符，例如：lang/app_%s.lang
+	 */
 	public void addAll(String path) {
-		Language[] values = Language.values();
+		Language.Enum[] values = Language.Enum.values();
 		for (int i = 0; i < values.length; i++) {
 			ResourcesLanguageMap mapper = new ResourcesLanguageMap(values[i]);
 			mapper.load(path);

src/test/java/test/TestLang.java

@@ -14,7 +14,7 @@ public class TestLang {
 
 	@Test
 	public void testArgs() {
-		ResourcesLanguageMap map = new ResourcesLanguageMap(Language.zh_CN);
+		ResourcesLanguageMap map = new ResourcesLanguageMap(Language.Enum.zh_CN);
 		map.load("zh_CN.lang");
 		System.out.println(map.textArgs("test", Map.of("msg", "hello world")));
 	}