简介这份资源是一套基于 ASP.NET 的商城 VIP 积分管理系统完整源码面向计算机专业学生、课程设计或毕业设计开发者以及希望了解会员积分业务实现的后端入门者。它把积分获取、积分累积、会员等级、积分兑换商品、消费记录查询与后台管理等环节做成可运行的项目能直接用于学习典型电商积分模块的开发路径。压缩包共 93 个文件约 2.31MB以 cs、aspx、ascx 等 C# 与 WebForms 页面为主配合 config 配置、master 母版页、sitemap 站点导航和 css 样式另附 mdf 与 ldf 数据库文件及一份 PPT 说明注册、登录、会员信息编辑、商品兑换、积分规则等模块划分清楚。已有 3098 人学习下载。读者可获得可编译运行的三层结构案例参考积分与会员数据表设计、权限后台与统计思路并借助 PPT 和目录结构快速梳理业务流程、排查配置问题。1. 活动上线第二天积分扣成了负数去年帮一个团队处理线上故障商城积分系统上线才两天客服的投诉就堆起来了用户下单抵扣之后积分余额变成负数。翻代码才发现扣减写成了「先查余额、再判断、再更新」的三步走两个并发请求同时读到 1000各自扣掉 800账就彻底坏了。商城积分系统看着只是商城里一个不起眼的小模块本质却是一套账本系统——发放、扣减、冻结、过期、对账任何一环没兜住后面就是永远对不平的流水和永远修不完的数据。这套源码适合两类人一类是手上的商城正准备上积分抵扣需要一个能直接改的底座另一类是已经写了半套想看看别人怎么处理幂等、并发和过期这三个老问题。整体不复杂但有几处细节值得逐行看。2. 架构与技术选型先把账本定死再谈接口2.1 三层结构业务接入层、积分服务层、账本存储层这套系统的分层很朴素但每一层的边界划得很清楚这也是它后面能扛住改造的原因。业务接入层负责把商城各个场景的事件翻译成统一的积分指令比如订单支付成功、每日签到、退款回滚接入方式常见是 HTTP 同步调用加上消息异步补偿两条腿走路。同步链路用于用户当场要看结果的场景比如下单抵扣异步链路用于返积分这种不要求实时的场景走消息队列削峰。积分服务层是真正的核心它只做三件事规则校验、账户变更、流水记账。这里有个血泪经验很多集成积分模块的项目喜欢把业务逻辑往积分服务里塞比如「满 200 元双倍积分」这种判断塞进去之后规则一变就要改积分服务的代码很快就烂成一锅粥。比较合理的做法是把这类判断留在业务侧积分服务只接受「给谁、加多少、什么场景、业务单号是什么」四个参数。账本存储层用 MySQL 做唯一事实来源账户表和流水表分开。Redis 在这套结构里只承担两个职责热点账户的余额缓存以及并发扣减前的快速失败。注意缓存永远不能当作账本余额的最终判定必须在数据库里完成。消息队列用于把「积分变了」这个事实广播出去让成长值、会员等级这些下游系统自己去订阅而不是让积分服务反过来调它们。2.2 数据模型账户表、流水表、规则表这三张表定生死整个系统的数据结构其实就三张核心表。账户表存当前状态流水表存变化历史规则表存配置。判断一个积分系统设计得好不好看流水表就知道了——如果流水表的记录会被 UPDATE 改金额那这套账基本没救。表名职责关键字段写入特点points_account用户当前积分余额user_id、available_points、frozen_points、version高频更新按 user_id 单行points_ledger每一次积分变动txn_no、scene、biz_no、change_amount、balance_after只插入永不改金额points_rule各场景发放规则rule_code、scene、ratio、daily_limit、expire_days低频变更适合加缓存建表时最值钱的两个东西一个是流水表上 (scene, biz_no) 的唯一索引另一个是 balance_after 这个字段。前者是幂等的最后一道防线后者是对账时唯一的救命稻草——没有它你只能看着一堆加减号猜是哪一笔出了问题。CREATE TABLE points_account ( user_id BIGINT UNSIGNED NOT NULL COMMENT 用户ID, total_points BIGINT NOT NULL DEFAULT 0 COMMENT 历史累计获得, available_points BIGINT NOT NULL DEFAULT 0 COMMENT 当前可用余额, frozen_points BIGINT NOT NULL DEFAULT 0 COMMENT 冻结中下单未支付, version INT NOT NULL DEFAULT 0 COMMENT 版本号便于排查并发, updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP, PRIMARY KEY (user_id) ) ENGINEInnoDB DEFAULT CHARSETutf8mb4 COMMENT积分账户;CREATE TABLE points_ledger ( id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT, txn_no VARCHAR(48) NOT NULL COMMENT 流水号全局唯一, user_id BIGINT UNSIGNED NOT NULL, scene VARCHAR(32) NOT NULL COMMENT order_pay/sign_in/order_deduct/expire/refund, biz_no VARCHAR(64) NOT NULL COMMENT 业务单号幂等键, change_amount BIGINT NOT NULL COMMENT 正数加分负数减分, balance_after BIGINT NOT NULL COMMENT 本条记账后的可用余额, expire_at DATETIME DEFAULT NULL COMMENT 过期时间NULL 表示永久有效, status TINYINT NOT NULL DEFAULT 1 COMMENT 1有效 2已过期 3已撤销, created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP, PRIMARY KEY (id), UNIQUE KEY uk_scene_biz (scene, biz_no), KEY idx_user_expire (user_id, status, expire_at) ) ENGINEInnoDB DEFAULT CHARSETutf8mb4 COMMENT积分流水只增不改;这里的字段设计有几处是踩过坑之后加的。change_amount 允许负数意味着过期、退款、撤销都可以用同一种记录方式表达对账时一句 SUM 就够不用去区分「哪些是加、哪些是减」balance_after 是冗余字段写入时多一次查询但事后排查能省几个小时idx_user_expire 这个联合索引是给过期任务用的缺了它凌晨的批处理会直接扫全表。2.3 目录结构与模块职责工程按职责切成了几个 Maven 模块好处是积分核心逻辑跟 Web 层、定时任务层解耦改造的时候能单独替换。points-server/ ├── points-api/ # 对外契约DTO、错误码、RPC/HTTP 接口定义 ├── points-core/ # 领域层系统的重心 │ ├── domain/ # Account、Ledger、Rule 三个聚合根 │ ├── service/ # GrantService、DeductService、ExpireService │ └── repository/ # Mapper 接口与缓存封装 ├── points-job/ # 过期、对账、补偿三个定时任务 ├── points-web/ # 启动模块Controller 与全局异常处理 └── sql/ # 建表脚本 初始化规则数据有个细节值得注意points-job 是独立模块但它和 points-web 共用同一份 points-core。这意味着同一套业务逻辑既能被 HTTP 请求触发也能被定时任务触发不需要在两处各写一遍账户更新代码。很多项目在这里翻车就是任务里手写了一版 SQL后来改了业务规则忘了同步导致后台扣的和前台扣的规则不一样。3. 环境搭建与跑通从空库到第一笔流水3.1 依赖与配置文件本地起这套东西的门槛不高MySQL 8 加 Redis 就够了JDK 用 17构建走 Maven。配置文件里真正影响行为的就那么几项剩下的保持默认即可。server: port: 8080 spring: datasource: url: jdbc:mysql://127.0.0.1:3306/points?useUnicodetruecharacterEncodingutf8serverTimezoneAsia/Shanghai username: points password: points123 hikari: maximum-pool-size: 20 # 单实例 20 够用别盲目调大 redis: host: 127.0.0.1 port: 6379 timeout: 2000ms points: expire: batch-size: 500 # 过期任务每批处理的流水条数 cron: 0 30 2 * * ? # 每天凌晨 2:30 执行 rule: cache-ttl-seconds: 300 # 规则缓存 5 分钟改配置后最多延迟这么久生效batch-size 这个参数是整套配置里最需要按数据量调整的。500 这个值适合日活几万的商城如果流水表已经上千万行一批 500 会让任务跑上几个小时这时候该调到 2000 并配合多线程分片但不要一次调到几万单事务太大会把 undo log 撑爆。3.2 建表与初始化规则数据建表脚本在 sql 目录下顺序不能乱先账户再流水最后规则。初始化数据里至少要放一条签到规则和一条消费返积分规则否则启动后调用发放接口会直接报「规则未开启」。-- 消费返积分每消费 1 元给 1 分有效期 365 天 INSERT INTO points_rule (rule_code, scene, ratio, daily_limit, expire_days, status) VALUES (RULE_ORDER_PAY, order_pay, 1.0000, 0, 365, 1); -- 每日签到固定 10 分当天上限 10 分有效期 30 天 INSERT INTO points_rule (rule_code, scene, ratio, daily_limit, expire_days, status) VALUES (RULE_SIGN_IN, sign_in, 10.0000, 10, 30, 1);ratio 用 DECIMAL 而不是 INT是因为很多商城的实际规则是「每消费 1 元给 0.5 分」用整数会导致规则无法表达。daily_limit 为 0 表示不限这个约定要在代码里显式处理不能靠数据库默认值糊弄过去。3.3 启动服务并用 curl 验证一次完整链路服务起来之后先别急着接业务系统用三条命令把发放、扣减、查询走一遍确认账本行为符合预期。# 1) 发放模拟订单支付成功返 100 分 curl -X POST http://127.0.0.1:8080/api/points/grant \ -H Content-Type: application/json \ -d {userId:1001,scene:order_pay,bizNo:ORD20240501001,orderAmount:100} # 2) 扣减模拟下单抵扣 30 分 curl -X POST http://127.0.0.1:8080/api/points/deduct \ -H Content-Type: application/json \ -d {userId:1001,scene:order_deduct,bizNo:ORD20240501002,amount:30} # 3) 查询余额 curl http://127.0.0.1:8080/api/points/account?userId1001第三条命令应该返回 {availablePoints:70,totalPoints:100,frozenPoints:0}。如果返回的 availablePoints 是 100说明扣减那一步没生效大概率是 scene 配错了或者规则里没开 order_deduct。再执行一次第一条命令余额应该还是 70 而不是 170这一步验证的就是幂等键生效——重复的业务单号不应该产生第二条流水。这个动作我每次接手新项目都要做一遍比看十遍代码管用。4. 核心链路拆解发放、扣减、过期三处最容易写错的地方4.1 积分发放幂等键和事务边界决定这套账能不能信发放看着最简单实际上问题最多因为它是最先被重复调用的接口。订单支付的回调重试、消息队列的重投、用户手抖多点两下任何一个都能让积分多发一遍。常见做法是三道防线接口层用 Redis 做快速去重数据库唯一索引做最终兜底业务层捕获重复键异常直接当作成功返回。Transactional(rollbackFor Exception.class) public GrantResult grant(GrantCommand cmd) { // 1) 规则校验场景必须开启单日上限要做累加判断 PointsRule rule ruleCache.getByScene(cmd.getScene()); if (rule null || rule.getStatus() ! 1) { throw new BizException(ErrorCode.RULE_NOT_OPEN); } long amount calcGrantAmount(cmd, rule); // 按 ratio 和订单金额换算 if (amount 0) { return GrantResult.empty(); } // 2) 写流水唯一索引 uk_scene_biz 兜底重复插入抛 DuplicateKeyException PointsLedger ledger new PointsLedger(); ledger.setTxnNo(IdGen.next()); ledger.setUserId(cmd.getUserId()); ledger.setScene(cmd.getScene()); ledger.setBizNo(cmd.getBizNo()); // 幂等键的第二段 ledger.setChangeAmount(amount); ledger.setExpireAt(calcExpireAt(rule.getExpireDays())); try { ledgerMapper.insert(ledger); } catch (DuplicateKeyException e) { log.warn(重复发放请求直接忽略 scene{} bizNo{}, cmd.getScene(), cmd.getBizNo()); return GrantResult.duplicated(); } // 3) 更新账户同事务内完成任何一步失败一起回滚 accountMapper.addAvailable(cmd.getUserId(), amount); long balanceAfter accountMapper.selectAvailable(cmd.getUserId()); ledgerMapper.updateBalanceAfter(ledger.getId(), balanceAfter); // 4) 事务提交后再发事件避免下游查库查不到 TransactionSynchronizationManager.registerSynchronization( new TransactionSynchronization() { Override public void afterCommit() { eventPublisher.publish(new PointsChangedEvent(cmd.getUserId(), amount, cmd.getScene())); } }); return GrantResult.success(balanceAfter); }这段代码有两个关键点值得掰开说。第一是 balance_after 的写入方式先更新账户再回查当前余额然后把余额回填到刚插入的那条流水上。这样做会多一次 UPDATE但换来的是每条流水都有一个准确的历史快照对账时能直接定位到是哪一笔开始对不上的。第二是事件发布必须挂在 afterCommit 上如果把 publish 写在事务中间消息可能比数据先到消费方消费方回查数据库查不到触发重试最后又是一笔重复积分。addAvailable 对应的 SQL 也要注意别写成先 SELECT 再 SET 绝对值update idaddAvailable UPDATE points_account SET available_points available_points #{amount}, total_points total_points #{amount}, version version 1 WHERE user_id #{userId} /update用available_points #{amount}这种自增写法数据库行锁会保证并发的正确性不需要应用层加任何锁。4.2 积分扣减一条带条件的 UPDATE 胜过十行 if扣减是全部链路里唯一会「钱不够」的操作也是最容易写出并发 bug 的地方。前面提到的负数余额根子就是代码里那个多余的 if——判断和更新之间存在时间窗口窗口里挤进来的请求都能通过判断。正确写法是把判断塞进 SQL 的 WHERE 里用影响行数当结果。public DeductResult deduct(DeductCommand cmd) { // 先查一次流水命中说明这个业务单号已经处理过了 PointsLedger exist ledgerMapper.selectBySceneAndBiz(cmd.getScene(), cmd.getBizNo()); if (exist ! null) { return DeductResult.duplicated(exist.getBalanceAfter()); } // 核心扣减条件写在 WHERE 里靠影响行数判断成功与否 int affected accountMapper.deductAvailable(cmd.getUserId(), cmd.getAmount()); if (affected 0) { // 可能是余额不足也可能是账户不存在这里统一按余额不足处理 throw new BizException(ErrorCode.POINTS_NOT_ENOUGH); } long balanceAfter accountMapper.selectAvailable(cmd.getUserId()); PointsLedger ledger buildLedger(cmd, -cmd.getAmount(), balanceAfter); ledgerMapper.insert(ledger); // 唯一索引再次兜底 return DeductResult.success(balanceAfter); }update iddeductAvailable UPDATE points_account SET available_points available_points - #{amount}, version version 1 WHERE user_id #{userId} AND available_points gt; #{amount} /updateAND available_points #{amount}这一行是整个扣减逻辑的全部安全性来源。数据库在执行这条 UPDATE 时会对该行加排他锁读到的一定是最新值两个并发请求必然串行化后到的那个会发现余额已经不够affected 返回 0。这比任何应用层的分布式锁都可靠而且性能高得多。注意 affected 0 这个分支不要粗暴地当成「余额不足」直接抛错就完事。如果账户根本不存在新用户第一次进来同样会返回 0这时候合理的处理是先初始化账户再重试一次或者干脆在注册时就预建账户。这个细节不处理新用户下单抵扣会直接报错。4.3 积分过期游标分页加独立事务别让任务跑成灾难过期任务的本质是「找出所有到期的正向流水逐条生成对应的负向流水」。听起来简单但数据量一上来就出问题。常见翻车写法是用LIMIT offset, size分页翻到第 10000 页时数据库要先扫描 500 万行再丢弃CPU 直接打满。public void expireJob(LocalDate today) { long cursor 0L; int batchSize expireProperties.getBatchSize(); while (true) { // 游标分页只查 id 大于上一批最大值的记录走主键索引 ListPointsLedger batch ledgerMapper.selectExpiredAfterId(cursor, today, batchSize); if (batch.isEmpty()) { break; } for (PointsLedger item : batch) { try { // 每条一个独立事务单条失败不影响整批 transactionTemplate.executeWithoutResult(status - expireOne(item)); } catch (Exception e) { log.error(积分过期失败 txnNo{} userId{}, item.getTxnNo(), item.getUserId(), e); // 失败记录留在原状态交给 T1 的补偿任务再扫一次 } } cursor batch.get(batch.size() - 1).getId(); } }select idselectExpiredAfterId resultTypePointsLedger SELECT id, txn_no, user_id, change_amount FROM points_ledger WHERE status 1 AND expire_at IS NOT NULL AND expire_at lt; #{today} AND id gt; #{cursor} ORDER BY id LIMIT #{batchSize} /select三个要点。第一游标用主键 id 而不是 offset每次从上一批的最大 id 往后扫全程走主键索引翻到第一亿条和第一条的速度一样。第二SELECT 只取需要的四列别写SELECT *过期任务不需要知道规则和场景多取的每一列都是白读的 IO。第三每条流水一个独立事务因为过期是幂等操作——原流水 status 从 1 改成 2 时用WHERE status 1保证只成功一次重复执行不会扣两次。expireOne 内部同样要走条件更新private void expireOne(PointsLedger item) { // 先把原流水标记为已过期靠 status1 的条件保证只处理一次 int marked ledgerMapper.markExpired(item.getId()); if (marked 0) { return; // 已被其他线程处理直接跳过 } // 再扣减账户注意这里也要防止扣成负数 int affected accountMapper.deductAvailable(item.getUserId(), item.getChangeAmount()); if (affected 0) { // 用户已经把分花掉了标记为待补扣挂起人工或后续处理 pendingMapper.insert(item.getUserId(), item.getChangeAmount()); log.warn(过期扣减余额不足转待处理 userId{} amount{}, item.getUserId(), item.getChangeAmount()); return; } ledgerMapper.insert(buildExpireLedger(item)); }「过期扣不动」这个分支是很多人漏掉的。用户拿到 100 分花了 90剩 10这时 100 分的原始流水到期了你按 100 扣就会负 90。正确做法是先扣能扣的剩下的挂到待处理表等用户下次获得积分时优先抵扣。这套系统里 pending 表就是这么用的。4.4 对账一条 SQL 找出所有不平的账户每天跑完过期任务之后,紧接着应该跑一次对账。别指望业务侧永远不出错也别指望自己写的代码没有 bug对账是最后一道防线。-- 账户余额 vs 流水总和两者必须完全相等 SELECT a.user_id, a.available_points AS account_balance, COALESCE(SUM(l.change_amount), 0) AS ledger_balance, a.available_points - COALESCE(SUM(l.change_amount), 0) AS diff FROM points_account a LEFT JOIN points_ledger l ON l.user_id a.user_id GROUP BY a.user_id, a.available_points HAVING diff 0 LIMIT 200;这条 SQL 能成立的前提是流水表只增不改——过期通过新增一条负数流水实现撤销退款也通过新增负数流水实现绝不回头去改原记录的金额。如果团队里有人图省事直接 UPDATE 老流水这条对账 SQL 立刻失效而且你永远查不出是哪天开始对不上的。对账结果不要只打日志diff 不为空的账户要推到告警通道同时把该用户近 30 天的流水全导出来存一份快照方便事后复盘。查出来的典型原因是分布式事务没处理好、消息重复消费、或者有人手工改过数据库。5. 避坑与排查五个让积分对不上的真实原因5.1 数据一致性相关的三个坑坑一重复回调发了两次积分。现象是用户投诉「明明只下了一单积分多了一倍」。排查下来接口层只做了 Redis 的 setnx 去重而 Redis 那次刚好赶上主从切换或者 key 到期去重失效。原因是把幂等完全押在缓存上缓存本身不是可靠的。解决办法是数据库唯一索引 (scene, biz_no) 必须建代码里 catch DuplicateKeyException 当作成功返回Redis 只作为减少数据库压力的前置过滤不承担正确性责任。坑二并发扣减把余额扣成负数。现象是账户表出现 available_points 为负的记录。原因几乎百分之百是「先 SELECT 判断余额再 UPDATE 扣减」这个经典写法判断和更新之间没有原子性。解决办法是把判断搬进 SQL 的 WHERE 条件用AND available_points #{amount}加上影响行数判断。改完以后可以顺手写个 20 线程各扣 10 分的压测用例跑完看余额是否刚好等于初始值减 200对不上就是还有别的地方在裸奔。坑三过期任务把用户扣成负数。现象是过期任务跑完一批用户的余额变成负的。原因是任务里直接按原始流水的金额扣没考虑用户已经花掉一部分。解决办法是过期扣减也走条件更新扣不动就把差额写进待处理表等用户下次获得积分时优先抵扣。另外要在过期任务执行前先冻结账户available_points 转到 frozen_points跑完再解冻避免用户刚好在任务执行期间消费。5.2 任务与性能相关的两个坑坑四凌晨的过期任务跑到第二天中午还没结束。现象是监控显示任务耗时从 20 分钟涨到 8 小时数据库 CPU 长期 90% 以上。原因通常有两个叠加一是用了LIMIT offset, size深分页二是把整批数据塞进一个大事务里。解决办法是换游标分页上一节已经写了配合 500 一批的小事务同时检查索引WHERE status 1 AND expire_at ?如果没有 (status, expire_at) 的联合索引每次都要全表扫。补索引之后同样的数据量耗时能降一个数量级。坑五账不平但查不出是哪一笔。现象是对账 SQL 报出 diff 不为 0但翻流水看不出问题。原因往往是流水表缺少 balance_after 字段或者有人的代码在事务提交前就发了消息导致下游系统重复处理。解决办法是补上 balance_after 并改成事务提交后发消息如果历史数据已经乱了就按时间顺序重放该用户所有流水重新计算每一笔之后的余额跟记录的 balance_after 逐条比对第一个出现偏差的位置就是出问题的地方。这个排查手段我用过好几次比瞎猜快得多。6. 二次开发把积分接到自己业务上的三个改造点6.1 新增一个业务场景其实只改三处接入新场景的路径很清晰不需要动核心逻辑。第一步在 points_rule 表里插一条规则记录把 scene 编码、换算比例、单日上限、有效天数填好第二步在场景枚举类里加上对应的常量顺便定义这个场景是加分还是减分第三步在业务系统的对应位置加一次调用比如订单支付成功后调 grant退款成功后调 revoke。三处改完就能跑核心的发放和扣减逻辑完全复用。真正需要小心的是第三步的调用位置。发放应该放在业务主流程成功之后绝不能在事务中间调退款撤销要传原始的业务单号让幂等键能命中同一笔流水。我一般会在业务侧封装一个 PointsClient把异常吞掉只打日志积分发不出去不能影响主交易——但这点要在业务上跟运营对齐因为很多商城是「不发积分就不算成交」的强一致要求。6.2 验证方法三条用例覆盖八成问题改完代码必须跑这三条用例缺一条都不算改完。用例操作期望结果重复回调同一个 bizNo 连续调两次 grant只有一条流水余额只加一次并发扣减20 线程同时扣同一个用户的积分余额不为负成功的请求数等于余额/单次扣减过期边界造一条 expire_at 为昨天的流水跑过期任务生成一条负数流水原流水 status 变成 2余额正确减少第二条用例最好用 JMeter 或者一段简单的多线程代码跑别用单线程模拟并发问题是模拟不出来的。跑完直接查账户表和流水表的 SUM两者必须一致。6.3 一个技巧把幂等键做成规范而不是随手拼接这套系统里我改得最满意的一处是把 bizNo 的格式强制规范成scene:业务单号:动作。比如订单支付返积分就是order_pay:ORD20240501001:grant同一单退款就是order_pay:ORD20240501001:revoke。这样同一笔业务的不同动作天然互不冲突又都能追溯回原始单号。// 幂等键统一生成禁止业务侧随手拼字符串 public static String bizKey(String scene, String orderNo, String action) { return String.join(:, scene, orderNo, action); }一开始团队里有人觉得这层封装多余直到上线后出现「退款和支付用了同一个 bizNo 导致退款失败」的问题。加上统一生成方法之后这类问题再没出现过。从那以后我每接一个积分需求都会先把幂等键和 balance_after 这两件事钉死在设计评审里谁提「先查余额再扣」的写法都得在会上说清楚为什么。这套源码的 sql 目录和 job 模块都留着照着第 3 章跑一遍就能看到自己的第一笔流水剩下的改造无非是照着第 6 章那三处往下接。希望帮到你。本文还有配套的精品资源点击获取
简介这份资源是一套基于 ASP.NET 的商城 VIP 积分管理系统完整源码面向计算机专业学生、课程设计或毕业设计开发者以及希望了解会员积分业务实现的后端入门者。它把积分获取、积分累积、会员等级、积分兑换商品、消费记录查询与后台管理等环节做成可运行的项目能直接用于学习典型电商积分模块的开发路径。压缩包共 93 个文件约 2.31MB以 cs、aspx、ascx 等 C# 与 WebForms 页面为主配合 config 配置、master 母版页、sitemap 站点导航和 css 样式另附 mdf 与 ldf 数据库文件及一份 PPT 说明注册、登录、会员信息编辑、商品兑换、积分规则等模块划分清楚。已有 3098 人学习下载。读者可获得可编译运行的三层结构案例参考积分与会员数据表设计、权限后台与统计思路并借助 PPT 和目录结构快速梳理业务流程、排查配置问题。1. 活动上线第二天积分扣成了负数去年帮一个团队处理线上故障商城积分系统上线才两天客服的投诉就堆起来了用户下单抵扣之后积分余额变成负数。翻代码才发现扣减写成了「先查余额、再判断、再更新」的三步走两个并发请求同时读到 1000各自扣掉 800账就彻底坏了。商城积分系统看着只是商城里一个不起眼的小模块本质却是一套账本系统——发放、扣减、冻结、过期、对账任何一环没兜住后面就是永远对不平的流水和永远修不完的数据。这套源码适合两类人一类是手上的商城正准备上积分抵扣需要一个能直接改的底座另一类是已经写了半套想看看别人怎么处理幂等、并发和过期这三个老问题。整体不复杂但有几处细节值得逐行看。2. 架构与技术选型先把账本定死再谈接口2.1 三层结构业务接入层、积分服务层、账本存储层这套系统的分层很朴素但每一层的边界划得很清楚这也是它后面能扛住改造的原因。业务接入层负责把商城各个场景的事件翻译成统一的积分指令比如订单支付成功、每日签到、退款回滚接入方式常见是 HTTP 同步调用加上消息异步补偿两条腿走路。同步链路用于用户当场要看结果的场景比如下单抵扣异步链路用于返积分这种不要求实时的场景走消息队列削峰。积分服务层是真正的核心它只做三件事规则校验、账户变更、流水记账。这里有个血泪经验很多集成积分模块的项目喜欢把业务逻辑往积分服务里塞比如「满 200 元双倍积分」这种判断塞进去之后规则一变就要改积分服务的代码很快就烂成一锅粥。比较合理的做法是把这类判断留在业务侧积分服务只接受「给谁、加多少、什么场景、业务单号是什么」四个参数。账本存储层用 MySQL 做唯一事实来源账户表和流水表分开。Redis 在这套结构里只承担两个职责热点账户的余额缓存以及并发扣减前的快速失败。注意缓存永远不能当作账本余额的最终判定必须在数据库里完成。消息队列用于把「积分变了」这个事实广播出去让成长值、会员等级这些下游系统自己去订阅而不是让积分服务反过来调它们。2.2 数据模型账户表、流水表、规则表这三张表定生死整个系统的数据结构其实就三张核心表。账户表存当前状态流水表存变化历史规则表存配置。判断一个积分系统设计得好不好看流水表就知道了——如果流水表的记录会被 UPDATE 改金额那这套账基本没救。表名职责关键字段写入特点points_account用户当前积分余额user_id、available_points、frozen_points、version高频更新按 user_id 单行points_ledger每一次积分变动txn_no、scene、biz_no、change_amount、balance_after只插入永不改金额points_rule各场景发放规则rule_code、scene、ratio、daily_limit、expire_days低频变更适合加缓存建表时最值钱的两个东西一个是流水表上 (scene, biz_no) 的唯一索引另一个是 balance_after 这个字段。前者是幂等的最后一道防线后者是对账时唯一的救命稻草——没有它你只能看着一堆加减号猜是哪一笔出了问题。CREATE TABLE points_account ( user_id BIGINT UNSIGNED NOT NULL COMMENT 用户ID, total_points BIGINT NOT NULL DEFAULT 0 COMMENT 历史累计获得, available_points BIGINT NOT NULL DEFAULT 0 COMMENT 当前可用余额, frozen_points BIGINT NOT NULL DEFAULT 0 COMMENT 冻结中下单未支付, version INT NOT NULL DEFAULT 0 COMMENT 版本号便于排查并发, updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP, PRIMARY KEY (user_id) ) ENGINEInnoDB DEFAULT CHARSETutf8mb4 COMMENT积分账户;CREATE TABLE points_ledger ( id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT, txn_no VARCHAR(48) NOT NULL COMMENT 流水号全局唯一, user_id BIGINT UNSIGNED NOT NULL, scene VARCHAR(32) NOT NULL COMMENT order_pay/sign_in/order_deduct/expire/refund, biz_no VARCHAR(64) NOT NULL COMMENT 业务单号幂等键, change_amount BIGINT NOT NULL COMMENT 正数加分负数减分, balance_after BIGINT NOT NULL COMMENT 本条记账后的可用余额, expire_at DATETIME DEFAULT NULL COMMENT 过期时间NULL 表示永久有效, status TINYINT NOT NULL DEFAULT 1 COMMENT 1有效 2已过期 3已撤销, created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP, PRIMARY KEY (id), UNIQUE KEY uk_scene_biz (scene, biz_no), KEY idx_user_expire (user_id, status, expire_at) ) ENGINEInnoDB DEFAULT CHARSETutf8mb4 COMMENT积分流水只增不改;这里的字段设计有几处是踩过坑之后加的。change_amount 允许负数意味着过期、退款、撤销都可以用同一种记录方式表达对账时一句 SUM 就够不用去区分「哪些是加、哪些是减」balance_after 是冗余字段写入时多一次查询但事后排查能省几个小时idx_user_expire 这个联合索引是给过期任务用的缺了它凌晨的批处理会直接扫全表。2.3 目录结构与模块职责工程按职责切成了几个 Maven 模块好处是积分核心逻辑跟 Web 层、定时任务层解耦改造的时候能单独替换。points-server/ ├── points-api/ # 对外契约DTO、错误码、RPC/HTTP 接口定义 ├── points-core/ # 领域层系统的重心 │ ├── domain/ # Account、Ledger、Rule 三个聚合根 │ ├── service/ # GrantService、DeductService、ExpireService │ └── repository/ # Mapper 接口与缓存封装 ├── points-job/ # 过期、对账、补偿三个定时任务 ├── points-web/ # 启动模块Controller 与全局异常处理 └── sql/ # 建表脚本 初始化规则数据有个细节值得注意points-job 是独立模块但它和 points-web 共用同一份 points-core。这意味着同一套业务逻辑既能被 HTTP 请求触发也能被定时任务触发不需要在两处各写一遍账户更新代码。很多项目在这里翻车就是任务里手写了一版 SQL后来改了业务规则忘了同步导致后台扣的和前台扣的规则不一样。3. 环境搭建与跑通从空库到第一笔流水3.1 依赖与配置文件本地起这套东西的门槛不高MySQL 8 加 Redis 就够了JDK 用 17构建走 Maven。配置文件里真正影响行为的就那么几项剩下的保持默认即可。server: port: 8080 spring: datasource: url: jdbc:mysql://127.0.0.1:3306/points?useUnicodetruecharacterEncodingutf8serverTimezoneAsia/Shanghai username: points password: points123 hikari: maximum-pool-size: 20 # 单实例 20 够用别盲目调大 redis: host: 127.0.0.1 port: 6379 timeout: 2000ms points: expire: batch-size: 500 # 过期任务每批处理的流水条数 cron: 0 30 2 * * ? # 每天凌晨 2:30 执行 rule: cache-ttl-seconds: 300 # 规则缓存 5 分钟改配置后最多延迟这么久生效batch-size 这个参数是整套配置里最需要按数据量调整的。500 这个值适合日活几万的商城如果流水表已经上千万行一批 500 会让任务跑上几个小时这时候该调到 2000 并配合多线程分片但不要一次调到几万单事务太大会把 undo log 撑爆。3.2 建表与初始化规则数据建表脚本在 sql 目录下顺序不能乱先账户再流水最后规则。初始化数据里至少要放一条签到规则和一条消费返积分规则否则启动后调用发放接口会直接报「规则未开启」。-- 消费返积分每消费 1 元给 1 分有效期 365 天 INSERT INTO points_rule (rule_code, scene, ratio, daily_limit, expire_days, status) VALUES (RULE_ORDER_PAY, order_pay, 1.0000, 0, 365, 1); -- 每日签到固定 10 分当天上限 10 分有效期 30 天 INSERT INTO points_rule (rule_code, scene, ratio, daily_limit, expire_days, status) VALUES (RULE_SIGN_IN, sign_in, 10.0000, 10, 30, 1);ratio 用 DECIMAL 而不是 INT是因为很多商城的实际规则是「每消费 1 元给 0.5 分」用整数会导致规则无法表达。daily_limit 为 0 表示不限这个约定要在代码里显式处理不能靠数据库默认值糊弄过去。3.3 启动服务并用 curl 验证一次完整链路服务起来之后先别急着接业务系统用三条命令把发放、扣减、查询走一遍确认账本行为符合预期。# 1) 发放模拟订单支付成功返 100 分 curl -X POST http://127.0.0.1:8080/api/points/grant \ -H Content-Type: application/json \ -d {userId:1001,scene:order_pay,bizNo:ORD20240501001,orderAmount:100} # 2) 扣减模拟下单抵扣 30 分 curl -X POST http://127.0.0.1:8080/api/points/deduct \ -H Content-Type: application/json \ -d {userId:1001,scene:order_deduct,bizNo:ORD20240501002,amount:30} # 3) 查询余额 curl http://127.0.0.1:8080/api/points/account?userId1001第三条命令应该返回 {availablePoints:70,totalPoints:100,frozenPoints:0}。如果返回的 availablePoints 是 100说明扣减那一步没生效大概率是 scene 配错了或者规则里没开 order_deduct。再执行一次第一条命令余额应该还是 70 而不是 170这一步验证的就是幂等键生效——重复的业务单号不应该产生第二条流水。这个动作我每次接手新项目都要做一遍比看十遍代码管用。4. 核心链路拆解发放、扣减、过期三处最容易写错的地方4.1 积分发放幂等键和事务边界决定这套账能不能信发放看着最简单实际上问题最多因为它是最先被重复调用的接口。订单支付的回调重试、消息队列的重投、用户手抖多点两下任何一个都能让积分多发一遍。常见做法是三道防线接口层用 Redis 做快速去重数据库唯一索引做最终兜底业务层捕获重复键异常直接当作成功返回。Transactional(rollbackFor Exception.class) public GrantResult grant(GrantCommand cmd) { // 1) 规则校验场景必须开启单日上限要做累加判断 PointsRule rule ruleCache.getByScene(cmd.getScene()); if (rule null || rule.getStatus() ! 1) { throw new BizException(ErrorCode.RULE_NOT_OPEN); } long amount calcGrantAmount(cmd, rule); // 按 ratio 和订单金额换算 if (amount 0) { return GrantResult.empty(); } // 2) 写流水唯一索引 uk_scene_biz 兜底重复插入抛 DuplicateKeyException PointsLedger ledger new PointsLedger(); ledger.setTxnNo(IdGen.next()); ledger.setUserId(cmd.getUserId()); ledger.setScene(cmd.getScene()); ledger.setBizNo(cmd.getBizNo()); // 幂等键的第二段 ledger.setChangeAmount(amount); ledger.setExpireAt(calcExpireAt(rule.getExpireDays())); try { ledgerMapper.insert(ledger); } catch (DuplicateKeyException e) { log.warn(重复发放请求直接忽略 scene{} bizNo{}, cmd.getScene(), cmd.getBizNo()); return GrantResult.duplicated(); } // 3) 更新账户同事务内完成任何一步失败一起回滚 accountMapper.addAvailable(cmd.getUserId(), amount); long balanceAfter accountMapper.selectAvailable(cmd.getUserId()); ledgerMapper.updateBalanceAfter(ledger.getId(), balanceAfter); // 4) 事务提交后再发事件避免下游查库查不到 TransactionSynchronizationManager.registerSynchronization( new TransactionSynchronization() { Override public void afterCommit() { eventPublisher.publish(new PointsChangedEvent(cmd.getUserId(), amount, cmd.getScene())); } }); return GrantResult.success(balanceAfter); }这段代码有两个关键点值得掰开说。第一是 balance_after 的写入方式先更新账户再回查当前余额然后把余额回填到刚插入的那条流水上。这样做会多一次 UPDATE但换来的是每条流水都有一个准确的历史快照对账时能直接定位到是哪一笔开始对不上的。第二是事件发布必须挂在 afterCommit 上如果把 publish 写在事务中间消息可能比数据先到消费方消费方回查数据库查不到触发重试最后又是一笔重复积分。addAvailable 对应的 SQL 也要注意别写成先 SELECT 再 SET 绝对值update idaddAvailable UPDATE points_account SET available_points available_points #{amount}, total_points total_points #{amount}, version version 1 WHERE user_id #{userId} /update用available_points #{amount}这种自增写法数据库行锁会保证并发的正确性不需要应用层加任何锁。4.2 积分扣减一条带条件的 UPDATE 胜过十行 if扣减是全部链路里唯一会「钱不够」的操作也是最容易写出并发 bug 的地方。前面提到的负数余额根子就是代码里那个多余的 if——判断和更新之间存在时间窗口窗口里挤进来的请求都能通过判断。正确写法是把判断塞进 SQL 的 WHERE 里用影响行数当结果。public DeductResult deduct(DeductCommand cmd) { // 先查一次流水命中说明这个业务单号已经处理过了 PointsLedger exist ledgerMapper.selectBySceneAndBiz(cmd.getScene(), cmd.getBizNo()); if (exist ! null) { return DeductResult.duplicated(exist.getBalanceAfter()); } // 核心扣减条件写在 WHERE 里靠影响行数判断成功与否 int affected accountMapper.deductAvailable(cmd.getUserId(), cmd.getAmount()); if (affected 0) { // 可能是余额不足也可能是账户不存在这里统一按余额不足处理 throw new BizException(ErrorCode.POINTS_NOT_ENOUGH); } long balanceAfter accountMapper.selectAvailable(cmd.getUserId()); PointsLedger ledger buildLedger(cmd, -cmd.getAmount(), balanceAfter); ledgerMapper.insert(ledger); // 唯一索引再次兜底 return DeductResult.success(balanceAfter); }update iddeductAvailable UPDATE points_account SET available_points available_points - #{amount}, version version 1 WHERE user_id #{userId} AND available_points gt; #{amount} /updateAND available_points #{amount}这一行是整个扣减逻辑的全部安全性来源。数据库在执行这条 UPDATE 时会对该行加排他锁读到的一定是最新值两个并发请求必然串行化后到的那个会发现余额已经不够affected 返回 0。这比任何应用层的分布式锁都可靠而且性能高得多。注意 affected 0 这个分支不要粗暴地当成「余额不足」直接抛错就完事。如果账户根本不存在新用户第一次进来同样会返回 0这时候合理的处理是先初始化账户再重试一次或者干脆在注册时就预建账户。这个细节不处理新用户下单抵扣会直接报错。4.3 积分过期游标分页加独立事务别让任务跑成灾难过期任务的本质是「找出所有到期的正向流水逐条生成对应的负向流水」。听起来简单但数据量一上来就出问题。常见翻车写法是用LIMIT offset, size分页翻到第 10000 页时数据库要先扫描 500 万行再丢弃CPU 直接打满。public void expireJob(LocalDate today) { long cursor 0L; int batchSize expireProperties.getBatchSize(); while (true) { // 游标分页只查 id 大于上一批最大值的记录走主键索引 ListPointsLedger batch ledgerMapper.selectExpiredAfterId(cursor, today, batchSize); if (batch.isEmpty()) { break; } for (PointsLedger item : batch) { try { // 每条一个独立事务单条失败不影响整批 transactionTemplate.executeWithoutResult(status - expireOne(item)); } catch (Exception e) { log.error(积分过期失败 txnNo{} userId{}, item.getTxnNo(), item.getUserId(), e); // 失败记录留在原状态交给 T1 的补偿任务再扫一次 } } cursor batch.get(batch.size() - 1).getId(); } }select idselectExpiredAfterId resultTypePointsLedger SELECT id, txn_no, user_id, change_amount FROM points_ledger WHERE status 1 AND expire_at IS NOT NULL AND expire_at lt; #{today} AND id gt; #{cursor} ORDER BY id LIMIT #{batchSize} /select三个要点。第一游标用主键 id 而不是 offset每次从上一批的最大 id 往后扫全程走主键索引翻到第一亿条和第一条的速度一样。第二SELECT 只取需要的四列别写SELECT *过期任务不需要知道规则和场景多取的每一列都是白读的 IO。第三每条流水一个独立事务因为过期是幂等操作——原流水 status 从 1 改成 2 时用WHERE status 1保证只成功一次重复执行不会扣两次。expireOne 内部同样要走条件更新private void expireOne(PointsLedger item) { // 先把原流水标记为已过期靠 status1 的条件保证只处理一次 int marked ledgerMapper.markExpired(item.getId()); if (marked 0) { return; // 已被其他线程处理直接跳过 } // 再扣减账户注意这里也要防止扣成负数 int affected accountMapper.deductAvailable(item.getUserId(), item.getChangeAmount()); if (affected 0) { // 用户已经把分花掉了标记为待补扣挂起人工或后续处理 pendingMapper.insert(item.getUserId(), item.getChangeAmount()); log.warn(过期扣减余额不足转待处理 userId{} amount{}, item.getUserId(), item.getChangeAmount()); return; } ledgerMapper.insert(buildExpireLedger(item)); }「过期扣不动」这个分支是很多人漏掉的。用户拿到 100 分花了 90剩 10这时 100 分的原始流水到期了你按 100 扣就会负 90。正确做法是先扣能扣的剩下的挂到待处理表等用户下次获得积分时优先抵扣。这套系统里 pending 表就是这么用的。4.4 对账一条 SQL 找出所有不平的账户每天跑完过期任务之后,紧接着应该跑一次对账。别指望业务侧永远不出错也别指望自己写的代码没有 bug对账是最后一道防线。-- 账户余额 vs 流水总和两者必须完全相等 SELECT a.user_id, a.available_points AS account_balance, COALESCE(SUM(l.change_amount), 0) AS ledger_balance, a.available_points - COALESCE(SUM(l.change_amount), 0) AS diff FROM points_account a LEFT JOIN points_ledger l ON l.user_id a.user_id GROUP BY a.user_id, a.available_points HAVING diff 0 LIMIT 200;这条 SQL 能成立的前提是流水表只增不改——过期通过新增一条负数流水实现撤销退款也通过新增负数流水实现绝不回头去改原记录的金额。如果团队里有人图省事直接 UPDATE 老流水这条对账 SQL 立刻失效而且你永远查不出是哪天开始对不上的。对账结果不要只打日志diff 不为空的账户要推到告警通道同时把该用户近 30 天的流水全导出来存一份快照方便事后复盘。查出来的典型原因是分布式事务没处理好、消息重复消费、或者有人手工改过数据库。5. 避坑与排查五个让积分对不上的真实原因5.1 数据一致性相关的三个坑坑一重复回调发了两次积分。现象是用户投诉「明明只下了一单积分多了一倍」。排查下来接口层只做了 Redis 的 setnx 去重而 Redis 那次刚好赶上主从切换或者 key 到期去重失效。原因是把幂等完全押在缓存上缓存本身不是可靠的。解决办法是数据库唯一索引 (scene, biz_no) 必须建代码里 catch DuplicateKeyException 当作成功返回Redis 只作为减少数据库压力的前置过滤不承担正确性责任。坑二并发扣减把余额扣成负数。现象是账户表出现 available_points 为负的记录。原因几乎百分之百是「先 SELECT 判断余额再 UPDATE 扣减」这个经典写法判断和更新之间没有原子性。解决办法是把判断搬进 SQL 的 WHERE 条件用AND available_points #{amount}加上影响行数判断。改完以后可以顺手写个 20 线程各扣 10 分的压测用例跑完看余额是否刚好等于初始值减 200对不上就是还有别的地方在裸奔。坑三过期任务把用户扣成负数。现象是过期任务跑完一批用户的余额变成负的。原因是任务里直接按原始流水的金额扣没考虑用户已经花掉一部分。解决办法是过期扣减也走条件更新扣不动就把差额写进待处理表等用户下次获得积分时优先抵扣。另外要在过期任务执行前先冻结账户available_points 转到 frozen_points跑完再解冻避免用户刚好在任务执行期间消费。5.2 任务与性能相关的两个坑坑四凌晨的过期任务跑到第二天中午还没结束。现象是监控显示任务耗时从 20 分钟涨到 8 小时数据库 CPU 长期 90% 以上。原因通常有两个叠加一是用了LIMIT offset, size深分页二是把整批数据塞进一个大事务里。解决办法是换游标分页上一节已经写了配合 500 一批的小事务同时检查索引WHERE status 1 AND expire_at ?如果没有 (status, expire_at) 的联合索引每次都要全表扫。补索引之后同样的数据量耗时能降一个数量级。坑五账不平但查不出是哪一笔。现象是对账 SQL 报出 diff 不为 0但翻流水看不出问题。原因往往是流水表缺少 balance_after 字段或者有人的代码在事务提交前就发了消息导致下游系统重复处理。解决办法是补上 balance_after 并改成事务提交后发消息如果历史数据已经乱了就按时间顺序重放该用户所有流水重新计算每一笔之后的余额跟记录的 balance_after 逐条比对第一个出现偏差的位置就是出问题的地方。这个排查手段我用过好几次比瞎猜快得多。6. 二次开发把积分接到自己业务上的三个改造点6.1 新增一个业务场景其实只改三处接入新场景的路径很清晰不需要动核心逻辑。第一步在 points_rule 表里插一条规则记录把 scene 编码、换算比例、单日上限、有效天数填好第二步在场景枚举类里加上对应的常量顺便定义这个场景是加分还是减分第三步在业务系统的对应位置加一次调用比如订单支付成功后调 grant退款成功后调 revoke。三处改完就能跑核心的发放和扣减逻辑完全复用。真正需要小心的是第三步的调用位置。发放应该放在业务主流程成功之后绝不能在事务中间调退款撤销要传原始的业务单号让幂等键能命中同一笔流水。我一般会在业务侧封装一个 PointsClient把异常吞掉只打日志积分发不出去不能影响主交易——但这点要在业务上跟运营对齐因为很多商城是「不发积分就不算成交」的强一致要求。6.2 验证方法三条用例覆盖八成问题改完代码必须跑这三条用例缺一条都不算改完。用例操作期望结果重复回调同一个 bizNo 连续调两次 grant只有一条流水余额只加一次并发扣减20 线程同时扣同一个用户的积分余额不为负成功的请求数等于余额/单次扣减过期边界造一条 expire_at 为昨天的流水跑过期任务生成一条负数流水原流水 status 变成 2余额正确减少第二条用例最好用 JMeter 或者一段简单的多线程代码跑别用单线程模拟并发问题是模拟不出来的。跑完直接查账户表和流水表的 SUM两者必须一致。6.3 一个技巧把幂等键做成规范而不是随手拼接这套系统里我改得最满意的一处是把 bizNo 的格式强制规范成scene:业务单号:动作。比如订单支付返积分就是order_pay:ORD20240501001:grant同一单退款就是order_pay:ORD20240501001:revoke。这样同一笔业务的不同动作天然互不冲突又都能追溯回原始单号。// 幂等键统一生成禁止业务侧随手拼字符串 public static String bizKey(String scene, String orderNo, String action) { return String.join(:, scene, orderNo, action); }一开始团队里有人觉得这层封装多余直到上线后出现「退款和支付用了同一个 bizNo 导致退款失败」的问题。加上统一生成方法之后这类问题再没出现过。从那以后我每接一个积分需求都会先把幂等键和 balance_after 这两件事钉死在设计评审里谁提「先查余额再扣」的写法都得在会上说清楚为什么。这套源码的 sql 目录和 job 模块都留着照着第 3 章跑一遍就能看到自己的第一笔流水剩下的改造无非是照着第 6 章那三处往下接。希望帮到你。本文还有配套的精品资源点击获取
