docs(guidelines): 更新编码指南并添加工作日志和开发工具文档

- 简化 AGENTS.md 文档结构，更新构建命令和代码风格指南 - 新增 2026 年 1 月工作日志记录项目进展和问题解决 - 添加 Cursor 连接 WSL 开发完整教程，涵盖环境配置和最佳实践 - 创建 SDKMAN Java 和 Maven 版本管理指南，支持多项目环境 - 编写 Windows Jabba Java 版本管理文档，提供 PowerShell 集成方案
2026-02-04 10:55:36 +08:00
parent 6d05134161
commit caae9fb69b
6 changed files with 1387 additions and 146 deletions
--- a/src/programming/backend/java/功能整理/SDKMAN-Java-Maven版本管理.md
+++ b/src/programming/backend/java/功能整理/SDKMAN-Java-Maven版本管理.md
@@ -0,0 +1,270 @@
+---
+title: 使用 SDKMAN 管理 Java 和 Maven 多版本
+icon: mdi:package-variant
+date: 2026-02-04
+category:
+  - 实用工具
+  - JAVA
+tag:
+  - SDKMAN
+  - Java
+  - Maven
+  - 版本管理
+---
+
+# 使用 SDKMAN 管理 Java 和 Maven 多版本方案
+
+在开发过程中，我们经常需要在不同的项目之间切换不同的 Java 和 Maven 版本。SDKMAN (Software Development Kit Manager) 是一个强大的工具，可以帮助我们轻松管理多个版本的软件开发工具包。
+
+<!-- more -->
+
+## 概述
+
+在开发过程中，我们经常需要在不同的项目之间切换不同的 Java 和 Maven 版本。SDKMAN (Software Development Kit Manager) 是一个强大的工具，可以帮助我们轻松管理多个版本的软件开发工具包。
+
+## 当前系统环境
+
+- **操作系统**: Linux
+- **当前 Java 版本**: OpenJDK 1.8.0_472 (Java 8)
+- **当前 Maven 版本**: Apache Maven 3.8.7
+- **SDKMAN 状态**: 需要安装
+
+## 安装 SDKMAN
+
+### 1. 下载并安装 SDKMAN
+
+```bash
+curl -s "https://get.sdkman.io" | bash
+```
+
+### 2. 初始化 SDKMAN
+
+```bash
+source "$HOME/.sdkman/bin/sdkman-init.sh"
+```
+
+### 3. 验证安装
+
+```bash
+sdk version
+```
+
+## 管理 Java 版本
+
+### 1. 查看可用的 Java 版本
+
+```bash
+sdk list java
+```
+
+### 2. 安装特定版本的 Java
+
+```bash
+# 安装 Java 11
+sdk install java 11.0.21-tem
+
+# 安装 Java 17 (LTS)
+sdk install java 17.0.9-tem
+
+# 安装 Java 21 (最新 LTS)
+sdk install java 21.0.1-tem
+
+# 安装 OpenJDK 版本
+sdk install java 8.0.382-tem
+```
+
+### 3. 切换 Java 版本
+
+```bash
+# 临时切换到 Java 11
+sdk use java 11.0.21-tem
+
+# 临时切换到 Java 17
+sdk use java 17.0.9-tem
+```
+
+### 4. 设置默认 Java 版本
+
+```bash
+sdk default java 17.0.9-tem
+```
+
+### 5. 查看当前使用的 Java 版本
+
+```bash
+sdk current java
+java -version
+```
+
+## 管理 Maven 版本
+
+### 1. 查看可用的 Maven 版本
+
+```bash
+sdk list maven
+```
+
+### 2. 安装特定版本的 Maven
+
+```bash
+# 安装 Maven 3.8.x
+sdk install maven 3.8.8
+
+# 安装 Maven 3.9.x
+sdk install maven 3.9.6
+```
+
+### 3. 切换 Maven 版本
+
+```bash
+sdk use maven 3.9.6
+```
+
+### 4. 设置默认 Maven 版本
+
+```bash
+sdk default maven 3.9.6
+```
+
+### 5. 查看当前使用的 Maven 版本
+
+```bash
+sdk current maven
+mvn -version
+```
+
+## 项目级版本管理
+
+SDKMAN 支持项目级别的版本管理，通过 `.sdkmanrc` 文件可以实现进入项目目录时自动切换到指定版本。
+
+### 1. 创建项目版本配置文件
+
+```bash
+# 在项目根目录创建 .sdkmanrc 文件
+cat > .sdkmanrc << EOF
+java=17.0.9-tem
+maven=3.9.6
+EOF
+```
+
+### 2. 启用项目版本环境
+
+```bash
+# 进入项目目录
+cd your-project
+
+# 激活项目配置的版本
+sdk env
+```
+
+### 3. 自动切换（可选）
+
+SDKMAN 可以配置为在进入包含 `.sdkmanrc` 文件的目录时自动切换版本。
+
+```bash
+# 启用自动切换
+sdk enable auto_env
+```
+
+## 常用 SDKMAN 命令
+
+### 1. 查看所有已安装的版本
+
+```bash
+sdk list installed
+```
+
+### 2. 查看特定工具的所有版本
+
+```bash
+sdk list java
+sdk list maven
+```
+
+### 3. 卸载不需要的版本
+
+```bash
+# 卸载 Java 11
+sdk uninstall java 11.0.21-tem
+
+# 卸载 Maven 3.8.8
+sdk uninstall maven 3.8.8
+```
+
+### 4. 更新 SDKMAN
+
+```bash
+sdk selfupdate
+```
+
+### 5. 查看帮助
+
+```bash
+sdk help
+```
+
+## 实际使用场景示例
+
+### 场景 1：新项目使用 Java 17 + Maven 3.9
+
+```bash
+cd new-project
+sdk use java 17.0.9-tem
+sdk use maven 3.9.6
+echo "java=17.0.9-tem" > .sdkmanrc
+echo "maven=3.9.6" >> .sdkmanrc
+```
+
+### 场景 2：维护旧项目使用 Java 8 + Maven 3.8
+
+```bash
+cd legacy-project
+sdk use java 8.0.382-tem
+sdk use maven 3.8.8
+echo "java=8.0.382-tem" > .sdkmanrc
+echo "maven=3.8.8" >> .sdkmanrc
+```
+
+### 场景 3：升级项目 Java 版本
+
+```bash
+cd project-to-upgrade
+# 从 Java 8 升级到 Java 17
+sdk install java 17.0.9-tem
+sdk use java 17.0.9-tem
+# 更新 .sdkmanrc 文件
+sed -i 's/java=.*/java=17.0.9-tem/' .sdkmanrc
+```
+
+## 最佳实践建议
+
+1. **保持系统 Java 版本最低**: 系统级别的 Java 保持为较低版本（如 Java 8），其他版本通过 SDKMAN 管理。
+
+2. **项目配置版本控制**: 将 `.sdkmanrc` 文件提交到版本控制系统，确保团队成员使用一致的开发环境。
+
+3. **定期清理不需要的版本**: 定期使用 `sdk list installed` 查看已安装版本，卸载不再使用的版本以节省磁盘空间。
+
+4. **文档化版本要求**: 在项目 README 文件中明确说明所需的 Java 和 Maven 版本。
+
+5. **测试环境一致性**: 开发、测试、生产环境尽量保持相同的版本配置。
+
+## 环境变量配置
+
+如果需要永久配置环境变量，可以在 `~/.bashrc` 或 `~/.zshrc` 中添加：
+
+```bash
+# SDKMAN 初始化
+export SDKMAN_DIR="$HOME/.sdkman"
+[[ -s "$SDKMAN_DIR/bin/sdkman-init.sh" ]] && source "$SDKMAN_DIR/bin/sdkman-init.sh"
+```
+
+## 总结
+
+SDKMAN 提供了一个优雅的解决方案来管理 Java 和 Maven 的多版本问题。通过合理使用 SDKMAN，我们可以：
+
+- 轻松在不同项目间切换版本
+- 避免版本冲突问题
+- 简化团队成员的环境配置
+- 提高开发效率和项目维护性
+
+建议所有需要处理多版本 Java 项目的开发者都使用 SDKMAN 进行版本管理。
--- a/src/programming/backend/java/功能整理/Windows-Jabba-Java版本管理.md
+++ b/src/programming/backend/java/功能整理/Windows-Jabba-Java版本管理.md
@@ -0,0 +1,405 @@
+---
+title: Windows 多版本 Java 环境管理（Jabba）
+icon: mdi:language-java
+date: 2026-02-04
+category:
+  - 实用工具
+  - JAVA
+tag:
+  - Jabba
+  - Java
+  - Windows
+  - 版本管理
+  - PowerShell
+---
+
+# Windows 多版本 Java 环境管理（Jabba）
+
+在 Windows 10 + PowerShell 环境下使用 Jabba 实现多版本 JDK 管理的完整指南。
+
+<!-- more -->
+
+## 1. 环境及目录约定
+
+- **操作系统**: Windows 10
+- **Shell**: PowerShell
+- **Jabba 安装目录**（手动方式）:
+  - 二进制: `C:\Users\<用户名>\.jabba\bin\jabba.exe`
+  - 脚本: `C:\Users\<用户名>\.jabba\jabba.ps1`
+- **本项目目录**（当前目录）:
+  - `C:\Users\<用户名>\Desktop\cursor\JAVA 版本管理`
+  - 内含辅助脚本，例如 `use-java.ps1`、本说明文件 `JAVA_ENV_SETUP.md`。
+
+> 下文中的 `<用户名>` 对应你本机的 Windows 用户名，例如 `a3621`。
+
+---
+
+## 2. Jabba 手动安装与集成
+
+### 2.1 放置 Jabba 可执行文件
+
+1. 使用浏览器下载 Jabba Windows 版本（例如 `jabba-0.14.0-windows-amd64.exe`）。
+2. 在资源管理器中创建目录:
+   - `C:\Users\<用户名>\.jabba\bin\`
+3. 将下载的 EXE 重命名为:
+   - `jabba.exe`
+4. 移动到:
+   - `C:\Users\<用户名>\.jabba\bin\jabba.exe`
+
+### 2.2 创建 `jabba.ps1` 包装脚本
+
+1. 打开 PowerShell，执行:
+
+   ```powershell
+   notepad "$env:USERPROFILE\.jabba\jabba.ps1"
+   ```
+
+2. 在文件中填入如下内容（如已存在可覆盖）:
+
+   ```powershell
+   $env:JABBA_HOME="$env:USERPROFILE\.jabba"
+
+   function jabba
+   {
+     $fd3=$([System.IO.Path]::GetTempFileName())
+     $command="& '$env:JABBA_HOME\bin\jabba.exe' $args --fd3 `"$fd3`""
+     & { $env:JABBA_SHELL_INTEGRATION="ON"; Invoke-Expression $command }
+     $fd3content=$(Get-Content $fd3)
+     if ($fd3content) {
+       $expression=$fd3content.replace("export ","`$env:").replace("unset ","Remove-Item env:") -join "`n"
+       if (-not $expression -eq "") { Invoke-Expression $expression }
+     }
+     Remove-Item -Force $fd3
+   }
+   ```
+
+3. 保存并关闭记事本。
+
+### 2.3 在 PowerShell Profile 中自动加载 Jabba
+
+1. 打开 PowerShell Profile:
+
+   ```powershell
+   notepad $PROFILE
+   ```
+
+2. 在文件末尾追加（若已有同类行则无需重复）:
+
+   ```powershell
+   if (Test-Path "$env:USERPROFILE\.jabba\jabba.ps1") { . "$env:USERPROFILE\.jabba\jabba.ps1" }
+   ```
+
+3. 保存，关闭 PowerShell 窗口，重新打开一个新的 PowerShell。
+
+4. 验证:
+
+   ```powershell
+   jabba --version
+   ```
+
+   若能输出版本号（例如 `0.14.0`），说明 Jabba 配置成功。
+
+---
+
+## 3. 使用 Jabba 管理多版本 JDK
+
+### 3.1 查看可用 JDK 版本
+
+```powershell
+jabba ls-remote
+jabba ls-remote temurin
+```
+
+### 3.2 安装常用 LTS 版本（示例: 8 / 11 / 17）
+
+```powershell
+jabba install temurin@17
+jabba install temurin@11
+jabba install temurin@8
+```
+
+安装完成后查看本机已安装的 JDK 列表:
+
+```powershell
+jabba ls
+```
+
+### 3.3 在当前终端会话切换 JDK 版本
+
+```powershell
+jabba use temurin@17
+java -version
+```
+
+`java -version` 应显示对应版本（例如 `openjdk version "17.x.y"`）。
+
+---
+
+## 4. 配置"全局默认" JDK 版本
+
+若希望每次打开 PowerShell 都默认使用某个版本（例如 17），可在 Profile 中配置:
+
+1. 在任意 PowerShell 会话中确认要用的版本，例如:
+
+   ```powershell
+   jabba use temurin@17
+   ```
+
+2. 打开 Profile:
+
+   ```powershell
+   notepad $PROFILE
+   ```
+
+3. 在末尾追加:
+
+   ```powershell
+   jabba use temurin@17
+   ```
+
+4. 保存并重启 PowerShell，验证:
+
+   ```powershell
+   java -version
+   ```
+
+此时新开终端应默认是 JDK 17。
+
+---
+
+## 5. 项目级 Java 版本管理（`.jabbarc` + `use-java.ps1`）
+
+### 5.1 `.jabbarc` 约定
+
+在每个 Java 项目根目录创建 `.jabbarc` 文件，内容为希望使用的 Jabba 版本，例如:
+
+```text
+temurin@17
+```
+
+老项目如需 Java 8:
+
+```text
+temurin@8
+```
+
+> 规则: `.jabbarc` 第一行非空内容即为要使用的版本字符串，与 `jabba ls` 中的名称一致。
+
+### 5.2 通用脚本 `use-java.ps1`
+
+在当前目录 `JAVA 版本管理` 下建议放一个通用脚本 `use-java.ps1`，典型实现如下:
+
+```powershell
+param(
+    [string]$ProjectPath = "."
+)
+
+$fullPath = (Resolve-Path $ProjectPath).Path
+$jabbarc = Join-Path $fullPath ".jabbarc"
+
+if (!(Test-Path $jabbarc)) {
+    Write-Host "未找到 .jabbarc 文件：$jabbarc"
+    exit 1
+}
+
+$version = (Get-Content $jabbarc | Where-Object { $_ -ne "" } | Select-Object -First 1).Trim()
+
+if (-not $version) {
+    Write-Host ".jabbarc 里没有有效版本号"
+    exit 1
+}
+
+Write-Host "切换到 JDK 版本：$version"
+jabba use $version
+
+Write-Host "当前 java 版本："
+java -version
+```
+
+> 实际脚本内容可根据需要微调，只要遵循"读取 `.jabbarc` → 调用 `jabba use`"的逻辑即可。
+
+### 5.3 使用方式示例
+
+假设有项目 `D:\Projects\MyApp`，根目录已放置 `.jabbarc`:
+
+```powershell
+cd "D:\Projects\MyApp"
+
+# 从当前目录调用公共脚本（路径根据实际情况调整）
+powershell -ExecutionPolicy Bypass -File "C:\Users\<用户名>\Desktop\cursor\JAVA 版本管理\use-java.ps1" .
+```
+
+执行后，当前终端的 `JAVA_HOME` 和 `PATH` 将切换到 `.jabbarc` 指定的 JDK，随后在该终端内运行的 `java` / `javac` / `mvn` / `gradlew` 都会使用这个版本。
+
+### 5.4 进阶：cd 自动检测 `.jabbarc`（类似 direnv）
+
+若希望**一进入带 `.jabbarc` 的目录就自动切换 JDK**，无需再手动执行 `use-java.ps1`，可在 PowerShell Profile 中增加下面逻辑。
+
+**行为说明：**
+
+- 每次执行 `cd`（或 `Set-Location`）后，从当前目录向上逐级查找 `.jabbarc`。
+- 找到则读取其中版本并执行 `jabba use <版本>`，当前终端即使用该 JDK。
+- 若当前路径及所有父目录都没有 `.jabbarc`，不修改 JDK（保持上一次的版本）。
+
+**实现步骤：**
+
+1. 打开 Profile：
+   ```powershell
+   notepad $PROFILE
+   ```
+2. 在**已加载 Jabba 的语句之后**（例如在 `jabba use temurin@17` 之后），追加下面整段代码并保存：
+
+```powershell
+# ----- 自动根据 .jabbarc 切换 JDK（direnv 风格） -----
+function Invoke-JabbaAutoUse {
+    $current = Get-Location
+    while ($current -and $current.Path) {
+        $jabbarc = Join-Path $current.Path ".jabbarc"
+        if (Test-Path -LiteralPath $jabbarc -PathType Leaf) {
+            $version = (Get-Content -LiteralPath $jabbarc -Raw -ErrorAction SilentlyContinue).Trim()
+            $version = ($version -split "`n" | ForEach-Object { $_.Trim() } | Where-Object { $_ -ne "" } | Select-Object -First 1)
+            if ($version) {
+                jabba use $version 2>$null
+            }
+            return
+        }
+        $parent = Split-Path $current.Path -Parent
+        if (-not $parent -or $parent -eq $current.Path) { break }
+        $current = Get-Item -LiteralPath $parent -ErrorAction SilentlyContinue
+    }
+}
+
+# 用包装函数替代内置 cd，使每次切换目录后自动检测 .jabbarc
+function Set-LocationWithJabba {
+    [CmdletBinding(DefaultParameterSetName = "Path")]
+    param(
+        [Parameter(ParameterSetName = "Path", Position = 0)]
+        [string]$Path,
+        [Parameter(ParameterSetName = "LiteralPath")]
+        [string]$LiteralPath,
+        [switch]$PassThru
+    )
+    if ($PSCmdlet.ParameterSetName -eq "LiteralPath" -and $LiteralPath) {
+        Set-Location -LiteralPath $LiteralPath
+    } elseif ($Path) {
+        Set-Location -Path $Path
+    } else {
+        Set-Location $env:USERPROFILE
+    }
+    if ($PassThru) { Get-Location }
+    Invoke-JabbaAutoUse
+}
+Set-Alias -Name cd -Value Set-LocationWithJabba -Force -Option AllScope
+# ----- 以上为自动 .jabbarc 检测 -----
+```
+
+3. 关闭并重新打开 PowerShell，使 Profile 生效。
+
+**使用方式：**
+
+```powershell
+cd D:\Projects\MyApp    # 若 MyApp 或其父目录有 .jabbarc，会自动 jabba use
+java -version           # 已是 .jabbarc 中指定的版本
+```
+
+**注意：**
+
+- 仅对**当前会话**中通过 `cd` 的切换生效；新开终端仍会先应用 Profile 里的默认 `jabba use`，再在第一次 `cd` 到带 `.jabbarc` 的目录时自动切换。
+- 若使用 `Set-Location`（或 `sl`）切换目录，不会触发自动检测；可在切换后手动执行 `Invoke-JabbaAutoUse` 或 `use-java.ps1`。
+- 若不需要自动检测，可删除 Profile 中上述整段"自动 .jabbarc 检测"代码，继续使用手动执行 `use-java.ps1` 的方式。
+
+---
+
+## 6. Maven / Gradle 与 JDK 版本
+
+### 6.1 Maven
+
+在执行 Maven 命令前，通过 Jabba 或 `use-java.ps1` 先切好版本:
+
+```powershell
+jabba use temurin@17           # 或 use-java.ps1 ...
+mvn -version                   # 确认使用的 JAVA_HOME
+mvn clean package
+```
+
+- Maven 默认读取当前会话的 `JAVA_HOME` / `PATH`，无需额外配置。
+
+### 6.2 Gradle / Gradle Wrapper
+
+同样原则，先设置好 JDK:
+
+```powershell
+jabba use temurin@11
+.\gradlew -version
+.\gradlew build
+```
+
+如需强制某项目永远使用固定 JDK，可在该项目 `gradle.properties` 中加入:
+
+```properties
+org.gradle.java.home=C:/Users/<用户名>/.jabba/jdk/temurin@17.0.10
+```
+
+> 注意路径需要与 `jabba ls` 列出的真实 JDK 目录一致。
+
+---
+
+## 7. IDE 中使用 Jabba 管理的 JDK
+
+### 7.1 IntelliJ IDEA
+
+1. 打开 `File -> Project Structure -> SDKs`。
+2. 点击 `+` 添加 JDK，路径指向 Jabba 安装的 JDK，例如:
+   - `C:\Users\<用户名>\.jabba\jdk\temurin@17.0.10`
+3. 在 `Project` 中为每个项目选择对应 SDK（JDK 8 / 11 / 17 等）。
+4. 在 IDEA 内置 Terminal 中使用 PowerShell，可继承前述 Jabba 环境。
+
+### 7.2 Eclipse
+
+1. 打开 `Window -> Preferences -> Java -> Installed JREs`。
+2. 添加 JRE，路径为 Jabba 的 JDK 目录，例如:
+   - `C:\Users\<用户名>\.jabba\jdk\temurin@11.0.x`
+3. 在工作空间或项目属性中为不同项目选择不同 JRE。
+
+### 7.3 VS Code（Java 扩展）
+
+在对应工程的 `settings.json` 中配置:
+
+```json
+{
+  "java.jdt.ls.java.home": "C:/Users/<用户名>/.jabba/jdk/temurin@17.0.10"
+}
+```
+
+不同 Workspace 可指向不同 JDK，实现按项目区分。
+
+---
+
+## 8. 备份与迁移建议
+
+为方便重装系统或迁移到新电脑，建议备份以下内容:
+
+- PowerShell Profile:
+  - `$PROFILE` 对应的文件（路径可通过 `echo $PROFILE` 查看）。
+- Jabba 相关:
+  - `C:\Users\<用户名>\.jabba\bin\jabba.exe`
+  - `C:\Users\<用户名>\.jabba\jabba.ps1`
+- 本目录下配置:
+  - `JAVA_ENV_SETUP.md`（本说明文件）
+  - `use-java.ps1`（项目级切换脚本）
+- 各个项目中的 `.jabbarc` 文件（记录各项目所需的 JDK 版本）。
+
+迁移步骤简化为:
+
+1. 将上述文件拷贝到新机器相同位置。
+2. 打开 PowerShell，确认 Profile 中有 Jabba 加载语句。
+3. 重新打开 PowerShell，执行 `jabba --version` 验证。
+4. 根据需要使用 `jabba install` 重新拉取各版本 JDK（或同时备份 `.jabba\jdk` 目录）。
+
+---
+
+通过上述配置，你即可在 Windows 10 上实现:
+
+- 全局默认 JDK 版本（通过 Profile 中的 `jabba use`）。
+- 项目级 JDK 版本（通过 `.jabbarc` + `use-java.ps1`）。
+- 构建工具与 IDE 均能根据当前环境/配置选择合适的 JDK。