311 lines
7.1 KiB
Markdown
311 lines
7.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 (代码格式化)
|
||
- 基于空格的缩进 (4个空格)
|
||
- 自动清理尾随空白字符
|
||
- 文件末尾添加换行符
|
||
- 基本的导入组织
|
||
|
||
常用命令:
|
||
```bash
|
||
# 检查代码格式
|
||
mvn spotless:check
|
||
|
||
# 自动格式化代码
|
||
mvn spotless:apply
|
||
```
|
||
|
||
#### Checkstyle (代码规范检查)
|
||
- 使用 Sun Java 编码规范 (比 Google 规范更宽松)
|
||
- 在编译时自动检查代码规范
|
||
- 与 Java 11 和 Lombok 兼容
|
||
|
||
常用命令:
|
||
```bash
|
||
# 检查代码规范
|
||
mvn checkstyle:check
|
||
|
||
# 生成规范检查报告
|
||
mvn checkstyle:checkstyle
|
||
```
|
||
|
||
#### 集成命令
|
||
```bash
|
||
# 格式化代码并编译
|
||
mvn spotless:apply compile
|
||
|
||
# 完整检查 (格式化 + 规范检查 + 编译)
|
||
mvn spotless:apply checkstyle:check compile
|
||
```
|
||
|
||
## API 集成测试指南
|
||
|
||
在 `play-admin` 模块内提供了基于 `apitest` Profile 的端到端测试套件。为了稳定跑通所有 API 场景，请按以下步骤准备环境：
|
||
|
||
1. **准备数据库**
|
||
默认连接信息为 `jdbc:mysql://127.0.0.1:33306/peipei_apitest`，账号密码均为 `apitest`。可通过以下命令初始化：
|
||
|
||
```sql
|
||
CREATE DATABASE IF NOT EXISTS peipei_apitest CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;
|
||
CREATE USER IF NOT EXISTS 'apitest'@'%' IDENTIFIED BY 'apitest';
|
||
GRANT ALL PRIVILEGES ON peipei_apitest.* TO 'apitest'@'%';
|
||
FLUSH PRIVILEGES;
|
||
```
|
||
|
||
若端口或凭证不同，请同步修改 `play-admin/src/main/resources/application-apitest.yml`。
|
||
|
||
2. **准备 Redis（必需）**
|
||
测试依赖 Redis 记录幂等与缓存信息。可以执行 `docker compose up -d redis`（路径：`docker/docker-compose.yml`）快速启一个实例，默认映射端口为 `36379`。
|
||
|
||
3. **执行测试**
|
||
在仓库根目录运行：
|
||
|
||
```bash
|
||
mvn -pl play-admin -am test
|
||
```
|
||
|
||
如需探查单个用例，可指定测试类：
|
||
|
||
```bash
|
||
mvn -pl play-admin -Dtest=WxCustomRandomOrderApiTest test
|
||
```
|
||
|
||
4. **自动数据播种**
|
||
激活 `apitest` Profile 时，`ApiTestDataSeeder` 会自动创建默认租户、顾客、店员、商品、礼物、优惠券等基线数据，并在每次启动时重置关键计数，因此多次执行结果一致。如果需要彻底清理，可直接清空数据库后重新运行测试。
|
||
|
||
按照上述流程，即可可靠地复现订单、优惠券、礼物等核心链路的 API 行为。
|
||
|
||
## 部署说明
|
||
|
||
### Docker 构建和推送
|
||
|
||
项目支持多架构 Docker 构建，特别适合在 Apple Silicon Mac 上为 Linux 服务器构建镜像。
|
||
|
||
#### 构建镜像
|
||
|
||
```bash
|
||
# 构建服务器部署镜像 (Linux amd64)
|
||
./build-docker.sh amd64
|
||
|
||
# 构建本地开发镜像 (Apple Silicon arm64)
|
||
./build-docker.sh arm64
|
||
|
||
# 自动检测架构构建
|
||
./build-docker.sh
|
||
|
||
# 查看帮助
|
||
./build-docker.sh -h
|
||
```
|
||
|
||
#### 推送到私有仓库
|
||
|
||
```bash
|
||
# 推送 amd64 镜像到私有仓库 (用于服务器部署)
|
||
./push-docker.sh
|
||
```
|
||
|
||
### 服务器部署
|
||
|
||
#### 部署环境
|
||
- **服务器**: CentOS Linux
|
||
- **架构**: amd64
|
||
- **容器**: Docker + Docker Compose
|
||
|
||
#### 部署步骤
|
||
|
||
1. **服务器上的配置文件**
|
||
```bash
|
||
# 服务器主目录有专门的 docker-compose 文件
|
||
~/docker-compose.yml # 为 CentOS 环境优化的配置
|
||
```
|
||
|
||
2. **启动服务**
|
||
```bash
|
||
# 在服务器主目录执行
|
||
cd ~
|
||
docker-compose up -d
|
||
```
|
||
|
||
3. **查看日志**
|
||
```bash
|
||
# 应用日志位置
|
||
~/log/ # 应用日志目录
|
||
|
||
# 查看实时日志
|
||
tail -f ~/log/detail.log
|
||
tail -f ~/log/error.log
|
||
|
||
# 查看容器日志
|
||
docker-compose logs -f
|
||
```
|
||
|
||
#### 部署文件说明
|
||
|
||
- **~/docker-compose.yml**: 为 CentOS 环境定制的 Docker Compose 配置
|
||
- **~/log/**: 应用日志输出目录
|
||
- 配置文件已针对服务器环境进行优化，可直接使用
|
||
|
||
## 模块介绍
|
||
|
||
### 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 配置已设置
|