Appearance

架构说明 ​

本文描述 ECShopX Java 后端的整体架构能力，作为全书技术栈「事实锚点」。细节命令与配置以仓库源码、docker-compose.yml 及 本地 / Docker 部署 为准。

软件架构 ​

  • 后端开发语言：Java 17（推荐 Eclipse Temurin 17）
  • 后端技术框架：Spring Boot 3.5 + MyBatis-Plus 3.5；内嵌 Undertow 作为 HTTP 容器（默认开启 allow-unescaped-characters-in-url，兼容含特殊字符的历史 URL；POST Body 上限 64MB）
  • 工程组织：1 Bundle = 1 Maven Module；50+ 业务模块（ecshopx-goods、ecshopx-orders 等）由 ecshopx-bootstrap 聚合为单个 Spring Boot 应用运行，启动主类 cn.shopex.ecshopx.EcshopxApplication
  • 前端开发语言：HTML5 / CSS3 / ES6 / 小程序开发框架（与 ECShopX 前端工程配套，本书不展开前端仓库细节）
  • 前端开发框架：Vue 2、Taro、React（管理端 / 商城端等多端方案并存）
  • 数据库：MySQL（建议 8.0，utf8mb4）；支持读写分离与阿里云 PolarDB 等兼容 MySQL 的托管实例
  • 队列 / 异步：ecshopx-dispatch 提供同步与 Redis 驱动的跨模块事件分发；默认可靠队列能力基于 Redis；RabbitMQ 非主路径
  • 缓存：默认 Redis；按业务划分多 Redis 逻辑库（default / companys / prism / datacube / deposit 等，见 application.properties）
  • CDN / OSS：对象存储驱动 ecshopx.storage.driver 支持 local / oss / qiniu / aws / cosv5
  • 数据库迁移：Flyway 管理增量 SQL（目录 ecshopx-bootstrap/src/main/resources/db/migration；默认关闭启动时自动迁移，使用 bin/make-migration 生成与执行）
  • 定时任务：XXL-JOB（各模块 cron 包 + @XxlJob；Admin 独立部署，Executor 随应用注册，默认端口 19999）
  • 日志与可观测：应用日志输出至 logs/；Sentry 为可选接入（当前工程未内置 Sentry SDK，可按运维需要自行集成）

对外 API 路径前缀：

路径前缀用途
/api/业务 REST API
/storage/静态资源 / 本地上传文件
/wechatAuth/微信授权回调

默认 HTTP 端口：18080。

数据处理能力 ​

  • 支持 MySQL 读写分离；可使用阿里云 PolarDB 等兼容 MySQL 的云数据库
  • 多级缓存：Redis 应用缓存 + 网关 / CDN 层缓存（运维篇摘要）；目标为常规 API 响应在 2 秒以内（视业务复杂度与下游依赖而定）
  • 权限与数据隔离：按终端、店铺（商户）、门店等维度进行访问控制与数据范围限定，适配 B2C / B2B2C / O2O 等多模式
  • 吞吐能力：生产容量应结合实例规格、JVM 调优、数据库与 Redis 规格及 HPA 策略实测评估，并按业务横向扩容

稳定性 ​

  • 运行时模型：以单 JVM 应用进程承载全部已装配 Bundle 的 HTTP 与同步业务逻辑；定时任务由 XXL-JOB Executor 执行，异步削峰由 ecshopx-dispatch（Redis 驱动）处理
  • 异步与削峰：耗时或非关键路径通过 ecshopx-dispatch 与业务事件机制异步处理，避免阻塞请求线程
  • 定时与批处理：统一由 XXL-JOB Executor 执行各模块注册的定时任务；Admin 控制台独立部署，执行器与应用同生命周期管理
  • 缓存与可用性：Redis 多级缓存降低数据库压力；关键外部依赖（MySQL、Redis）建议主从或托管高可用方案
  • 集群与弹性（可选）：生产环境可使用 Docker Compose 多副本或 Kubernetes + HPA 水平扩展应用实例；状态外置至 MySQL / Redis，应用无状态便于滚动发布

持续集成 ​

  • 源码二次开发：ecshopx-java 以 Apache 2.0 开源，除商业授权外均可基于源码定制；模块边界清晰，可按 Bundle 独立演进
  • 本地 / 测试环境：仓库提供 docker-compose.yml，一键编排 MySQL、Redis、XXL-JOB Admin 与 ecshopx-java 应用（推荐默认开发路径）
  • 构建工具链：根目录 ./mvnw 统一编译与测试；数据库结构变更通过 Flyway + bin/make-migration 工作流
  • 版本管理：Git 管理源码与迁移脚本；提交前建议在目标模块执行 ./mvnw -pl <module> -am verify
  • CI/CD（可选）：Kubernetes、Helm、GitLab CI 等流水线可按团队基础设施自行接入，非仓库内置必选路径；首版文档以 Compose 与本地 Maven 工作流为准