简介这是一套基于微服务架构的Java分销管理系统完整源码面向需要学习分布式业务拆分、权限管控与订单流转的Java开发者。资源涵盖前端页面、后端服务与数据脚本包含404个Java文件、599个JavaScript文件及201个HTML页面辅以CSS样式、XML映射、SQL初始化脚本和yml配置能够清晰呈现从界面交互到服务调用的完整链路。压缩包共1643个文件整体大小15.02MB便于快速下载与本地部署。目前已有480人学习参考适合用于课程设计、毕设二次开发或微服务入门实战。通过研读源码读者可以掌握分销关系管理、多模块协作、接口设计等关键思路并借助其中附带的构建脚本与容器配置快速启动项目。1. 这套源码的真正门槛不在微服务而在分销那套账怎么算得平如果你带着「跑通一个 Spring Cloud 项目」的心态去打开这份源码大概率会卡在一个更尴尬的地方服务能起来订单也能下但佣金算出来是错的。微服务下的 Java 分销管理系统表面上是 Nacos、Gateway、Feign 那套东西骨子里却是分销关系、佣金计算、提现结算这些和钱有关的业务逻辑。这个领域最典型的问题不是「接口报 500」而是「接口正常返回但月底对账差几块几毛」。这套源码适合两类人一类是想看微服务真实落地长什么样的 Java 工程师另一类是要在分销业务上做二次开发、想知道佣金链路该怎么设计的开发负责人。它几乎覆盖了微服务面试题里的高频考点——服务拆分、注册发现、配置中心、异步解耦、幂等设计而且每一项都挂在具体的分销业务场景上不是那种空转的 demo。2. 先画清楚微服务架构图分销系统到底要拆出哪些服务2.1 从单体到微服务分销系统的边界划分思路拿到任何源码第一步不是看代码而是先画微服务架构图把服务边界理清楚。分销管理系统和普通电商系统的差别在于多了一条钱的分发链路用户下单后平台要把利润按比例分给上级推荐人、代理、股东。这条链路天然适合独立成一个服务因为它对一致性的要求、对账的频率和商品订单完全不同。我见过的典型拆分方案是这样的这份源码大概率也遵循类似结构服务职责独立数据库gateway-service统一入口、路由、限流、鉴权无member-service会员、分销关系、等级、上下级查询member_dbproduct-service商品、分类、库存product_dborder-service订单、支付回调、售后order_dbcommission-service佣金计算、佣金明细、提现、余额commission_dbsystem-service后台用户、角色、菜单system_db为什么佣金要单独拆一个服务两个原因。第一佣金计算是异步的、批量的某个用户下单后要触发一串上级的分佣计算如果写在下单事务里订单接口会被拖慢第二佣金和提现涉及资金账户必须和订单数据做物理隔离避免一个慢 SQL 把整个下单链路拖垮。如果你拿到的是多商户版本还会多一个 merchant-service也就是类似若依微服务plus那种平台 商户的双层结构分销关系会加上 merchant_id 维度。这里想提醒一点不要因为服务拆得多就觉得高级拆的目的永远只有一个——让变更频繁的模块独立部署让资金相关的模块严格隔离。2.2 分库与数据隔离微服务下分销数据怎么落库微服务拆分后最直观的变化是数据库拆了。member_db 里存会员和分销关系order_db 里存订单commission_db 里存佣金和提现。表之间不再有外键跨库查询全部走接口调用。分销关系表是最核心的一张常见设计是CREATE TABLE member_distribution ( id bigint NOT NULL AUTO_INCREMENT, member_id bigint NOT NULL COMMENT 会员ID, parent_id bigint DEFAULT NULL COMMENT 直接上级推荐人ID, agent_level tinyint DEFAULT 0 COMMENT 代理等级0普通1银牌2金牌, parent_path varchar(255) DEFAULT NULL COMMENT 冗余的上级路径逗号分隔, create_time datetime DEFAULT NULL, PRIMARY KEY (id), UNIQUE KEY uk_member_id (member_id), KEY idx_parent_id (parent_id) ) ENGINEInnoDB DEFAULT CHARSETutf8mb4;这里有两个关键设计。第一个是 parent_id记录直接上级第二个是 parent_path把从顶级到当前节点的整条路径冗余出来比如1,3,8表示上级链是会员1 → 会员3 → 会员8。这样查询某个节点的所有上级就不用递归直接用 FIND_IN_SET 或者把 path 拆开做 in 查询这对佣金计算的性能影响非常大。很多分销源码用的是递归 CTEMySQL 8.0层级浅还好一旦代理体系做到三级以上或者单节点下挂几千人递归就很吃力。再说表名里的 utf8mb4分销系统经常要存 emoji 表情和生僻字比如用户昵称、备注用 utf8 会报错或者乱码这是最基础但最常见的一个设置。而且现在用 MyBatis-Plus 的话可以直接在实体类上加 TableName 注解让表名和实体对应配合它的代码生成器先建实体类再同步建表挺省事。2.3 服务间的调用链用 OpenFeign 跨服务拿会员信息服务拆完之后跨服务调用是避免不了的。佣金服务计算分佣时需要知道订单是谁的、订单金额多少、下单人属于哪个代理等级这些数据分散在 order-service 和 member-service 里。最常用的方案是 OpenFeign 声明式 HTTP 调用。FeignClient(name member-service, fallback MemberFeignFallback.class) public interface MemberFeignClient { GetMapping(/member/distribution/path/{memberId}) RListLong getParentPath(PathVariable(memberId) Long memberId); }FeignClient 接口定义了三样东西服务名对应 Nacos 上注册的 member-service、调用路径、降级处理。fallback 的作用是 member-service 挂了的时候佣金服务不至于直接抛异常而是走一个返回空列表的兜底逻辑。但注意降级只解决「拿不到数据怎么办」的问题不解决「数据拿错了怎么办」的问题——如果 member-service 响应超时Feign 默认会重试重试在查询场景没问题但如果是下单扣库存这种写操作重试就会产生重复数据。所以在分销系统里我一般会建议把 Feign 的超时时间调小比如连接超时 2000ms、读超时 3000ms并且对写操作关闭重试。2.4 典型链路下单支付完成后佣金是异步算的分销系统的核心链路不是同步的。用户下单 → 支付成功 → 订单服务更新订单状态 → 发送一条 MQ 消息「订单已支付」→ 佣金服务消费消息查出分销链逐级计算佣金并写入佣金明细。这中间有两个关键点。第一订单服务和佣金服务之间绝对不能同步调用因为佣金计算要对同一订单的多个上级分别算还要查商品的分佣比例耗时不稳定。同步调用会把订单支付的接口拖垮。第二支付回调是关键触发点。订单状态必须是「已支付」才允许算佣金用户下单未支付就关单这种订单不能进入分佣链路。所以消息发送应该放在支付回调成功、订单状态更新之后而不是下单接口里。3. 落地之前的基建选择Nacos、Gateway、MyBatis-Plus 和多模块工程结构3.1 注册中心与配置中心为什么这类源码都用 Nacos微服务首先要解决「服务之间怎么找到彼此」的问题。早些年常见的是 Eureka但社区停止更新后新项目基本都迁移到了 Nacos。Nacos 把服务发现和配置中心合二为一分布式配置不用单独再上一套 Apollo对中小团队来说少维护一个组件。而且 Nacos 自带控制台服务是否注册成功、配置是否生效打开浏览器就能看到排查问题的路径短。Nacos 的配置写法很固定每个服务里都有一个 bootstrap.ymlspring: application: name: commission-service cloud: nacos: discovery: server-addr: 127.0.0.1:8848 namespace: dev config: server-addr: 127.0.0.1:8848 namespace: dev file-extension: yml注意这里有几个参数值得展开。server-addr 是 Nacos 服务端地址本地开发就是 127.0.0.1:8848上到测试环境就得换成 Nacos 所在服务器的内网 IP。namespace 是环境隔离的关键dev、test、prod 各建一个命名空间服务启动时读取对应的配置避免测试环境连到生产数据库这种事故。file-extension 指定配置文件后缀dataId 的默认规则是${spring.application.name}.${file-extension}也就是 commission-service.yml。如果你遇到服务启动失败先不要怀疑代码按这个顺序排查先看 Nacos 服务是否启动、端口 8848 是否通再看 bootstrap.yml 里的 namespace 是否填对最后看服务是否成功注册到了 Nacos 控制台。这类问题十有八九是环境配置问题和业务代码没关系。3.2 网关层统一入口Spring Cloud Gateway 的路由与统一鉴权所有前端请求都先进网关网关再做路由分发。Spring Cloud Gateway 是目前的主流选择它的路由配置是纯声明式的spring: cloud: gateway: routes: - id: member-route uri: lb://member-service predicates: - Path/api/member/** filters: - StripPrefix1 - id: order-route uri: lb://order-service predicates: - Path/api/order/** filters: - StripPrefix1这里面的参数值得逐个说清楚。id 是路由的唯一标识自定义即可但不要和别的路由重名。uri 用lb://开头表示从负载均衡器拿服务实例后面跟的是 Nacos 里注册的服务名不是 IP。Predicates 里的 Path 是匹配规则意思是凡是/api/member/**开头的请求都转发到 member-service。StripPrefix1 表示去掉第一段路径前端请求打过来是/api/member/list网关转发给 member-service 的时候会变成/member/list这要求服务内部的 Controller 定义里带/member前缀或者不带两边要对齐这是新手最容易搞混的地方。统一鉴权一般写一个 GlobalFilter从请求头里取 token调用 member-service 或者本地解析 JWT校验通过才放行。注意网关过滤器里不要做太重的逻辑它要转发所有服务的请求一旦这里出现慢逻辑全站接口一起变慢。3.3 MyBatis-Plus 在微服务里的用法实体类建表、逻辑删除、分页插件分销系统的数据访问层基本都用 MyBatis-Plus原因很简单单表 CRUD 不用写 XML分页插件现成代码量和维护成本比纯 MyBatis 低不少。而且 MyBatis-Plus 支持根据实体类生成创建表的 SQL 语句从实体出发反向设计表结构在微服务的多个服务里建表时很效率。Data TableName(commission_detail) public class CommissionDetail { TableId(type IdType.ASSIGN_ID) private Long id; TableField(order_no) private String orderNo; TableField(member_id) private Long memberId; TableField(from_member_id) private Long fromMemberId; TableField(amount) private BigDecimal amount; TableLogic TableField(deleted) private Integer deleted; }这里的几个注解是 MyBatis-Plus 的核心。TableName 指定实体对应的表名不写的话默认用类名转下划线多数据库命名不规范时就容易对不上。TableId 指定主键策略ASSIGN_ID 是雪花算法生成分布式ID在微服务场景下比自增主键好用因为多个服务各自写库用自增ID容易冲突。TableLogic 是逻辑删除删佣金明细时不是物理 delete而是把 deleted 置为 1查询自动带deleted 0好处是误删了能恢复。如果你是做分销系统的佣金明细这种数据强烈建议保留逻辑删除财务对账的时候你要能解释清楚每条数据的去留。分页插件需要在每个服务里配置一个 MybatisPlusInterceptor Bean否则 Page 对象不生效。3.4 多模块工程在本地怎么统一启动这套源码是用 Maven 多模块组织的一个聚合工程下面挂多个 service 模块。打开工程后如果一个个手动启动微服务来回切换很痛苦。常见做法是在 IDEA 里新建一个 Compound Configuration把多个 Spring Boot 启动类加进去一键启动。如果是用 VS Code可以在 launch.json 里定义多个配置再用 compounds 把几个 main 类合起来统一启动效果一样。启动顺序上先把 Nacos 和 MySQL、Redis 起好再起来网关最后起业务服务。顺序搞反了也不至于启动失败但服务注册会有先后网关路由在 Nacos 里找不到实例时会报 503。4. 分销核心链路代码拆解佣金怎么算、提现怎么走、账怎么平4.1 多级分佣的查链逻辑不要递归查库佣金计算的第一步是找到下单人的所有上线。假设分销规则是三级分佣一级上线拿订单金额的 5%二级拿 3%三级拿 2%。那我要查出这个下单用户的 parent_id再查 parent_id 的 parent_id一直到第三层。最笨的写法是每查一层发一次 SQL三层就是三次查询如果用户量是百万级这种查询对数据库压力非常大。更优的做法是查询时直接用 parent_path 字段一次拿回整条链SELECT parent_path FROM member_distribution WHERE member_id #{memberId}拿到类似1,3,8的路径后在内存里切出最近的三级再批量查这三个会员的当前等级和分佣比例。这样数据库只挨一次查询剩下的都在 JVM 内存里完成。比例配置我一般建议放在单独一张配置表里不要写在代码里因为分销政策经常调整比如大促期间临时把一级分佣提高到 8%改配置表比发版本快得多也不容易出事故。另外一个细节是分销等级的快照问题。用户下单那一刻他的上线是银牌代理等订单支付完成时上线可能已经升级成金牌了。按哪个等级算行业里通行的做法是按下单时快照的等级算订单一旦提交分佣比例就锁死后续等级变更不追溯历史订单。实现方式很简单在下单接口里把当时的 member_distribution 快照数据冗余到订单表的一个字段里佣金计算时直接读快照不查实时等级。4.2 佣金计算的幂等设计MQ 重复消费怎么防佣金计算是典型的 MQ 消费者场景。订单服务发消息佣金服务消费消息算佣金写明细。这里最大的坑是消息可能重复。RocketMQ、RabbitMQ 都承诺 at-least-once 投递也就是说网络抖动、消费者宕机重启都可能让同一条消息被投递两次。如果没有幂等保护同一张订单的佣金就会被算两次月底对账时财务会找你拼命。RabbitListener(queues commission.calculate.queue) Transactional(rollbackFor Exception.class) public void onOrderPaid(OrderPaidMessage message) { // 幂等检查同一订单同一会员只允许算一次佣金 Integer count commissionDetailMapper.selectCount( new LambdaQueryWrapperCommissionDetail() .eq(CommissionDetail::getOrderNo, message.getOrderNo()) .eq(CommissionDetail::getFromMemberId, message.getMemberId())); if (count 0) { log.warn(Duplicate commission message, skip. orderNo{}, message.getOrderNo()); return; } // 查分销链 ListLong parentIds distributionService.getParentPath(message.getMemberId(), 3); // 逐级按比例计算佣金 for (int level 0; level parentIds.size(); level) { CommissionDetail detail new CommissionDetail(); detail.setOrderNo(message.getOrderNo()); detail.setMemberId(parentIds.get(level)); // 拿佣金的上级 detail.setFromMemberId(message.getMemberId()); // 下单人 detail.setAmount(message.getOrderAmount() .multiply(ratioConfig.getByLevel(level))); // BigDecimal 运算 commissionDetailMapper.insert(detail); } }这段代码里有三个设计值得细说。第一是幂等检查先按 order_no from_member_id 查是否已有佣金记录有就直接跳过。但光有代码还不够数据库层面也要加唯一索引否则两个并发消费线程同时查到 count 为 0然后同时插入还是会重复。第二是事务边界Transactional 只包住佣金服务自己的数据库操作订单服务那边的事务和这边无关这就是微服务下典型的最终一致性——订单已支付佣金最终会算出来但不是同时发生。第三是金额计算全部用 BigDecimal 的 multiply禁用 double 乘法公式订单金额 × 比例执行几次就明白为什么 double 会丢精度了。4.3 提现状态机和余额冻结资金操作要留流水佣金算出来之后会累加到会员的佣金余额里。余额表设计通常是有两个字段available_amount可用余额和 frozen_amount冻结余额。用户发起提现时不是直接扣减 available_amount而是把提现金额从可用余额移到冻结余额等打款成功后再真正扣掉冻结部分。为什么这么设计因为打款不是即时的从用户提交提现到财务审核、再到第三方支付平台打款中间可能隔几个小时甚至一天。如果提交提现时就扣减余额打款失败需要把金额加回来操作失误就容易资金错乱。先冻结、后扣减账目流动全程可追溯。Transactional(rollbackFor Exception.class) public WithdrawResult withdraw(Long memberId, BigDecimal amount) { // 乐观锁扣减可用余额冻结等额资金 int updated walletMapper.freezeAmount(memberId, amount); if (updated 0) { throw new InsufficientBalanceException(可用余额不足); } WithdrawRecord record new WithdrawRecord(); record.setMemberId(memberId); record.setAmount(amount); record.setStatus(WithdrawStatus.PENDING); withdrawRecordMapper.insert(record); return WithdrawResult.success(record.getId()); }关键在于 freezeAmount 这条 SQLUPDATE member_wallet SET available_amount available_amount - #{amount}, frozen_amount frozen_amount #{amount} WHERE member_id #{memberId} AND available_amount #{amount}这是一个典型的乐观锁写法。where 条件里带上available_amount amount如果余额不足这条 update 影响行数为 0代码里就能捕获到。并发情况下两个提现请求同时进来数据库的行锁保证只有一个能更新成功另一个自然失败。这里不要用先查余额再判断的方式两步操作之间有并发窗口查出来够用update 时可能已经被别人扣掉了。提现单的状态机至少要有这几个状态PENDING待审核→ REVIEWING审核中→ PAYING打款中→ PAID已到账以及 REJECTED审核拒绝和 FAILED打款失败。每个状态变更都要在提现记录表里留一条变更日志哪一天谁审核的、谁打款的、失败原因是什么全部可追溯。资金相关的系统先想清楚怎么对账再想清楚怎么实现功能顺序不能反。4.4 佣金流水的对账思路明细和余额要能互相印证最后再补一个很多源码里不会写但运维时一定会用到的点对账。佣金明细表记录每一笔分佣余额表记录累计金额两者必须能互相印证。具体做法是每个月底跑一个对账任务把当月所有佣金明细的金额汇总和会员余额表的增加额做比对有差异就报警。对账代码不复杂一个 SQL 的事情但这条提醒值得写出来分销系统的 bug 往往不是功能跑不通而是功能跑通了账对不上。设计时就要给每笔资金变动配一个流水号关联到业务单号这是以后查账的唯一线索。5. 避坑清单从能编译到能上线五个绕不开的坑5.1 服务启动失败Nacos 连不上是最常见的事故现象服务启动报错日志里出现NacosException: Client not connected或者connection refused。也可能是服务能启动但 Nacos 控制台的服务列表里看不到它Feign 调用时 503。原因基本就是三个。一是 Nacos 服务端没启动或者 8848 端口被占用二是 bootstrap.yml 里的 server-addr 指向了错误的地址比如本地环境填了生产环境的 Nacos三是 namespace 和 group 不匹配服务注册到了 A 命名空间消费者在 B 命名空间里找它自然找不到。解决先 telnet 测试 Nacos 地址连通性再登录 Nacos 控制台确认命名空间 ID最后看服务启动日志里注册中心相关的告警。还有一个冷门的点如果服务器有多个网卡Nacos 可能注册了错误的 IP需要在配置里显式指定 spring.cloud.nacos.discovery.ip否则其他服务访问不到它。5.2 同一订单佣金被算两次MQ 重复消费没有幂等现象月底对账时发现某笔订单的佣金明细重复了两条金额翻倍。原因RabbitMQ/RocketMQ 的 at-least-once 投递机制消费者处理成功后因网络问题未来得及确认 ack消息被重新投递。如果消费逻辑里没有「先查后插」的幂等判断第二次消费时会再插一条一模一样的佣金记录。解决三层防护。第一层业务代码里按 order_no from_member_id 查重第二层数据库建唯一索引双保险第三层消费逻辑里对重复消息做标记直接 return。这三层缺一层都不能算稳只靠业务代码查重并发下两个线程同时查到空结果就还是会插重。5.3 多级分佣递归查询拖垮数据库现象分销层级深某个高等级代理下线人数特别多佣金计算接口查分销链越来越慢数据库 CPU 飙升。原因代码里逐级查库每算一级佣金发一次 SQL分销深度是 10 级就发 10 次用户量一大数据库扛不住。还有的是用了 MySQL 8.0 的递归 CTE层级太深照样慢。解决两个方向一起做。结构上限制分销层级一般业务也就三级超过三级的政策大多涉嫌违规也不合理技术上给 member_distribution 表加 parent_path 冗余字段一次性查整条链配合 Redis 把高频代理的链路缓存起来。查询代码里坚决消灭递归这是分销系统性能优化的第一原则。5.4 佣金算出来差一分钱double 精度丢失现象佣金明细表里某条记录是 8.999999999加总之后总是差几分几毛财务对账极度痛苦。原因代码里用了 double 类型做金额运算。double 是浮点数二进制无法精确表示 0.1多次乘法运算误差累积后就对不上了。解决金额字段全部用 BigDecimal数据库层面用 decimal(10,2) 或者更稳妥的做法是金额以「分」为单位存整数比如 8.99 元存成 899。这样既避免浮点误差又不用每次查询都做 BigDecimal 的 scale 处理。这个坑在分销系统里几乎每个新人都会踩一遍属于血泪经验。5.5 订单支付成功但佣金没算消息丢失无人发现现象对账时发现一部分订单没有任何佣金明细但订单状态确实是已支付。原因消息发送失败或者消费者处理时抛异常但是没有重试机制。比如订单服务发消息时 MQ 刚好不可用代码里没捕获异常消息就丢了或者消费者代码里 NPE 导致消息被 reject进入了死信队列没被处理。解决三点。第一发消息处做失败补偿发送失败就把消息地址记录到本地事务表由定时任务扫表重发第二消费者里捕获所有异常并记录到补偿任务表定时重试第三建一个对账任务每日扫描已支付但 30 分钟内没有生成佣金明细的订单触发补算。这套机制落地后才敢说分布式环境下的佣金链路基本可靠。6. 拿到源码后先做三件事验证、压测、加一个分佣等级源码跑通后我建议按下面的顺序验证它而不是急着看代码。第一件事把所有服务启动打开 Nacos 控制台确认全部服务注册成功然后从前端点一个下单接口走完整个链路下单 → 支付回调 → 消费消息 → 佣金明细入库 → 余额增加。第二步用一段 SQL 验证佣金金额是否正确查订单金额乘以比例比对佣金明细表里的记录SELECT SUM(d.amount) AS should_amount, o.order_amount * 0.05 AS expect_amount FROM commission_detail d JOIN order o ON o.order_no d.order_no WHERE d.order_no 20250601001 GROUP BY o.order_no对不上就直接看日志里 MQ 消费是否正常比对着代码猜快得多。第三步找一个你准备上线的真实分销规则试着往配置表里加一个分佣等级——不用改代码只加配置和调整处理逻辑里的循环层数。这一步能测试出这套源码的扩展性是不是够用。我自己的教训是第一次跑这种项目时只验证了主流程没验证幂等结果压测工具一跑佣金明细多了几百条当时脑子是蒙的。从那以后凡是涉及资金写入的接口我的第一反应永远是先看有没有幂等控制再谈性能优化。分销系统的代码看起来不复杂复杂度全在边界条件和异常路径里。希望这篇笔记能让你少走几步弯路把这套源码跑起来的同时也把佣金链路的设计思路真正装进脑子里。本文还有配套的精品资源点击获取