跳到正文
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 })

三个约束:

  1. 幂等:bizNo 唯一。重复调用返回首次结果,不重复记账。
  2. 批量原子:一次记账的所有分录,要么全成要么全败。
  3. 无副作用:记账只写分录,不改业务表、不发消息(消息由业务侧发)。

为什么第 3 条很重要:账务一旦回调业务系统,就形成了环, 排查问题时你永远不知道是谁先动的手。

四条硬校验(写死在接口里)

校验规则不过的后果
借贷平衡Σ借 = Σ贷账本从根上就是错的
金额为正整数分录金额 > 0,借贷方向用字段表示负数金额会让红冲逻辑失效
科目存在且可记账对照科目表校验记到叶子节点外,报表汇总不出来
期间未关账所属会计期间必须打开跨期改账,月报已出,无法回溯

任何一条不过,直接抛错,不降级、不部分入账。

余额怎么算:算出来,不要存

这是与"余额表"最本质的区别。

余额 = Σ(历史分录) 或 上次快照 + Σ(快照后分录)

为什么不能只存余额:

  • 存了余额,就必须保证"余额更新"和"分录写入"在同一事务里,否则会漂
  • 一旦漂了,你无法从余额反推是哪笔错了
  • 审计要的是分录,不是数字

工程上的折中:分录是唯一事实,余额是物化视图。 每天日终做一次余额快照,平时用「快照 + 增量」计算。快照可以随时重建。

日终:三件事

① 试算平衡

Σ所有科目借方发生额 = Σ所有科目贷方发生额

不平就是有 bug,当天必须查出来,不能等到月底。

② 余额快照

给每个科目每个维度(币种/主体/商户)写一条快照。 快照要能被重算覆盖——如果发现错了,重跑当天即可,不用修数据。

③ 与业务对账

账务的"应收渠道"  vs  业务系统的"成功但未结算"

这两者对不上,说明有笔业务没记账,或者记错了。

记账失败怎么办

这是最容易被忽略的一环。记账失败意味着业务已经发生,但账没记上。

方案适用风险
业务事务内同步记账强一致要求高的核心链路记账慢会拖垮业务
本地消息表 + 异步记账绝大多数场景需要补偿机制
直接丢弃 + 告警绝不建议账永久缺失

推荐第二种:业务写库时同时写一条"待记账"记录(同一事务), 异步消费、失败重试、超过阈值告警。

判断标准很简单:任何一笔钱动了而账没记,都是事故。 区别只在于你是当天发现,还是三个月后审计发现。

一个反直觉的设计取舍

不要把"记账"做成实时强一致。

很多团队一上来就要求"支付成功必须同步记账成功",结果:

  • 记账服务抖动 → 支付链路超时 → 用户看到失败但钱已扣
  • 为了保记账,把整个支付链路的事务拉长,吞吐骤降

正确做法:支付成功后落"待记账",由账务异步消费。 账务允许晚几秒,但不能允许丢。

自查

  • 业务系统传的是事件类型,不是科目
  • 记账接口只有一个入口,且幂等键是业务流水号
  • 借贷平衡、金额为正、科目合法、期间打开——四条都在接口里校验
  • 余额是算出来的,分录是唯一事实
  • 日终试算平衡 + 余额快照 + 业务对账,三件都做
  • 记账失败有本地消息表兜底,不是丢弃
  • 记账失败率与积压量有监控

依据

  • 复式记账的恒等性:任何时点,Σ借 = Σ贷
  • 事件驱动的账务设计:业务描述事实,账务解释事实
相关阅读