mall-swarm: A Microservices E-Commerce Reference Stack for Java Teams

A Complete Microservices Blueprint for Java E-Commerce

mall-swarm targets Java backend engineers and teams who need to build or study a production-grade distributed e-commerce system. Rather than requiring architects to assemble each piece individually, the project ships nine cooperating services that cover authentication, product search, order management, messaging, and an admin console. The admin backend is a separate Vue application called mall-admin-web, and a mobile-facing storefront called mall-app-web is included as a third frontend.

The technology stack is broad. On the backend, it uses Spring Cloud 2025 and Spring Cloud Alibaba, Spring Boot 3.5, Sa-Token for authentication and authorisation, MyBatis with MyBatisGenerator for data access, and Seata for distributed transactions. Product search runs through Elasticsearch. Infrastructure dependencies include Nacos for service registry and configuration, RabbitMQ for messaging, Redis for caching, MongoDB for supplementary storage, and MinIO or Alibaba OSS for object storage. Kubernetes and Jenkins handle deployment and CI in the full setup. Every one of these dependencies must be running before the services can start.

The repository describes itself as both a practical system and a learning platform. The README points to a companion tutorial site at cloud.macrozheng.com, a video course, and a full Spring Cloud tutorial series. The intended audience includes engineers learning distributed systems alongside those wanting a head start on a real commerce project.

How the Nine Services Divide Responsibility

The project organises its code into nine modules, each deployable as an independent service:

mall
├── mall-common -- 工具类及通用代码模块
├── mall-mbg -- MyBatisGenerator生成的数据库操作代码模块
├── mall-auth -- 基于Spring Security Oauth2的统一的认证中心
├── mall-gateway -- 基于Spring Cloud Gateway的微服务API网关服务
├── mall-monitor -- 基于Spring Boot Admin的微服务监控中心
├── mall-admin -- 后台管理系统服务
├── mall-search -- 基于Elasticsearch的商品搜索系统服务
├── mall-portal -- 移动端商城系统服务
├── mall-demo -- 微服务远程调用测试服务
└── config -- 配置中心存储的配置

mall-gateway is the single entry point for all external traffic, built on Spring Cloud Gateway. mall-auth handles unified authentication using Sa-Token. mall-search runs product searches through Elasticsearch. mall-monitor provides a Spring Boot Admin dashboard for observing running services. The config directory holds configuration stored in Nacos, externalised from every service so that a property change does not require a redeployment.

All service-to-service calls go through Nacos for discovery. Seata coordinates transactions that span more than one service. LogStash collects logs centrally, visible in Kibana. The monitoring center runs at port 8101, the API gateway at 8201, and Nacos at port 8848 on the example deployment address.

Development Environment Requirements and First Steps

Running the full stack locally demands a specific set of versioned dependencies. The README specifies: JDK 17, MySQL 5.7, Redis 7.0, Elasticsearch 7.17.3 with matching Kibana and Logstash at the same version, MongoDB 5.0, RabbitMQ 3.10.5, and nginx 1.22.

Setup instructions point to external documentation rather than inline steps. The README directs engineers to cloud.macrozheng.com for both the Windows backend environment setup and the mall-admin-web frontend setup. The repository itself is not a self-contained setup guide; network access to the documentation site is required to follow the full procedure.

The Kubernetes deployment path is separate from the local development path. The README shows a Portainer management UI running at port 30880 as the cluster interface after a Kubernetes deployment, but the steps to reach that state are documented in the external tutorial rather than in the repository files. Two branches exist to support different migration timelines: the master branch targets Spring Cloud 2025 and Spring Boot 3.5, while dev-v2 retains compatibility with Spring Cloud 2021 and Spring Boot 2.7 for teams that have not yet moved to newer runtimes.

Where the Reference Architecture Shows Its Limits

mall-swarm is designed as a learning reference and a starting template. That framing creates real constraints for teams who want to deploy it to production directly.

The external service requirements are demanding. Running all nine services alongside MySQL, Redis, Elasticsearch, RabbitMQ, MongoDB, and Nacos means that even a minimal deployment needs substantial infrastructure. The README specifies Elasticsearch 7.17.3 and MongoDB 5.0, which are not the most recent releases available. Any team upgrading these dependencies must verify compatibility manually, as the repository does not document tested upgrade paths.

The setup documentation lives entirely on the cloud.macrozheng.com tutorial site. If that site becomes unavailable, new developers have only the technology table and module structure to guide them, with no inline step-by-step commands in the repository itself.

Distributed transactions across services require Seata. The README lists Seata in the technology table but does not describe how to configure it or which transaction patterns the portal service relies on. Teams inheriting this codebase for a production system must audit those transaction boundaries independently before going live.

The project spans five separate repositories: this one, mall-admin-web, mall-app-web, a configuration repository, and the companion mall repository. Coordinating version compatibility across that many codebases adds maintenance overhead that a single-application architecture does not carry.

mall-swarm Versus the Single-App mall Repository

The README explicitly links to the mall repository as a companion project. mall is a Spring Boot e-commerce application, while mall-swarm decomposes the same business domain into nine independently deployable microservices, adding Nacos for service discovery and configuration, and Spring Cloud Gateway as the single API entry point.

Engineers who need to understand the business logic quickly, or who are deploying to a single server, will find mall considerably simpler to run. mall-swarm exists for teams who need to operate services independently, scale individual components separately, or learn how a distributed architecture routes requests between authentication, search, and order management.

For Java teams whose primary concern is rapid admin console generation rather than e-commerce domain coverage, JeecgBoot is another open-source option. JeecgBoot focuses on low-code development through code wizards and form builders, while mall-swarm provides a complete e-commerce business domain with a proper microservices decomposition. The two address different problems and do not substitute for each other.

Maintenance Status, Branch Strategy, and Licensing

The last push to the master branch was on 2026-07-31, which is approximately two months before the time of writing, indicating the project continues to receive updates. The most recent tagged release is v1.0.3 from March 2024, with the master branch receiving commits well beyond that release date.

The Spring Boot 3.5 requirement on the master branch carries a concrete implication: Spring Boot 3.x requires Java 17 at minimum, which is reflected in the documented environment requiring JDK 17. Teams running JDK 11 cannot use the master branch without a Java upgrade. The dev-v2 branch preserves the older Spring Cloud 2021 and Spring Boot 2.7 toolchain for those teams.

The project is licensed under Apache License 2.0. That licence permits commercial use, modification, and distribution, with the requirement to preserve copyright notices and the Apache disclaimer in derived works. The homepage lists a copyright range of 2018 to 2026, placing the project as a long-running effort rather than a recent experiment.

Editorial conclusion

Java teams building a new distributed e-commerce system will find mall-swarm gives them a working architecture faster than assembling each service from scratch. Teams who need production-ready setup instructions should consult the cloud.macrozheng.com tutorials first, since the repository itself contains no inline setup steps. Anyone who cannot run JDK 17 locally must use the dev-v2 branch, which targets the older Spring Cloud 2021 and Spring Boot 2.7 stack.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. macrozheng/mall-swarm on GitHub
3. Project website
4. README
5. Releases