技术说明

本文给出 ECShopX Java 的整体技术方案、技术栈清单与部署摘要，与 架构说明.md 共同构成全书「事实锚点」。

整体方案

ECShopX Java 采用前后端分离 + 模块化单体后端架构：前端（管理端 ecshopx-admin、商城端 ecshopx-vshop 等）通过 HTTP 调用 Java 后端；后端以单个 Spring Boot 进程聚合全部业务 Bundle，外围依赖 MySQL、Redis、对象存储与任务调度组件。

核心组件（文字版）：

                    ┌─────────────────────────────────────┐
                    │  前端：Vue / Taro 小程序 / H5 / PC   │
                    └──────────────────┬──────────────────┘
                                       │ HTTPS
                    ┌──────────────────▼──────────────────┐
                    │  负载均衡 / CDN（生产可选）           │
                    └──────────────────┬──────────────────┘
                                       │
┌──────────────────────────────────────▼──────────────────────────────────────┐
│  ecshopx-java（Spring Boot 3 + Undertow，端口 18080）                        │
│  ├─ ecshopx-bootstrap → cn.shopex.ecshopx.EcshopxApplication               │
│  ├─ 50+ 业务 Bundle（goods / orders / members / payment / …）              │
│  ├─ ecshopx-dispatch（同步 / Redis 异步事件）                               │
│  └─ XXL-JOB Executor（端口 19999，向 Admin 注册）                           │
└───────┬─────────────────┬────────────────────┬────────────────────────────┘
        │                 │                    │
        ▼                 ▼                    ▼
   MySQL 8.x         Redis 7.x          OSS / CDN
   + Flyway          多逻辑库缓存/队列     local / oss / qiniu / aws / cosv5
        │
        ▼
   XXL-JOB Admin（独立部署，调度各模块 @XxlJob 任务）

数据与任务流要点：

持久化：MyBatis-Plus Mapper 访问 MySQL；结构变更经 Flyway 版本化迁移
缓存与队列：默认 Redis；ecshopx-dispatch 可将跨 Bundle 事件写入 Redis 异步消费
文件与静态资源：ecshopx.storage.* 对接本地目录或云 OSS，经 /storage/ 或 CDN 域名对外
定时任务：业务模块在 cron 包声明 @XxlJob 处理器，由 XXL-JOB Admin 统一调度

技术栈

名称	描述
后端开发语言	Java 17
后端开发框架	Spring Boot 3.5、MyBatis-Plus 3.5、Undertow
启动入口	`cn.shopex.ecshopx.EcshopxApplication`（`ecshopx-bootstrap` 模块）
前端开发语言	HTML5 / CSS3 / ES6 / 小程序开发框架
前端开发框架	Vue 2、Taro、React
数据库	MySQL（≥ 5.7，建议 8.0，`utf8mb4`）
数据库迁移	Flyway（`ecshopx-bootstrap/src/main/resources/db/migration`）
队列 / 异步	Redis（`ecshopx-dispatch` 默认异步驱动）；RabbitMQ 非主路径
缓存	Redis（多逻辑库：default / companys / prism / datacube / deposit）
定时任务	XXL-JOB 2.5（Admin 独立 + 应用内 Executor）
CDN / OSS	阿里云 OSS、七牛云、AWS S3、腾讯云 COS（`cosv5`）；驱动键 `ecshopx.storage.driver`
日志搜集	应用日志（`logs/`）；Sentry 为可选（工程未默认集成）
构建工具	Maven 3.9+（推荐 `./mvnw`）
容器编排	Docker Compose（`docker-compose.yml`，推荐本地与集成测试）
持续集成	Git；GitLab CI / K8S 流水线为团队可选扩展

OSS & CDN 方案

对象存储通过 ecshopx.storage.driver 切换驱动：

驱动值	说明
`local`	本地目录，默认 URL 前缀 `http://localhost:18080/storage`
`oss`	阿里云 OSS（`ecshopx.storage.oss.*`）
`qiniu`	七牛云存储（`ecshopx.storage.qiniu.*`）
`aws`	AWS S3 兼容存储（`ecshopx.storage.aws.*`）
`cosv5`	腾讯云 COS（`ecshopx.storage.cosv5.*`）

使用场景：

前后端分离：前端构建产物（CSS / JS）可部署至 CDN 或静态资源桶
媒体资源：商品图、视频等大文件上传至 OSS，经 CDN 加速分发
导入导出：部分批量导入文件可使用独立私有桶配置（ecshopx.storage.import-file.*）

生产环境建议：图片 / 视频使用独立 Bucket 与域名，并开启 CDN 回源 OSS。

前端技术方案

前端工程与 Java 后端分离部署，通过 /api/、/storage/、/wechatAuth/ 等统一前缀对接：

PC 管理端：Vue 2 + vue-router / vuex，iview 组件库
移动端 H5：Taro
微信小程序：Taro / Wepy
混合应用：H5 内嵌与原生双向通讯
工具链：webpack、vue-cli 3、spx-cli
协作：YApi 管理接口文档与 Mock

前端仓库版本与构建命令以各前端项目 README 为准；本书聚焦 Java 后端二次开发。

后端技术方案

模块化 Maven 工程

父工程 cn.shopex:ecshopx 统一管理 50+ 子模块版本与依赖 BOM（ecshopx-bom）
1 Bundle = 1 Maven Module：如 ecshopx-goods、ecshopx-orders、ecshopx-members
公共能力：ecshopx-common（异常、工具、MyBatis 扩展）、ecshopx-dispatch（跨模块事件）
启动装配：ecshopx-bootstrap 引入所需 Bundle 依赖，打包为可执行 jar

分层约定

每个业务 Bundle 内部典型分层：

层级	职责
`api`（`admin` / `front` / `openapi`）	HTTP 控制器，参数校验与响应封装
`service`	业务编排与领域逻辑
`mapper`	MyBatis-Plus 数据访问
`domain` / `entity`	表映射实体（`@TableName` 等）
`integration`	外部系统适配
`port`	跨 Bundle 能力接口，避免循环依赖
`dispatch`	本模块发出 / 监听的事件
`cron`	XXL-JOB 任务处理器（`@XxlJob`）

跨模块调用应通过 Port 接口 或 dispatch 事件 解耦，禁止 Bundle 间直接循环依赖。

启动与开发工具链

入口类：cn.shopex.ecshopx.EcshopxApplication
本地启动：./mvnw -pl ecshopx-bootstrap -am spring-boot:run -Dspring-boot.run.profiles=local
打包运行：./mvnw -pl ecshopx-bootstrap -am package -DskipTests → java -jar ecshopx-bootstrap/target/*.jar
数据库迁移：bin/make-migration <描述> 生成 SQL → review → bin/make-migration migrate
Mapper 命名：FqcnMapperBeanNameGenerator 避免多模块同名 Mapper 冲突

依赖服务

MySQL：业务库 ecshopx；XXL-JOB 使用独立库 xxl_job
Redis：缓存、会话、dispatch 队列等；密码与逻辑库见 application-local.properties 或 Compose 环境变量
XXL-JOB：xxl.job.admin.addresses 指向 Admin；xxl.job.executor.port=19999

部署方案

传统主机 / 云主机

安装 JDK 17、自备 MySQL 与 Redis
./mvnw -pl ecshopx-bootstrap -am package -DskipTests 构建可执行 jar
导入 docker/ecshopx.sql（及 docker/tables_xxl_job.sql）初始化数据库
配置 application.properties 或外部配置（数据源、Redis、OSS、XXL-JOB 等）
java -jar ecshopx-bootstrap-*.jar --spring.profiles.active=prod 启动
可选：Nginx 反向代理至 18080，统一域名暴露 /api/、/storage/

Docker Compose（推荐）

仓库根目录 docker-compose.yml 一键拉起 mysql + redis + xxl-job-admin + ecshopx-java：

bash

cd ecshopx-java
docker compose up -d

服务	地址（宿主机，Compose）
API	http://localhost:18080/api/
静态资源	http://localhost:18080/storage/
微信回调	http://localhost:18080/wechatAuth/
XXL-JOB Admin	http://localhost:8080/xxl-job-admin（`docker-compose.yml` 映射 `8080:8080`）
MySQL	`localhost:3306`
Redis	`localhost:6379`

非 Compose 本地 profile：application.properties / application-local.properties 中执行器指向 http://127.0.0.1:9080/xxl-job-admin，需自行在宿主机启动 XXL-JOB Admin 并监听 9080；与 Compose 编排的 8080 端口无关。

详见本地 / Docker 部署中的编排命令与健康检查说明。

Kubernetes（可选摘要）

将 ecshopx-java 镜像（docker/Dockerfile 多阶段构建）部署为 Deployment，通过 Service / Ingress 暴露 18080
MySQL、Redis、XXL-JOB Admin 建议使用云托管或集群内 StatefulSet；应用实例无状态，可配置 HPA 按 CPU / 自定义指标扩缩
配置通过 ConfigMap / Secret 注入，等价于 Spring Boot --key=value 或 APP_ARGS 环境变量
Helm / GitLab CI 等流水线按团队规范接入，非仓库强制要求

Java 版以单 JVM Spring Boot 应用 + XXL-JOB + ecshopx-dispatch 为主部署模型；应用副本可水平扩展，定时与异步分别由 Admin 调度与 Redis 队列承载。

技术说明 ​

整体方案 ​

技术栈 ​

OSS & CDN 方案 ​

前端技术方案 ​

后端技术方案 ​

模块化 Maven 工程 ​

分层约定 ​

启动与开发工具链 ​

依赖服务 ​

部署方案 ​

传统主机 / 云主机 ​

Docker Compose（推荐） ​

Kubernetes（可选摘要） ​