# Mall4j review: a Spring Boot 4 and Vue3 B2C mall source code under AGPLv3

> Mall4j's open repository is a single-tenant B2C mall built on Spring Boot 4, Sa-Token, MyBatis-Plus, Redis and Vue3, published under AGPLv3. It is a solid reading and prototyping base, but the licence and the split between open and commercial editions decide whether you can ship it.

**gz-yami/mall4j** — ⭐️⭐️⭐️ 电商商城 小程序电商商城系统 PC商城 H5商城 APP商城 Java商城 O2O商城 跨境商城

- Repository: https://github.com/gz-yami/mall4j
- Website: https://www.mall4j.com
- Stars: 5,264 · Forks: 1,361
- Language: JavaScript
- License: AGPL-3.0
- Published: 2026-09-23 · Updated: 2026-09-23 · Language: en
- Canonical page: https://hysenlabs.com/projects/gz-yami-mall4j

## What Mall4j's open repository actually covers

The README is explicit that this repository is the main open-source repository of a larger product family, and that the open edition targets a single-merchant B2C storefront. The feature list it gives is a conventional commerce core: products, orders, members, specification and SKU handling, cart, payment, permissions, content and statistics. The admin side is described as covering product management, order management, freight templates, specification management, member management, operations, content management, reporting, permissions and system settings.

The audience stated in the README is narrow on purpose: learning, evaluation, secondary development, and enterprise mall prototyping. That framing matters. If you need multi-merchant settlement, supply chain, SaaS tenancy or cross-border flows, the README points you at the commercial editions on the official site rather than at this code. The repository is not a stripped-down teaser of those editions; the README says the enterprise version system is not the same as an enhanced version of this repository, which is an unusually direct statement about scope.

One structural detail worth noting for anyone planning a fork: the backend is split into Maven modules by responsibility, with yami-shop-admin, yami-shop-api, yami-shop-bean, yami-shop-common, yami-shop-security, yami-shop-service and yami-shop-sys at the top level, alongside front-end/, db/, doc/ and docker-compose.yml. That layout tells you the intended separation between the admin application and the storefront API before you read a single class.

## Architecture and data flow in the Mall4j backend

The README names the stack directly: Spring Boot 4 and Vue3 with a separated frontend and backend, Sa-Token for authentication and authorization, MyBatis and MyBatis-Plus for persistence, Redis for caching, and Redisson for distributed locks. The lock detail is the one that says the most about intended deployment. Redisson-backed distributed locks exist because the README states the project is intended to suit production multi-instance deployment. A single-process demo mall does not need them; a mall running more than one application instance does, because cart and order operations race across instances.

The dependency table lists Spring Security web alongside Sa-Token, plus spring-doc, jakarta-validation, Hikari for connection pooling, Logback, Lombok, Hutool and Knife4j for the API UI. The README also notes it was scanned with the Alibaba Java Coding Guidelines plugin with no reported issues, which is a style claim, not a correctness claim.

Two applications are separated at the process level. The admin backend and the storefront API are distinct services with distinct ports, and docker-compose.yml confirms this: mall4j-admin is exposed on 8085 and mall4j-api on 8086. Both connect to a MySQL container and a Redis container, and both receive REDIS_HOST, REDIS_PORT and REDIS_DATABASE=1 as environment variables. The database container runs with the flag --lower_case_table_names=1, which is the kind of setting that bites you later if you move to a managed MySQL instance that refuses to start with it. The README does not document a rollback path for schema changes, so treat the db/ directory as the source of truth for what the schema expects.

## Installing Mall4j with Docker Compose and reaching the admin app

The README points at doc/, the Gitee wiki and a Bilibili video for environment setup, and says to read the documentation before the video. The repository itself ships a docker-compose.yml at the top level, which is the fastest route to a running pair of services without assembling MySQL and Redis by hand.

The compose file defines four services: mall4j-mysql built from ./db/Dockerfile, mall4j-redis on the redis:5.0.4 image, mall4j-admin built from ./yami-shop-admin/Dockerfile, and mall4j-api built from ./yami-shop-api/Dockerfile. Bring them up from the repository root:

```bash
docker compose up -d
```

Expect four containers. The MySQL container sets MYSQL_ROOT_PASSWORD to root and mounts ./mall4j-mysql as the data volume, so the first start initializes the schema from the db/ context. The admin application waits on the Redis and MySQL containers via depends_on and links, and it is published on host port 8085; the API is published on 8086. If you are running the backend outside Docker instead, the compose file shows which environment variables the applications read:

```yaml
environment:
  - REDIS_HOST=mall4j-redis
  - REDIS_PORT=6379
  - REDIS_DATABASE=1
```

Point REDIS_HOST at your own Redis host and keep REDIS_DATABASE at 1 unless you change it in configuration too. The frontend is not part of this compose file; the README lists the Vue3 admin frontend in the separate mall4v repository, the native WeChat mini program in mall4m, and the uni-app multi-end frontend in mall4uni. The README also mentions an Agent Skill shipped in .agents/skills/mall4j/ (with a copy under .claude/skills/mall4j/) intended to assist with startup, usage and secondary development for the existing feature set. That is a documentation aid, not a runtime dependency.

## Where Mall4j is the wrong tool

The licence is the first hard boundary. The repository is AGPLv3, and the README states plainly that closed-source commercial use requires a separate commercial authorization obtained through the official site. AGPLv3 is a network-copyleft licence: if you run a modified version as a network service, the source-availability obligation follows the service, not just the distributed binary. If your business model depends on keeping your storefront customizations private, this repository is the wrong starting point, and no amount of code quality changes that.

The second boundary is functional scope. The open edition is a single-merchant B2C mall. If your requirement is multi-merchant onboarding, supply chain, SaaS multi-tenancy or cross-border commerce, the README directs you to commercial editions and explicitly says the enterprise version system is not an enhanced version of this repository. Buying the commercial edition is therefore not a matter of unlocking features hidden in this code; it is a different product line.

The third is documentation depth in the repository itself. The README defers deployment detail to doc/, the wiki and a video, and it does not document rollback, migration strategy or upgrade procedures for the database. The dependency table repeatedly says versions are governed by pom.xml and package.json, which means the README table is a stable overview, not a version manifest. Anyone who pins a dependency from the README table alone is guessing. The compose file also pins Redis to 5.0.4, an old tag; the README does not discuss upgrading it, and Redisson behaviour on newer Redis versions is not addressed in the repository documentation.

## Mall4j compared with other Java mall source projects

The searches people run around this project consistently land on a small set of alternatives: Macrozheng's mall, Litemall, CRMEB, ShopXO and NiuShop. The useful distinction is not which one has more features but which one matches your deployment shape and licence tolerance.

Macrozheng's mall is the closest architectural sibling: a Spring Boot based mall reference project with a separated admin frontend. The difference that matters here is the framework baseline. Mall4j's README states the mainline has moved to Spring Boot 4 and Vue3, with the v4.0 release described as a Spring Boot 4 upgrade and v3.3 described as adding virtual thread support. A project still on an older Spring Boot line will face framework upgrade, dependency compatibility and security maintenance work that Mall4j has already done, which is the argument the README itself makes for new evaluations.

Litemall is a lighter, older Node and Spring Boot combination aimed at learning; it is not positioned as a production multi-instance deployment. CRMEB and NiuShop are PHP-based commercial product lines, so the comparison is not really about code but about the ecosystem you want to hire for and the licence terms you accept. ShopXO is likewise PHP. If your team is Java-only and you want Sa-Token, MyBatis-Plus and Redisson in the stack, Mall4j sits in a different category from those PHP options. If your team is PHP-first, none of Mall4j's Java architecture helps you, and the AGPLv3 question disappears because you were never going to use it.

## Maintenance, upgrades and what AGPLv3 costs you

The repository is not archived, and the last push was on 2026-09-14. The release history shows v4.0 on 2026-03-19 described as the Spring Boot 4 upgrade, v3.4 on 2025-03-10 for Spring Boot 3.4, and v3.3 on 2024-04-24 adding virtual thread support. That cadence is roughly annual on major framework alignment, with the 2026-09-14 push showing recent activity beyond the last tagged release.

Upgrade cost is concentrated in two places. The first is the framework baseline: Spring Boot 4 and Vue3 mean your team must be comfortable on a recent Spring line, and any in-house modules written against an older Spring Security or MyBatis configuration will need rework. The second is the database. The compose file runs MySQL with lower_case_table_names=1, which is a container-level startup flag; the README does not describe how schema changes are versioned or rolled back, so you should read db/ before planning an upgrade and treat the README as silent on migration tooling.

Licence implications, without legal advice: AGPLv3 covers this repository. The README states that learning, research, secondary development and self-deployment are permitted under the licence, and that closed-source commercial use, private enterprise delivery, multi-merchant, supply chain, SaaS and cross-border versions fall under commercial authorization. The README further states that the commercial edition delivers 100% source code, unencrypted, with a permanent licence, subject to the official site and contract. If your legal position cannot accept network copyleft, the correct action is to contact the vendor through the official site before you write a line of customization, not after.

## Conclusion

Adopt the open repository if you are evaluating Java mall architecture, teaching, or building a prototype whose licensing you can satisfy under AGPLv3. Do not adopt it as a drop-in base for a closed-source commercial storefront: the README states that closed-source commercial use requires a separate commercial licence from the official site, and multi-merchant, SaaS and cross-border scope is not in this repository. Before committing, read doc/ and the wiki, confirm the dependency versions in pom.xml and package.json rather than the README table, and check whether your deployment can meet AGPLv3 source-availability terms.

## FAQ

### What is Mall4j and who is the open repository for?

Mall4j is a Java mall source code product family, and this repository is the main open-source repository aimed at single-merchant B2C storefronts. The README says it suits learning, evaluation, secondary development and enterprise mall prototyping.

### Can I use Mall4j's open repository for free in a commercial project?

The README states the open repository is licensed under AGPLv3 and can be used freely provided the licence terms are respected. Closed-source commercial use requires a separate commercial authorization obtained through the official site.

### How do I start Mall4j locally?

The repository ships a docker-compose.yml at the top level that starts MySQL, Redis, the admin application on port 8085 and the API on port 8086. The README recommends reading doc/ and the wiki first, and provides a Bilibili video for development environment setup.

### Does Mall4j support Spring Boot 4 and Vue3?

The README states the mainline has been upgraded to Spring Boot 4 and Vue3, and the v4.0 release is described as the Spring Boot 4 upgrade. It adds that exact dependency versions are governed by the backend pom.xml and the frontend package.json.

### Is the Mall4j commercial edition source code encrypted?

The README states the commercial edition delivers 100% source code with no encryption and a permanent licence. It adds that the exact delivery scope, authorization terms and service content are governed by the official site and the contract.

## Sources

- [gz-yami/mall4j on GitHub](https://github.com/gz-yami/mall4j)
- [License: AGPL-3.0](https://github.com/gz-yami/mall4j/blob/master/LICENSE)
- [Project website](https://www.mall4j.com)
- [README](https://github.com/gz-yami/mall4j/blob/master/README.md)
- [Releases](https://github.com/gz-yami/mall4j/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/gz-yami-mall4j