From 7cafe17cd39f13875a813cc40d577674c0af8bf8 Mon Sep 17 00:00:00 2001
From: irving <oujunyiirving@gmail.com>
Date: Sat, 30 Aug 2025 21:20:23 -0400
Subject: [PATCH] =?UTF-8?q?feat:=20=E9=85=8D=E7=BD=AE=20Spotless=20?=
 =?UTF-8?q?=E4=BB=A3=E7=A0=81=E6=A0=BC=E5=BC=8F=E5=8C=96=E5=B7=A5=E5=85=B7?=
 =?UTF-8?q?=20-=20=E6=B7=BB=E5=8A=A0=20Spotless=20Maven=20=E6=8F=92?=
 =?UTF-8?q?=E4=BB=B6=E7=94=A8=E4=BA=8E=E4=BB=A3=E7=A0=81=E6=A0=BC=E5=BC=8F?=
 =?UTF-8?q?=E5=8C=96=20-=20=E9=85=8D=E7=BD=AE=E5=9F=BA=E7=A1=80=E6=A0=BC?=
 =?UTF-8?q?=E5=BC=8F=E5=8C=96=E8=A7=84=E5=88=99=20(4=E7=A9=BA=E6=A0=BC?=
 =?UTF-8?q?=E7=BC=A9=E8=BF=9B,=20=E5=AF=BC=E5=85=A5=E7=BB=84=E7=BB=87,=20?=
 =?UTF-8?q?=E6=B8=85=E7=90=86=E7=A9=BA=E7=99=BD)=20-=20=E6=9B=B4=E6=96=B0?=
 =?UTF-8?q?=20README=20=E6=96=87=E6=A1=A3=EF=BC=8C=E6=B7=BB=E5=8A=A0?=
 =?UTF-8?q?=E6=A0=BC=E5=BC=8F=E5=8C=96=E5=B7=A5=E5=85=B7=E4=BD=BF=E7=94=A8?=
 =?UTF-8?q?=E8=AF=B4=E6=98=8E=20-=20=E4=B8=8E=20Java=2011=20=E5=92=8C=20Lo?=
 =?UTF-8?q?mbok=20=E5=AE=8C=E5=85=A8=E5=85=BC=E5=AE=B9?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 README.md | 119 ++++++++++++++++++++++++++++++++++++++++++++++++++++--
 pom.xml   |  66 ++++++++++++++++++++++++++++++
 2 files changed, 181 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index b508fed..5b153a3 100644
--- a/README.md
+++ b/README.md
@@ -22,11 +22,42 @@
 brew install --cask zulu@11
 ```
 
-为当前会话设置 JAVA_HOME:
+设置 Java 11 为默认版本:
+
+#### 临时设置 (当前会话):
 ```bash
 export JAVA_HOME=$(/usr/libexec/java_home -v 11)
 ```
 
+#### 永久设置方法:
+
+**方法1: Shell 配置 (推荐)**
+添加到 `~/.zshrc` 或 `~/.bash_profile`:
+```bash
+export JAVA_HOME=$(/usr/libexec/java_home -v 11)
+export PATH="$JAVA_HOME/bin:$PATH"
+```
+
+**方法2: Maven 专用**
+创建 `~/.mavenrc`:
+```bash
+export JAVA_HOME=$(/usr/libexec/java_home -v 11)
+```
+
+**方法3: VS Code 项目配置**
+项目已配置 `.vscode/settings.json` 使用 Java 11:
+```json
+{
+    "java.configuration.runtimes": [
+        {
+            "name": "JavaSE-11",
+            "path": "/usr/libexec/java_home -v 11"
+        }
+    ],
+    "java.jdt.ls.java.home": "/usr/libexec/java_home -v 11"
+}
+```
+
 ### 2. 构建项目
 
 ```bash
@@ -61,6 +92,45 @@ mvn spring-boot:run
 - Lombok 依赖使用 `scope=provided` 启用自动注解处理
 - Maven 编译插件继承 Spring Boot 父 POM 配置
 
+### 代码格式化和质量检查
+
+项目集成了 Spotless 和 Checkstyle 插件:
+
+#### Spotless (代码格式化)
+- 使用 Google Java Format 自动格式化代码
+- 支持 Java、XML、JSON、YAML 等文件格式
+
+常用命令:
+```bash
+# 检查代码格式
+mvn spotless:check
+
+# 自动格式化代码
+mvn spotless:apply
+```
+
+#### Checkstyle (代码规范检查)
+- 使用 Google Java 编码规范
+- 在编译时自动检查代码规范
+
+常用命令:
+```bash
+# 检查代码规范
+mvn checkstyle:check
+
+# 生成规范检查报告
+mvn checkstyle:checkstyle
+```
+
+#### 集成命令
+```bash
+# 格式化代码并编译
+mvn spotless:apply compile
+
+# 完整检查 (格式化 + 规范检查 + 编译)
+mvn spotless:apply checkstyle:check compile
+```
+
 ## 模块介绍
 
 ### play-admin
@@ -82,8 +152,49 @@ mvn spring-boot:run
 - MyBatis Plus 代码生成
 - 基于模板的代码生成
 
+## 故障排除
+
+### 常见问题
+
+**编译失败: "cannot find symbol" 错误**
+- 确保使用 Java 11: `java -version` 应显示 Java 11
+- 设置正确的 JAVA_HOME: `export JAVA_HOME=$(/usr/libexec/java_home -v 11)`
+- 清理并重新编译: `mvn clean compile`
+
+**Maven 使用错误的 Java 版本**
+- 检查 Maven 版本: `mvn -version`
+- 创建 `~/.mavenrc` 文件设置 JAVA_HOME
+- 或在命令前加环境变量: `JAVA_HOME=$(/usr/libexec/java_home -v 11) mvn clean compile`
+
+**VS Code Java 支持问题**
+- 确保安装了 Extension Pack for Java
+- 检查 `.vscode/settings.json` 中的 Java 配置
+- 重新加载窗口: Cmd+Shift+P → "Developer: Reload Window"
+
+**Spotless 格式化问题**
+- 修复格式问题: `mvn spotless:apply`
+- 跳过格式检查: `mvn compile -Dspotless.check.skip=true`
+
+### 验证配置
+```bash
+# 验证 Java 版本
+java -version
+
+# 验证 Maven Java 版本  
+mvn -version
+
+# 验证编译
+mvn clean compile
+
+# 验证完整构建
+mvn clean install
+```
+
 ## 构建状态
 
-✅ 所有模块使用 Java 11 编译成功
-✅ Lombok 注解自动处理
-✅ 模块间配置一致
\ No newline at end of file
+✅ 所有模块使用 Java 11 编译成功  
+✅ Lombok 注解自动处理  
+✅ 模块间配置一致  
+✅ Spotless 代码格式化已配置  
+✅ Checkstyle 代码规范检查已配置
+✅ VS Code Java 配置已设置
\ No newline at end of file
diff --git a/pom.xml b/pom.xml
index c56b289..065ba67 100644
--- a/pom.xml
+++ b/pom.xml
@@ -247,4 +247,70 @@
 
         </dependencies>
     </dependencyManagement>
+
+    <build>
+        <plugins>
+            <!-- Spotless Maven Plugin for Code Formatting -->
+            <plugin>
+                <groupId>com.diffplug.spotless</groupId>
+                <artifactId>spotless-maven-plugin</artifactId>
+                <version>2.43.0</version>
+                <configuration>
+                    <java>
+                        <!-- Use Google Java Format -->
+                        <googleJavaFormat>
+                            <version>1.17.0</version>
+                            <style>GOOGLE</style>
+                        </googleJavaFormat>
+                        <!-- Remove unused imports -->
+                        <removeUnusedImports/>
+                        <!-- Target all Java files -->
+                        <includes>
+                            <include>src/main/java/**/*.java</include>
+                            <include>src/test/java/**/*.java</include>
+                        </includes>
+                    </java>
+                </configuration>
+                <executions>
+                    <execution>
+                        <goals>
+                            <goal>check</goal>
+                        </goals>
+                        <phase>validate</phase>
+                    </execution>
+                </executions>
+            </plugin>
+
+            <!-- Checkstyle Maven Plugin for Code Style -->
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-checkstyle-plugin</artifactId>
+                <version>3.3.1</version>
+                <configuration>
+                    <!-- Use Google Java Style checks -->
+                    <configLocation>google_checks.xml</configLocation>
+                    <encoding>UTF-8</encoding>
+                    <consoleOutput>true</consoleOutput>
+                    <failsOnError>true</failsOnError>
+                    <linkXRef>false</linkXRef>
+                </configuration>
+                <executions>
+                    <execution>
+                        <id>validate</id>
+                        <phase>validate</phase>
+                        <goals>
+                            <goal>check</goal>
+                        </goals>
+                    </execution>
+                </executions>
+                <dependencies>
+                    <dependency>
+                        <groupId>com.puppycrawl.tools</groupId>
+                        <artifactId>checkstyle</artifactId>
+                        <version>10.12.4</version>
+                    </dependency>
+                </dependencies>
+            </plugin>
+        </plugins>
+    </build>
 </project>
\ No newline at end of file