PeiPei 后端项目

基于 Spring Boot 的多模块项目，为 PeiPei 应用提供后端服务。

项目结构

• play-admin: 主要的 Spring Boot 应用模块
• play-common: 公共工具类和共享代码
• play-generator: 代码生成工具

构建要求

• Java 11 (必须)
• Maven 3.6+

快速开始

1. 安装 Java 11

在 macOS 上使用 Homebrew:

brew install --cask zulu@11

设置 Java 11 为默认版本:

临时设置 (当前会话):

export JAVA_HOME=$(/usr/libexec/java_home -v 11)

永久设置方法:

方法1: Shell 配置 (推荐) 添加到 ~/.zshrc 或 ~/.bash_profile:

export JAVA_HOME=$(/usr/libexec/java_home -v 11)
export PATH="$JAVA_HOME/bin:$PATH"

方法2: Maven 专用 创建 ~/.mavenrc:

export JAVA_HOME=$(/usr/libexec/java_home -v 11)

方法3: VS Code 项目配置 项目已配置 .vscode/settings.json 使用 Java 11:

{
    "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. 构建项目

# 清理并构建所有模块
mvn clean install

# 或者仅编译
mvn clean compile

3. 运行应用

# 运行主应用
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个空格)
• 自动清理尾随空白字符
• 文件末尾添加换行符
• 基本的导入组织

常用命令:

# 检查代码格式
mvn spotless:check

# 自动格式化代码
mvn spotless:apply

Checkstyle (代码规范检查)

• 使用 Sun Java 编码规范 (比 Google 规范更宽松)
• 在编译时自动检查代码规范
• 与 Java 11 和 Lombok 兼容

常用命令:

# 检查代码规范
mvn checkstyle:check

# 生成规范检查报告
mvn checkstyle:checkstyle

集成命令

# 格式化代码并编译
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。可通过以下命令初始化：

   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. 执行测试
   在仓库根目录运行：

   mvn -pl play-admin -am test
   

   如需探查单个用例，可指定测试类：

   mvn -pl play-admin -Dtest=WxCustomRandomOrderApiTest test
   

4. 自动数据播种
   激活 apitest Profile 时，ApiTestDataSeeder 会自动创建默认租户、顾客、店员、商品、礼物、优惠券等基线数据，并在每次启动时重置关键计数，因此多次执行结果一致。如果需要彻底清理，可直接清空数据库后重新运行测试。

按照上述流程，即可可靠地复现订单、优惠券、礼物等核心链路的 API 行为。

部署说明

Docker 构建和推送

项目支持多架构 Docker 构建，特别适合在 Apple Silicon Mac 上为 Linux 服务器构建镜像。

构建镜像

# 构建服务器部署镜像 (Linux amd64)
./build-docker.sh amd64

# 构建本地开发镜像 (Apple Silicon arm64)
./build-docker.sh arm64

# 自动检测架构构建
./build-docker.sh

# 查看帮助
./build-docker.sh -h

推送到私有仓库

# 推送 amd64 镜像到私有仓库 (用于服务器部署)
./push-docker.sh

服务器部署

部署环境

• 服务器: CentOS Linux
• 架构: amd64
• 容器: Docker + Docker Compose

部署步骤

1. 服务器上的配置文件

   # 服务器主目录有专门的 docker-compose 文件
   ~/docker-compose.yml  # 为 CentOS 环境优化的配置
   

2. 启动服务

   # 在服务器主目录执行
   cd ~
   docker-compose up -d
   

3. 查看日志

   # 应用日志位置
   ~/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

验证配置

# 验证 Java 版本
java -version

# 验证 Maven Java 版本  
mvn -version

# 验证编译
mvn clean compile

# 验证完整构建
mvn clean install

构建状态

✅ 所有模块使用 Java 11 编译成功
✅ Lombok 注解自动处理
✅ 模块间配置一致
✅ Spotless 代码格式化已配置
✅ Checkstyle 代码规范检查已配置 ✅ VS Code Java 配置已设置