mall-swarm: a Spring Cloud Alibaba microservices mall you can actually run

What mall-swarm solves, and for whom

Most Spring Cloud sample repositories stop at a hello-world endpoint per service. mall-swarm starts from a shopping domain: goods, orders, members, search and an admin console. The repository README describes it as a microservices mall system that integrates a registry, a configuration center, a monitoring center and a gateway on top of the e-commerce business, and lists Spring Cloud Alibaba, Spring Boot 3.5, Sa-Token, MyBatis, Elasticsearch, Docker and Kubernetes among its core technologies. The intended reader is a Java backend engineer who already knows Spring Boot and wants to see how service discovery, config distribution, gateway routing and distributed transactions fit together in one codebase, or an instructor who needs a domain rich enough to make those topics concrete.

The secondary audience is a team that wants a starting skeleton for an internal commerce or catalog system. That is a weaker fit. mall-swarm is a teaching project with a companion tutorial site at cloud.macrozheng.com, and its value is in reading and running it, not in shipping it as your storefront.

The module split and what each process does

The README publishes the module tree directly, and it is the fastest way to understand the architecture. mall-common holds utility classes and shared code; mall-mbg holds the MyBatis Generator output for database access; mall-auth is described as a unified authentication center based on Spring Security OAuth2; mall-gateway is the API gateway built on Spring Cloud Gateway; mall-monitor is a Spring Boot Admin monitoring center; mall-admin is the backend management service; mall-search is the Elasticsearch-backed product search service; mall-portal serves the mobile storefront; mall-demo exists for testing remote calls between services. A top-level config directory holds the configuration that the config center serves.

One inconsistency is worth flagging before you plan around it. The technology table lists Sa-Token as the authentication and authorization framework, while the module tree still describes mall-auth as Spring Security OAuth2 based. Both statements come from the same README, and the README does not reconcile them. If token issuance is central to your design, read the mall-auth source and the config directory rather than trusting either line.

The supporting stack is broad: MySQL, Redis, MongoDB, RabbitMQ, Elasticsearch, Seata for global transactions, Druid for connection pooling, Knife4j for API docs, LogStash for log collection, and OSS or MinIO for object storage. Each of those is another process to run, which is the real cost of this architecture.

Getting mall-swarm running and seeing it work

The README's environment section pins JDK 17, MySQL 5.7, Redis 7.0 and Elasticsearch 7.17 for the development environment. It does not publish a build command, a startup command or a docker-compose file, so the honest first step is not a shell command but a decision about which branch you want, because the README states that master targets Spring Cloud 2025 with Spring Boot 3.5 while dev-v2 targets Spring Cloud 2021 with Spring Boot 2.7. Clone with the project's own URL and inspect which branch you landed on.

git clone https://github.com/macrozheng/mall-swarm.git

The repository layout is the next thing to read, because it tells you which processes exist before you try to start any of them. The README prints the tree in the project structure section, and the module names are the ones you will be launching.

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 -- 配置中心存储的配置

That tree is the whole architecture in one screen: nine Maven modules plus a config directory that the config center serves. Because the README does not document a single startup order, expect to bring up the registry and config center before the business services, since registration and configuration are what the mall services depend on. The README also does not document rollback, so there is no documented way to undo a bad configuration push.

For a first real look at the system, skip the local build entirely and open the two demos the README links. The admin console is at cloud.macrozheng.com/admin/index.html, and the mobile storefront is at www.macrozheng.com/app/, which the README suggests viewing with the browser switched to mobile mode. Seeing the finished product before wiring up MySQL, Redis and Elasticsearch is the cheapest way to decide whether the rest of the setup is worth your afternoon.

Where mall-swarm is the wrong tool

The release history is the clearest limitation. The three listed releases are v1.0.1 from 2020-08-15, v1.0.2 from 2022-06-22 and v1.0.3 from 2024-03-01. The master branch was pushed on 2026-07-31, so the code moves, but there is no release cadence to pin to and no published upgrade notes between those tags. If your organisation requires a versioned artifact with a changelog before you deploy, mall-swarm does not give you one. You would be tracking a branch.

The second limitation is operational weight. A registry, a config center, a gateway, a monitor, three business services, MySQL, Redis, MongoDB, RabbitMQ, Elasticsearch and Seata is not a small footprint, and the README's environment table lists versions and links to external setup guides rather than describing how to run them together. There is no documented docker-compose or Kubernetes manifest in the README itself, even though Docker and Kubernetes appear in the technology list. You will be assembling the runtime environment yourself from the tutorial site or from the config directory.

The third is fit. If you are building a single-team application that will never split into independently deployed services, the gateway plus registry plus config center trio adds failure modes without adding capability. A modular monolith on Spring Boot would get you the same business logic with one process to debug. mall-swarm earns its complexity only when you actually need independent deployment or you are deliberately studying distributed patterns.

How it compares with the single-application mall project

The same author maintains macrozheng/mall, which the README links as the backend project, alongside mall-admin-web for the admin front end and mall-app-web for the mobile storefront. That pairing is the most useful comparison, because it isolates one variable: the architecture.

mall is the monolithic version of the same domain. mall-swarm takes that domain and splits it across the modules listed above, adding a gateway, a registry, a config center and a monitoring center as separate concerns. The business tables, the MyBatis layer and the admin UI are conceptually the same territory; what changes is that a call that was a method invocation in mall becomes a remote call through the gateway in mall-swarm, with the latency, serialization and partial-failure questions that follow.

That makes mall the better choice if you want to read e-commerce business logic without infrastructure noise, and mall-swarm the better choice if the infrastructure is the point. Reading both side by side is arguably the intended use, since the README links them together and points to a separate Spring Cloud tutorial repository, springcloud-learning, for the framework material.

Maintenance, licence and the cost of upgrading

The repository is not archived, and the last push to master was on 2026-07-31, so the code is being touched. The releases are a different story: v1.0.3 dates from 2024-03-01, and the README does not describe a migration path from dev-v2 to master. That gap is the upgrade cost in practice. Moving from the Spring Boot 2.7 branch to the Spring Boot 3.5 branch crosses a Jakarta namespace change in the servlet stack, and the README offers no compatibility notes, no deprecation list and no rollback procedure. Budget for reading diffs rather than following a guide.

The licence is Apache-2.0, which permits commercial use, modification and redistribution, and includes an explicit patent grant. It also requires that you preserve the licence and notice files and state significant changes. This is a description of the licence text, not legal advice; if you plan to ship a derivative, have your own counsel review the NOTICE and attribution requirements.

One practical cost to note: the README's technology table mixes components that are core to the architecture (Spring Cloud, Sa-Token, Seata) with components that are optional conveniences (Portainer, Jenkins, MinIO, OSS). Treat the table as a menu, not a manifest, and decide per component whether your deployment needs it.

Editorial conclusion

Adopt mall-swarm if you want a runnable Spring Cloud Alibaba reference with a real business domain, and you are willing to read the config repository and tutorial site before touching the code. Do not adopt it if you need a maintained product with versioned upgrade notes: the last release is v1.0.3 from 2024-03-01, and the last push to master was 2026-07-31, so the branch moves while the releases do not. Before committing, verify the master versus dev-v2 branch choice against your Spring Boot version, and confirm how mall-auth issues tokens, since the module list still names Spring Security OAuth2 while the README's technology table names Sa-Token.

Frequently asked questions

Official sources

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