微同商城（platform）项目介绍

一句话定位：国内最有名的开源微信小程序商城之一，Java 后端 + uniapp/原生小程序双前端全开源，2018 年入选 Gitee GVP，Apache-2.0 免费可商用 —— 免费给你一个能跑起来的商城底座，想上多商户、直播、分销、多端就买商业版。

1. 项目是什么

微同商城是一套「微信小程序商城」的完整前后端开源实现：后端 Java 单体，前端给两套 —— wx-mall（微信小程序原生）和 uni-mall（uniapp 版），后台管理界面是 Vue 2 + Element UI。

对标的是 CRMEB、likeshop、萤火商城这类「小程序商城源码」产品，但它走的是开源引流 + 商业版变现的路子，所以开源版给得相对实在（前后端全开源、不压缩、无后门）。

它解决的核心问题：

1. 电商通用模块重复造轮子 —— 商品/SKU、订单、购物车、优惠券、支付、会员、地址、物流这些模块已经跑通，拿来就能改业务。
2. 小程序商城的支付与授权链路最磨人 —— 微信登录、手机号获取、微信支付回调、退款这些「官方文档看得懂但跑不通」的部分已完成对接（weixin-java 全家桶）。
3. 毕设与外包的交付压力 —— 结构规范、注释齐全、有文档和视频，是学生毕设和外包接单的高频选择。

不适用的场景：它不是 SaaS 级多租户架构（多租户在商业版）；不追求微服务水平扩展（单体，靠 Redis + 集群部署撑并发）；开源版只有微信小程序端，H5 / App / 支付宝小程序是商业版能力；不适合做 B2B 大宗交易或跨境（无多币种、无复杂审批流）。

2. 核心特性

3. 技术架构

整体结构：标准单体分层（common / biz / admin / api 四模块），两个启动入口 —— 后台管理接口 platform-admin，商城接口 platform-api，共用 platform-biz 业务层与 platform-common 公共层。Web 容器用 Undertow（显式排除了 Tomcat），接口文档用 Knife4j。

技术选型（版本取自仓库根 pom.xml，非宣传口径）：

关键取舍：选 Shiro 而非 Spring Security，配置更轻但生态弱一些；选 fastjson 而非 Jackson，性能好但历史安全事件多；前端停在第 2 代（Vue 2 + Element UI，已停止维护），这是开源版与商业版最实质的差距 —— 管理端技术债是这套代码最大的隐性成本。

项目模块划分（注意：Maven 只认 4 个 Java 模块，UI 与前端目录不在 Maven 生命周期内）：

platform
├── _sql                    初始化脚本（base.sql / mall.sql / sys_region.sql）
├── platform-common         公共模块（工具、常量、异常、返回体）
├── platform-biz            业务代码（核心，商品/订单/会员/营销）
├── platform-admin          后台管理接口服务（启动类 PlatformAdminApplication）
├── platform-api            小程序商城接口服务（启动类 PlatformApiApplication）
├── platform-admin-ui       管理端页面（Vue 2 + Element UI）
├── uni-mall                uniapp 版商城
├── wx-mall                 微信小程序原生商城
├── scripts/                构建与 Docker 启停脚本
├── deploy/                 容器编排、.env 模板、构建产物
└── AGENTS.md               AI 助手启动说明书

4. 目录结构

见上节模块划分。几个关键位置需要记住：

5. 快速上手

环境硬门槛：JDK 21（推荐）、Maven 3.8、MySQL 8.0、Redis 4.0.1+、微信开发者工具。项目用了 Lombok，IDEA / Eclipse 需装插件，否则源码报「缺少 get/set」。

方式 A：丢给 AI 助手（官方首推）

git clone https://gitee.com/fuyang_lipengjun/platform.git
cd platform
# 然后把目录交给 AI 助手，说：「按 AGENTS.md 把这个项目跑起来」
# 它会自动检查运行时、装依赖、引导填配置、建表、启动、验证页面
# 官方称首次配置约 10 分钟

方式 B：手动部署

# 1. 建库（MySQL 8.0），依次导入，顺序不能乱
mysql -uroot -p your_db < _sql/base.sql
mysql -uroot -p your_db < _sql/mall.sql
mysql -uroot -p your_db < _sql/sys_region.sql

# 2. 申请商户号、开通微信支付、下载证书，分别放到
#    platform-admin/src/main/resources/cert/
#    platform-api/src/main/resources/cert/

# 3. 改配置
#    application.yml      → 公众号/小程序 appId、secret、微信支付 mchId/paySignKey/notifyUrl
#    application-dev.yml  → 数据库 url / username / password

# 4. 起 Redis，再分别启动两个启动类
#    PlatformAdminApplication.java
#    PlatformApiApplication.java
#    IDEA 默认访问 http://localhost:8000

# 5. 小程序端：微信开发者工具导入 wx-mall，填 appId，
#    修改 wx-mall/config/api.js 中的 API_BASE_URL 指向本机后端

方式 C：Docker 一键

scripts/build-jars.sh        # 产出 platform-admin.jar / platform-api.jar
scripts/build-admin-ui.sh    # 产出 platform-admin-ui-dist/
cp deploy/.env.example deploy/.env    # 需要改 profile/端口/密码时先复制
scripts/docker-up.sh         # 拉起 mysql + redis + admin + api + nginx
# 管理台 http://localhost:8888
# 停止：scripts/docker-down.sh

MySQL 首次启动会自动执行 _sql/ 下脚本；deploy/data/mysql 已有数据时不会重复导入。

启动失败高频原因：SQL 导入顺序错（sys_region 前置会报外键/主键冲突）；Redis 没起（登录态直接失效）；证书只放了一侧（支付下单成功、回调失败）；JDK 版本低于 21；Maven 卡在 pom 里声明的私有仓库 nexus.dev.dtstack.cn（外部访问不到，见第 11 节）。

6. 功能模块清单

说明：官网把「秒杀、优惠券、多商户、直播卖货、分销」并列宣传为开箱即用，但其中优惠券在开源版可查，多商户/直播/分销对应的是旗舰版与 SaaS 版。采购前务必按第 8 节口径核对。

7. 版本与授权

协议要点

• Apache-2.0：可商用、可闭源分发、可申请软件著作权。
• 官方要求：再次开源时请注明出处。
• 官方立场：个人学习、毕设、商用都允许，但商用推荐购买商业版源码（这是措辞建议，不构成协议限制）。
• 官网承诺「100% 源码交付，无压缩、无后门」—— 开源版本身就是全源码，这条主要针对商业版。

8. 商业模式说明

一句话概括：用一套真正能跑的开源商城做流量入口，把「多端 + 多商户 + 多租户」切给商业版，再靠定制开发和部署服务收尾。

几个要点

• 不标价是明确的销售策略：官网 FAQ 有「开源版和商业版有什么区别」「可以开发票么」「授权期限多久」的问答位，但价格必须走客服 —— 说明走的是询单议价，不是标准电商式售卖。
• 发票与授权期限是它的标准 FAQ 项，说明主要客户是企业而非个人；买之前一定要问清授权期限与续费规则（官网 FAQ 有这条，但内容需询客服）。
• 对使用者意味着什么：开源版能让你零成本把一个真实可用的商城跑到线上，但它刻意保留的缺口（多端、多商户、直播、分销、Vue 3 后台）恰好是稍有规模的商家的刚需 —— 这个「刚需边界」设计得比多数开源项目精明。如果你只做单商家微信小程序，开源版足够；只要沾上多端或多商户，本质上就是付费用户。

9. 生态与周边

扩展方式三条路：① 在 platform-biz 加业务 Service，Controller 分别落到 admin / api；② 用 platform-gen 插件按表生成 CRUD 骨架；③ 前端换皮肤（platform-admin-ui 或 wx-mall 整套替换）。

10. 选型建议

强烈建议用

• 学生毕设、课程设计 —— 模块完整度高、文档齐、能真跑起来，这一档几乎没有更好的选择。
• 单商家微信小程序商城的快速交付（外包 1～2 个月工期），开源版够用。
• 想学「Java 电商系统怎么分层」的开发者 —— 商品/订单/SKU 建模是标准教科书级实现。

可以试试

• 企业自营商城（非平台型），愿意接受 Vue 2 管理端的技术债，或自己升级到 Vue 3。
• 想要「对话式管理」尝鲜的团队 —— 微信 AI 能力的工程封装（工具注册 + 权限校验 + 写操作确认）值得参考。

不建议用

• 要做多商户平台、SaaS 服务商 —— 直接买商业版，别在开源版上硬改，改造成本高于授权费。
• 追求 Vue 3 全家桶、长期维护的团队 —— 开源版管理端停在第 2 代，是明确的负债。
• 高并发秒杀型业务 —— 单体 + MySQL，架构不匹配。

同类对比

11. 风险与坑

部署层

• SQL 必须按 base → mall → sys_region 顺序导入，顺序错会报主键/外键冲突。
• 微信支付证书要放两处（admin 与 api 各一份），只放一处会出现「下单成功、回调验签失败」。
• Redis 是硬依赖，没起 Redis 登录态直接废。
• JDK 必须 21，低版本编译不过；Lombok 插件不装，IDE 满屏红线。
• 端口差异：IDEA 启动是 8000，Eclipse 是 8080，网上老教程的端口不能照抄。

依赖层（最容易踩且最难查）

• 根 pom.xml 里声明了私有 Nexus 仓库 nexus.dev.dtstack.cn。外部网络访问不到，若有依赖仅存在于该仓库，构建会卡在下载或直接失败。构建异常优先怀疑这里，可尝试注释该 repository 走阿里云公共仓。
• fastjson 用的是 com.alibaba:fastjson 的 2.x 兼容包（版本号 2.0.53 但 artifact 是 1.x 系），别当成 fastjson2 用。
• 项目 2018 年起源，网上大量第三方文章还停留在 springframework 4.3.7 + mysql5.1 时代的技术选型，以仓库 pom.xml 为准。

商业与信息一致性层

• 官网 FAQ 说开源版是「SpringBoot2 + Vue2」，但仓库主分支后端已升到 Spring Boot 3.2.5（前端 Vue2 这点没错）。升级是分步走的，宣传口径滞后于代码，别被 FAQ 里的版本号误导。
• 官网把秒杀、多商户、直播、分销并列宣传，很容易看成开源版功能 —— 实际只有优惠券在开源版可查，采购前逐项问客服确认。
• 微信 AI 能力仍在灰度内测、暂未开放提审，手机端要求微信 ≥ 8.0.75、调试基础库 ≥ 3.16.1。当技术预研可以，别写进上线计划。
• Apache-2.0 允许商用，且协议上不强制买商业版；「商用推荐购买商业版」是官方建议，不是法律限制。但二次开发规模大了，商业版的支持价值会超过自研成本。
• 前端 Vue 2 + Element UI 已停止官方维护，长期项目要考虑安全补丁来源。

生产落地 checklist

• ✅ 三份 SQL 按序导入完成，省市区数据完整
• ☐ 微信商户号、支付证书两侧就位，支付与退款各跑一笔真实交易
• ✅ Redis 已做持久化与密码保护，非默认端口
• ✅ application.yml 中微信 appId/secret/商户号已从示例值替换
• ✅ 私有 Nexus 依赖已清理或镜像化，构建可离线复现
• ☐ 管理端默认账号已改，后台路径考虑加白名单
• ✅ 商品图片存储已切到自有 OSS/MinIO，不用本地目录
• ✅ 定时任务、订单超时关闭已验证触发

12. 参考链接