D8-02账务域3 分钟更新于 2026-11
记账接口设计
一句话
账务核心只该暴露一个记账接口,业务系统永远不知道科目长什么样。
本文目录12 节
记账接口设计
先定边界:谁决定科目
这是账务域最容易吵起来的问题。
| 方案 | 业务系统要传什么 | 结果 |
|---|---|---|
| ❌ 业务传科目 | 借 1001 贷 2001 | 每加一个业务都要改业务代码,科目散落全系统 |
| ✅ 业务传"事件" | {type: 'payment_success', amount, ...} | 账务自己决定科目,业务只描述发生了什么 |
结论:业务说"发生了什么",账务决定"怎么记"。
这条边界一旦反过来,账务就从"核心"退化成了"存储"。
唯一入口:一个幂等的 post
/**
* @param {string} bizNo 业务流水号(幂等键)
* @param {string} eventType 事件类型,如 payment_success / refund_success
* @param {object} payload 业务数据
*/
async function post({ bizNo, eventType, payload })
三个约束:
- 幂等:
bizNo唯一。重复调用返回首次结果,不重复记账。 - 批量原子:一次记账的所有分录,要么全成要么全败。
- 无副作用:记账只写分录,不改业务表、不发消息(消息由业务侧发)。
为什么第 3 条很重要:账务一旦回调业务系统,就形成了环, 排查问题时你永远不知道是谁先动的手。
四条硬校验(写死在接口里)
| 校验 | 规则 | 不过的后果 |
|---|---|---|
| 借贷平衡 | Σ借 = Σ贷 | 账本从根上就是错的 |
| 金额为正整数 | 分录金额 > 0,借贷方向用字段表示 | 负数金额会让红冲逻辑失效 |
| 科目存在且可记账 | 对照科目表校验 | 记到叶子节点外,报表汇总不出来 |
| 期间未关账 | 所属会计期间必须打开 | 跨期改账,月报已出,无法回溯 |
任何一条不过,直接抛错,不降级、不部分入账。
余额怎么算:算出来,不要存
这是与"余额表"最本质的区别。
余额 = Σ(历史分录) 或 上次快照 + Σ(快照后分录)
为什么不能只存余额:
- 存了余额,就必须保证"余额更新"和"分录写入"在同一事务里,否则会漂
- 一旦漂了,你无法从余额反推是哪笔错了
- 审计要的是分录,不是数字
工程上的折中:分录是唯一事实,余额是物化视图。 每天日终做一次余额快照,平时用「快照 + 增量」计算。快照可以随时重建。
日终:三件事
① 试算平衡
Σ所有科目借方发生额 = Σ所有科目贷方发生额
不平就是有 bug,当天必须查出来,不能等到月底。
② 余额快照
给每个科目每个维度(币种/主体/商户)写一条快照。 快照要能被重算覆盖——如果发现错了,重跑当天即可,不用修数据。
③ 与业务对账
账务的"应收渠道" vs 业务系统的"成功但未结算"
这两者对不上,说明有笔业务没记账,或者记错了。
记账失败怎么办
这是最容易被忽略的一环。记账失败意味着业务已经发生,但账没记上。
| 方案 | 适用 | 风险 |
|---|---|---|
| 业务事务内同步记账 | 强一致要求高的核心链路 | 记账慢会拖垮业务 |
| 本地消息表 + 异步记账 | 绝大多数场景 | 需要补偿机制 |
| 直接丢弃 + 告警 | 绝不建议 | 账永久缺失 |
推荐第二种:业务写库时同时写一条"待记账"记录(同一事务), 异步消费、失败重试、超过阈值告警。
判断标准很简单:任何一笔钱动了而账没记,都是事故。 区别只在于你是当天发现,还是三个月后审计发现。
一个反直觉的设计取舍
不要把"记账"做成实时强一致。
很多团队一上来就要求"支付成功必须同步记账成功",结果:
- 记账服务抖动 → 支付链路超时 → 用户看到失败但钱已扣
- 为了保记账,把整个支付链路的事务拉长,吞吐骤降
正确做法:支付成功后落"待记账",由账务异步消费。 账务允许晚几秒,但不能允许丢。
自查
- 业务系统传的是事件类型,不是科目
- 记账接口只有一个入口,且幂等键是业务流水号
- 借贷平衡、金额为正、科目合法、期间打开——四条都在接口里校验
- 余额是算出来的,分录是唯一事实
- 日终试算平衡 + 余额快照 + 业务对账,三件都做
- 记账失败有本地消息表兜底,不是丢弃
- 记账失败率与积压量有监控
依据
- 复式记账的恒等性:任何时点,Σ借 = Σ贷
- 事件驱动的账务设计:业务描述事实,账务解释事实
相关阅读