玩湃
blame | 历史 | 原始文档

PlayPai 项目分析与启动说明

1. 项目概览

PlayPai 是一个 Java 微服务后端项目，使用 Spring Cloud Alibaba + Nacos 进行服务注册、配置管理和服务间调用。仓库不包含可独立启动的 Web 前端；根目录的 package.json 是业务 JSON 数据，并非 Node.js 工程配置。

主要技术栈：

  • JDK 8
  • Maven 3.x
  • Spring Boot 2.3.6.RELEASE（父依赖定义）
  • Spring Cloud Hoxton.SR9、Spring Cloud Alibaba 2.2.1.RELEASE
  • Nacos、OpenFeign、Spring Cloud Gateway、Sentinel
  • MyBatis / MyBatis-Plus、Druid、ShardingSphere
  • MySQL 5.7、Redis
  • OAuth2 / Spring Security、Swagger 2

2. 目录结构

PlayPai/
├── cloud-server-parent/              # 本项目父 POM，统一本地 profile 与仓库配置
├── cloud-server-gateway/             # 网关
├── cloud-server-auth/                # OAuth2 授权中心
├── cloud-server-account/             # 账户、用户、学员等领域
├── cloud-server-activity/            # 福利、优惠券、积分等活动领域
├── cloud-server-competition/         # 赛事领域
├── cloud-server-course/              # 课程、课包、排课等领域
├── cloud-server-other/               # 门店、场地、首页配置等领域
├── cloud-server-management/          # 管理后台 API
├── cloud-server-communityWorldCup/   # 社区世界杯领域
├── nacos/                            # Nacos 配置导出包
└── sql/                              # 6 个业务数据库的初始化 SQL

每个服务的典型分层为：controller（接口）、service（业务）、mapper（数据访问）、entity/model（数据模型）、feignclient（跨服务调用）和 resources/mapper（MyBatis XML）。

3. Maven 继承与私有依赖

依赖关系如下：

各 cloud-server-* 服务
        │
        └── mb-cloud-parent:1.1.3（cloud-server-parent/pom.xml）
                    │
                    └── mb-cloud-dependent:1.1.3（私有 Maven POM）
                              │
                              └── mb-cloud-platform-bom:1.1.3 等私有公共依赖

mb-cloud-dependent 不是项目源码目录中的 Java 文件，而是 Maven 坐标。正常情况下 Maven 会将其下载到：

~/.m2/repository/cn/mb/cloud/mb-cloud-dependent/1.1.3/

项目使用 Magic-Beans 私有仓库和阿里云仓库。Magic-Beans 的 HTTP 地址会重定向到 HTTPS；如果某台机器无法下载，可先检查 Maven 的 settings.xml 是否被不可用的镜像覆盖。

注意：根目录没有聚合 pom.xml，cloud-server-parent/pom.xml 也没有 <modules>。因此不能在根目录一次构建所有服务；需按模块构建或在 IDE 中逐个添加 Maven POM。

4. 服务清单与访问端口

服务 Maven artifactId 端口 数据库
网关 mb-cloud-gateway 56666 无独立库
授权中心 mb-cloud-auth 5016 playpai_other
账户 mb-cloud-account 5001 playpai_account
福利活动 mb-cloud-activity 5002 playpai_activity
赛事 mb-cloud-competition 5003 playpai_competition
课程 mb-cloud-course 5004 playpai_course
其他/门店场地 mb-cloud-other 5005 playpai_other
管理后台 mb-cloud-management 5006 playpai_other
社区世界杯 mb-cloud-communityWorldCup 5007 playpai_community_world_cup

网关入口为 http://localhost:56666，主要路由前缀如下：

/account/**            -> mb-cloud-account
/activity/**           -> mb-cloud-activity
/competition/**        -> mb-cloud-competition
/course/**             -> mb-cloud-course
/other/**              -> mb-cloud-other
/communityWorldCup/**  -> mb-cloud-communityWorldCup

路由和各服务端口由 Nacos 中的配置控制，导出文件位于 nacos/nacos_config_export_20250922175137.zip。

5. 外部基础设施与配置来源

Nacos

各模块的 src/main/resources/bootstrap.properties 不含最终固定配置，而是通过 Maven 资源过滤生成 Nacos 地址、用户名、命名空间和服务名。

开发 profile 的默认目标：

Nacos: 127.0.0.1:18848
namespace: b786884e-d7e5-477d-a7d2-193e27528e55
group: dsh-cloud

请启动 Nacos，并导入仓库内的 Nacos 配置导出 ZIP。配置中包含服务端口、数据源、网关路由和公共配置。

MySQL 与 Redis

开发环境配置使用：

MySQL: 127.0.0.1:3306
Redis: 127.0.0.1:6379

初始化数据库：

mysql -uroot -p -e 'CREATE DATABASE IF NOT EXISTS playpai_account CHARACTER SET utf8mb4;'
mysql -uroot -p -e 'CREATE DATABASE IF NOT EXISTS playpai_activity CHARACTER SET utf8mb4;'
mysql -uroot -p -e 'CREATE DATABASE IF NOT EXISTS playpai_competition CHARACTER SET utf8mb4;'
mysql -uroot -p -e 'CREATE DATABASE IF NOT EXISTS playpai_course CHARACTER SET utf8mb4;'
mysql -uroot -p -e 'CREATE DATABASE IF NOT EXISTS playpai_other CHARACTER SET utf8mb4;'
mysql -uroot -p -e 'CREATE DATABASE IF NOT EXISTS playpai_community_world_cup CHARACTER SET utf8mb4;'

mysql -uroot -p playpai_account < sql/playpai_account.sql
mysql -uroot -p playpai_activity < sql/playpai_activity.sql
mysql -uroot -p playpai_competition < sql/playpai_competition.sql
mysql -uroot -p playpai_course < sql/playpai_course.sql
mysql -uroot -p playpai_other < sql/playpai_other.sql
mysql -uroot -p playpai_community_world_cup < sql/playpai_community_world_cup.sql

导入 SQL 会删除并重建其中已有的表，请只在本地开发数据库执行。

6. 正确的 JDK 设置

必须使用完整 JDK 8，不能使用 macOS 中的 Java 浏览器插件 JRE。推荐配置：

export JAVA_HOME=/Library/Java/JavaVirtualMachines/jdk-1.8.jdk/Contents/Home
export PATH="$JAVA_HOME/bin:$PATH"

java -version
mvn -version

若 Maven 报错 tools.jar not found 且路径包含 JavaAppletPlugin.plugin，说明正在使用 JRE；按上面设置 JAVA_HOME 后重新构建。

7. 构建与启动

单模块构建

mvn -f cloud-server-gateway/pom.xml clean package -DskipTests

其他模块将路径替换为对应模块的 pom.xml 即可。构建成功后的 Jar 位于模块 target/ 目录。

推荐启动顺序

  1. 启动 MySQL、Redis、Nacos。
  2. 导入 Nacos 配置与 SQL 数据。
  3. 启动授权中心和基础业务服务：auth、account、other。
  4. 启动 course、activity、competition、communityWorldCup、management。
  5. 最后启动 gateway。

示例：

mvn -f cloud-server-auth/pom.xml spring-boot:run
mvn -f cloud-server-account/pom.xml spring-boot:run
mvn -f cloud-server-other/pom.xml spring-boot:run
mvn -f cloud-server-gateway/pom.xml spring-boot:run

也可以先打包再启动：

java -jar cloud-server-gateway/target/mb-cloud-gateway.jar

8. IntelliJ IDEA 导入方法

由于没有 Maven 聚合模块，直接打开根目录时 IDEA 只会将其识别为普通项目。请在 Maven 工具窗口中点击 + Add Maven Project，依次添加每个 cloud-server-*/pom.xml，再执行 Reload All Maven Projects。

在 Settings -> Build Tools -> Maven 中设置：

  • Maven importer JDK：/Library/Java/JavaVirtualMachines/jdk-1.8.jdk/Contents/Home
  • Maven Runner JRE：同一个 JDK 8

在 Project Structure -> Project SDK 中也选择同一 JDK。

9. 当前已知风险

  • 私有依赖依赖外部 Maven 仓库；网络不可用时无法首次下载 cn.mb.cloud 相关依赖。
  • 没有根聚合 POM，不支持一次命令构建全部服务。
  • 配置和数据库连接信息主要在 Nacos，未正确导入 Nacos 配置时服务不能正常启动。
  • 多个服务通过 OpenFeign 相互调用，单独启动一个服务只能进行有限功能验证。
  • 部分支付、短信、对象存储、地图等第三方能力需要有效的外部配置和密钥，未配置时相关业务不可用。