7cafe17cd3
- 添加 Spotless Maven 插件用于代码格式化 - 配置基础格式化规则 (4空格缩进, 导入组织, 清理空白) - 更新 README 文档，添加格式化工具使用说明 - 与 Java 11 和 Lombok 完全兼容
200 lines
4.1 KiB
Markdown
200 lines
4.1 KiB
Markdown
# PeiPei 后端项目
|
|
|
|
基于 Spring Boot 的多模块项目，为 PeiPei 应用提供后端服务。
|
|
|
|
## 项目结构
|
|
|
|
- **play-admin**: 主要的 Spring Boot 应用模块
|
|
- **play-common**: 公共工具类和共享代码
|
|
- **play-generator**: 代码生成工具
|
|
|
|
## 构建要求
|
|
|
|
- **Java 11** (必须)
|
|
- **Maven 3.6+**
|
|
|
|
## 快速开始
|
|
|
|
### 1. 安装 Java 11
|
|
|
|
在 macOS 上使用 Homebrew:
|
|
```bash
|
|
brew install --cask zulu@11
|
|
```
|
|
|
|
设置 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
|
|
# 清理并构建所有模块
|
|
mvn clean install
|
|
|
|
# 或者仅编译
|
|
mvn clean compile
|
|
```
|
|
|
|
### 3. 运行应用
|
|
|
|
```bash
|
|
# 运行主应用
|
|
java -jar play-admin/target/play-admin-1.0.jar
|
|
|
|
# 或使用 Maven
|
|
cd play-admin
|
|
mvn spring-boot:run
|
|
```
|
|
|
|
## 配置说明
|
|
|
|
项目在所有模块中统一使用 Java 11:
|
|
- 所有模块都配置为 Java 11 源码和目标版本
|
|
- Lombok 注解自动处理
|
|
- 无需显式配置注解处理器
|
|
|
|
## 开发说明
|
|
|
|
- 项目已更新为所有模块统一使用 Java 11
|
|
- 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
|
|
主要的 Spring Boot 应用，包含:
|
|
- REST API 接口
|
|
- 安全配置
|
|
- 数据库集成
|
|
- 微信集成
|
|
|
|
### play-common
|
|
共享工具库，包含:
|
|
- 公共域对象
|
|
- 工具类
|
|
- Redis 配置
|
|
- 安全工具
|
|
|
|
### play-generator
|
|
代码生成工具，包含:
|
|
- 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 注解自动处理
|
|
✅ 模块间配置一致
|
|
✅ Spotless 代码格式化已配置
|
|
✅ Checkstyle 代码规范检查已配置
|
|
✅ VS Code Java 配置已设置 |