改需求 ≠ 改主干
二开包以 owner: custom 在构建期打进宿主，零运行时开销；官方发版覆盖不到你的实现，升级不再人人自危。
v1.0 开源 · MIT 协议 · Java 21 / Spring Boot 3.2
一套 Core 打底，
插件与二开各走一条通道
HouMall 是面向真实交易场景的插件化开源商城系统： BFF 作为唯一入口兼任网关，PF4J 插件运行时负责安装、启停与扩展点分发， 官方主干、二次开发、第三方插件三条通道共用同一套契约却互不干扰。 改价格算法不必改主干，装 ERP 不必重启商城。
- 6层架构栈
- 11个内置扩展点
- 3条交付通道
- 17+ 前端应用
code: mall-coupon
name: 优惠券
version: 1.2.0
owner: thirdparty # official | custom | thirdparty
runtime: embedded # embedded | standalone
host: mall
extensions:
- point: goods.PriceCalcExtension
class: com.houjiang.coupon.ext.CouponPriceCalc
priority: 100
menus:
- { path: /mall/coupon, title: 优惠券, sort: 3610 }
frontend:
entry: /plugin-assets/mall-coupon/1.2.0/index.mjs
一份 plugin.yaml 同时驱动：扩展点注册、菜单注入、接口路由、前端资源加载。
技术栈
Java 21Spring Boot 3.2.4Spring Cloud Alibaba 2023
NacosOpenFeign 4.1MyBatis-Plus 3.5.7
MySQL 8RedisRocketMQSeata
PF4JVue 3.5Vite 7Element PlusPinia
为什么是 HouMall
商城系统的痛点，从来不是「能不能下单」
是客户要改一句价格算法，你就得 fork 一份主干；是卖出去的 ERP 和商城死死耦合；是每接一个新渠道都要重新发版。
卖能力 ≠ 塞代码
ERP、OA、财务、MES、收银台、配送以独立插件制品交付。装了才有菜单、接口和表；没装，Core 照常登录、浏览、下单、支付。
可扩展 ≠ 可拖垮
高频链路（认证、定价、下单、库存、支付）在启动期冻结成不可变快照；单个扩展点 200ms 超时、异常只记录不传播。
核心能力
从商城交易闭环，到插件商业化闭环
下列能力均有对应源码模块与文档落点，不是 Roadmap 上的空头支票。
商城交易主干
商品 SPU/SKU/分类/品牌/库存、订单与售后、支付（微信 / 支付宝 / 余额）与对账、商户入驻与结算、供应商协同，覆盖完整交易闭环。
- goods / order / payment
- merchant / supplier
BFF 统一入口
bff-web 是浏览器请求的唯一 HTTP 入口，承担鉴权、租户上下文、DTO 聚合与插件代理，不额外部署一层网关；限流 / WAF / TLS 交给 Nginx 与云 LB。
/web/**统一路由/web/plugin/{code}/**泛化分发
插件中心与市场
插件的概览、筛选、安装、启停、卸载与配置抽屉，配合市场商品、版本、License 授权；制品落盘后做摘要与签名校验。
hou_addon_plugin安装态PluginArtifactStore校验
扩展点机制
扩展点契约统一收在 plugin-api，实现随插件或二开。当前内置 11 个：定价、库存变更、运费、下单前后、支付回调、登录后、菜单注入、仪表盘、促销三件套。
- 不可变快照 + 优先级冻结
- 无插件时零开销
前端插件运行时
宿主通过远程 ESM import() 加载插件产物，动态 router.addRoute、自动注入菜单、卸载触发 teardown，加载失败自动兜底。
- 接口统一走
ctx.callApi - 插件前端与宿主样式隔离
多端开箱
平台管理后台、商城 PC 前台、uni-app 移动端、商家端、供应商端、会员中心、IM 客服、内容管理、收银台与配送端，共 17+ 前端应用。
- Vue 3.5 + Vite 7 + Element Plus
- 桌面端可用 Electron 打包
架构
六层栈 + 一条请求链路
所有设计只回答一个问题：新能力进来时，谁都不用动。
L1接入层BFF（bff-web）唯一入口，兼任网关；插件通道
/web/plugin/**L2宿主层mall / goods / order / payment / auth …（standalone 或 embedded）
L3能力层插件与二开（embedded 进宿主，或运行期热插拔）
L4接口层
backend/contracts/{module}-api，按需建立的稳定契约L5基础设施commons / plugin-platform / MySQL / Redis / MQ
L6工具链Maven 反应堆 / CI 门禁 / 部署脚本
请求链路
frontend/admin 等前端
→ BFF（入口 + 鉴权 + 租户上下文 + 聚合 + 插件代理）
→ Core PaaS 平台服务
→ 商城核心领域（goods / order / payment / merchant / supplier / mall）
→ 扩展点快照（官方 · 二开 · 插件 · 降级）
→ 数据库 / 消息 / 对象存储 / 第三方平台D1 不新增独立 Gateway，BFF 兼任
D2/D3 契约与 Feign 分离，跨模块只依赖契约
D4 扩展点契约统一放
plugin-apiD5 契约测试、trace/metrics、灰度回滚为门禁
模块地图
开源 Core 里到底有什么
全部模块在 backend/paas/ 平级组织，多进程 + Nacos + OpenFeign，不堆层级。
| 模块 | 职责 | 归属 |
|---|---|---|
commons | 公共基础（DTO / VO / 工具 / Token） | Core |
auth | 认证授权 | Core |
base | 基础数据（地区 / 配置 / 文件 / 短信 / 邮件） | Core |
permission | 角色、菜单、数据权限 | Core |
userms | 用户、员工、组织 | Core |
thirdparty | 短信 / 邮件 / OSS / 企微 / 钉钉 / 飞书等通用外部能力 | Core |
goods | 商品 SPU / SKU / 分类 / 品牌 / 库存 | Core |
order | 下单、退款、物流、售后 | Core |
payment | 支付渠道、余额、对账 | Core |
merchant | 商家入驻、店铺、结算 | Core |
supplier | 供应商协同 | Core |
mall | 插件中心宿主 + 插件引擎装配 + 商城聚合宿主 | Core |
plugin-sdk / plugin-engine | 插件开发 SDK 与 PF4J 运行时 | Core |
erp · oa · finance · mes | 企业资源计划 / 协同办公 / 财务 / 生产执行 | 商业插件 |
webpos · rider · dcenter | 门店收银台 / 骑手 / 配送调度 | 商业插件 |
插件与二开
一个能力包，两个开关，三种交付
一份 plugin.yaml 加 owner / runtime 两个开关，派生出内建服务、内建能力、二开包、第三方插件四种形态。学一次，会两种交付。
| 通道 | 身份 | 生效时机 | 典型场景 |
|---|---|---|---|
| A 官方主干 | owner: official | 发版重启 | 商品、订单、优惠券 |
| B 二开覆盖 | owner: custom | 构建期打进宿主 | 改价格算法、换 OSS |
| C 插件热插拔 | owner: thirdparty | 运行期热插拔 | 拼团、新推送通道 |
关键区别：二开是「换掉」官方实现（构建期、零运行时开销）；插件是「追加」官方钩子（运行期、有注册开销）。
// backend/extensions/custom-goods —— 不改一行主干，覆盖定价
@HouExtension(
point = "goods.PriceCalcExtension",
owner = "custom", // 官方 priority = 0，二开 = 100
priority = 100
)
public class VipPriceCalc implements PriceCalcExtension {
@Override
public void execute(PriceCalcContext ctx) {
long amount = ctx.in().getSkuAmount();
if (ctx.in().getUserLevel() >= 3) {
ctx.out().setPayAmount(amount * 9 / 10); // 会员 9 折
}
}
}code: custom-goods
name: 商品二开包
version: 1.0.0
owner: custom
runtime: embedded
host: mall
apis:
- plugin-api
- goods-api// 插件前端：ESM 产物由宿主远程加载，自动注册路由与菜单
export default {
install(ctx) {
ctx.addRoute({ path: '/mall/coupon', component: () => import('./views/Coupon.vue') });
ctx.callApi('/coupon/list'); // 收敛到 /web/plugin/mall-coupon/**
},
teardown() { /* 卸载时清理 */ }
}
快速开始
四步跑起来
下面每条命令都来自项目实际构建链路，不是示意。
-
1
克隆仓库
git clone <你的仓库地址> houcloud && cd houcloud -
2
安装插件契约与 SDK
plugin-platform是反应堆根，先把plugin-sdk与plugin-api装进本地仓库。cd plugin-platformmvn -o -q -DskipTests -pl sdk/plugin-sdk,../backend/contracts/plugin-api install -
3
构建并启动 Core 服务
按需构建，
-am会自动带上依赖模块；对外入口bff-web默认端口 8391。mvn -DskipTests -pl bff/bff-web -am clean package -
4
启动管理后台
cd frontend/admin && npm install && npm run dev
环境要求：JDK 21+ · Maven 3.8+ · Node 20.19+ / 22.12+ · MySQL 8 · Redis · Nacos 2.x。
增量编译会引发
NoClassDefFoundError，后端构建请务必带 clean。
路线图
阶段与门禁
阶段之间必须通过上一阶段的验收门禁：工作完成、产物存在、验证通过、文档同步，四条同时满足才算 OK。
M0 方案与边界冻结
模块归属、目录决策、商业插件边界与二开形态定稿
M1 Core API 与依赖基线
契约抽取、扩展点契约、二开依赖白名单与契约测试门禁
M2 BFF 与 Adapter 基础架构
/web/plugin/{code}/** 通道、插件中心 / 市场 / License 服务
M3 Plugin Engine 真实宿主
PF4J 装载、扩展点注册与不可变快照、集成测试闭环
M4 frontend/admin 插件宿主
插件中心页面、动态路由、菜单注入与前端资源加载
M5 ERP 首个纵向插件
首个完整商业插件纵向迁移，验证独立交付与授权
M6 OA 与财务插件
多商业插件共存与跨域协作走 Core 事件与扩展点
M7 商城聚合及其他插件迁移
分销、积分、返利、风控、装修等聚合业务插件化
M8 商业运营与稳定性
性能、trace/metrics、灰度回滚与运维 tooling 完善
FAQ
你大概会问这些
开源的是哪些部分？商业插件怎么拿？
Core（认证、权限、用户组织、商品、订单、支付、商户、供应商、第三方基础能力、插件中心与插件引擎）全部开源。ERP、OA、财务、MES、收银台、骑手配送以及商城营销类聚合能力以独立插件制品交付，未安装时 Core 依然可以独立登录、浏览、下单和完成基础支付。
二开和插件到底有什么区别？
区别在于「换掉」还是「追加」：二开（owner: custom）在构建期打进宿主，用来替换官方实现，零运行时开销；插件（owner: thirdparty）在运行期热插拔，用来追加官方钩子。两者的元数据、目录结构、前端契约与扩展点写法完全一致。
插件把系统拖垮了怎么办？
扩展点在注册与卸载期生成按优先级冻结的不可变快照，读路径零复制零排序；单个扩展点 200ms 超时，插件异常只记录不向上传播；没有插件时链路零开销。高频链路（认证、定价、下单、库存、支付）都走快照，不扫描 Class、不扫描插件目录。
为什么还要 BFF，不直接上 API Gateway？
BFF 已经在做统一入口、鉴权、租户上下文与前端聚合，再加一层独立业务网关只会多一跳和一套配置。限流、WAF、TLS、负载均衡交给 Nginx 与云 LB 更合适，这是架构决策 D1 的结论。
可以商用吗？
可以。项目以 MIT 协议开源，允许商用、修改、分发与再许可，只需保留版权声明。注意商业插件制品与授权不包含在 Core 的开源范围内。