积分接口对接手记：从发帖回帖到积分到账的全链路踩坑记录

最近在给社区做一套积分体系，需求很简单：用户发帖得积分、回帖得积分、积分变动要实时展示。听着不难，真正动手对接的时候才发现，发帖、回帖、积分接口这三者之间的联动，藏着不少容易忽略的细节。这篇帖子就把我踩过的坑和最终跑通的流程整理出来，给同样在做这个功能的朋友一个参考。

先说整体思路。积分系统不能独立存在，它必须挂在现有内容动作上。我的做法是：在发帖成功和回帖成功的回调里，分别调用积分接口，传入用户ID、动作类型和关联内容ID。积分接口收到请求后，先查重（防止重复加分），再更新用户积分总表，同时写一条积分流水记录。这样用户在前端看到积分变化时，后台也能查到每一笔的来源。

第一个坑出现在发帖回调里。我最初把积分接口调用直接写在发帖的保存逻辑后面，结果发现如果积分接口报错，会导致整个发帖流程失败，用户那边直接看到“发帖失败”的提示。后来改成异步处理：发帖主流程只负责保存内容，积分操作放进消息队列或者用计划任务轮询待处理列表。用户发帖即时成功，积分稍后到账，体验上没什么差别，但稳定性提升了很多。

第二个坑是回帖的重复加分问题。用户快速连发两条回帖，或者网络抖动导致前端重试，很容易触发两次积分接口调用。我一开始在积分接口里加了个简单的时间窗口判断，比如同一个用户对同一个主题的加分间隔不能小于30秒，但后来发现这个方案太粗暴，用户连续认真回帖会被误伤。最终改成了基于内容ID的唯一索引：每条回帖在积分表里对应一条记录，数据库层面保证同一个回帖ID只能加分一次。

第三个坑是积分流水的展示。用户想看自己的积分明细，需要把发帖、回帖、签到、打赏等所有积分变动统一拉出来。我建了一张积分流水表，字段包括用户ID、变动值、变动类型、关联内容ID、创建时间。前端列表页直接查这张表，按时间倒序分页展示。这里要注意的是，流水表只存变动值，不存当前总积分，总积分单独维护在用户表里，每次变动时更新。这样查询明细和查询总余额互不干扰，性能也更好。

最后补充一个对接时的细节：积分接口的返回格式一定要统一。我用的格式是`{code: 0, data: {balance: 123}, msg: "success"}`，发帖和回帖模块只需要判断code是否为0，其余字段一概不关心。这样后续如果积分规则调整，比如增加双倍积分日，只需要改积分接口内部逻辑，发帖和回帖模块完全不用动。

整个流程跑通之后，我又加了一个小功能：用户发帖成功后，前端通过轮询积分接口的余额字段，实现积分数字的平滑滚动动画，效果还挺讨喜的。如果你也在做类似的积分对接，建议先把数据流图画清楚，再动手写代码，能少走不少弯路。