账单统计

场景

付费套餐上线后,第一批用户开始付费。

但财务部门找到我:

Finance Chat
周一 09:30
财

需求:

  1. 每月自动生成账单
  2. 统计每个用户的调用量
  3. 计算超额部分
  4. 发送账单给用户

问题分析

我查了一下当前的统计系统:

api_stats_hourlyFields
字段名类型约束 / 说明
idBIGINTPRIMARY KEY, AUTO_INCREMENT
user_idINTNOT NULL
endpointVARCHAR(255)NOT NULL
hourTIMESTAMP精确到小时
total_callsINTDEFAULT 0
success_callsINTDEFAULT 0
error_callsINTDEFAULT 0
avg_response_timeFLOAT平均响应时间(ms)
created_atTIMESTAMPDEFAULT CURRENT_TIMESTAMP
api_stats_hourlyRows
user_idendpointhourtotal_callssuccess_callserror_calls
1001/api/weather2026-04-20 10:001321284
1002/api/forecast2026-04-20 10:0091901

问题:

  1. 统计表每月聚合一次,不是实时的
  2. 没有按 API 分别统计
  3. 没有按时间段统计(用于计算超限)
  4. 没有计费相关的字段

账单系统设计

需求分析

账单需要包含:
1. 基本信息(用户、周期、套餐)
2. 使用情况(总调用量、各 API 调用量)
3. 费用明细(基础费用、超额费用)
4. 支付状态

计费规则:
- 基础费用:套餐月费
- 超额费用:超出套餐部分按次计费
- 超额价格:¥0.001/次(1 元 1000 次)

数据库设计

invoicesFields
字段名类型约束 / 说明
idINTPRIMARY KEY, AUTO_INCREMENT
user_idINTFK -> users.id
subscription_idINTFK -> user_subscriptions.id
billing_period_startDATE账期开始
billing_period_endDATE账期结束
subtotalDECIMAL(10,2)小计
taxDECIMAL(10,2)税费
totalDECIMAL(10,2)总计
total_callsINT周期调用总量
plan_limitINT套餐周期限额
overage_callsINT超额次数
statusVARCHAR(20)draft/sent/paid/overdue/cancelled
sent_atTIMESTAMP发送时间
paid_atTIMESTAMP支付时间
invoicesRows
iduser_idbilling_period_startbilling_period_endtotalstatus
100011012026-04-012026-04-30132.40paid
100022042026-04-012026-04-30529.00sent
100033052026-04-012026-04-3099.00overdue

账单生成逻辑

按用户生成月度账单

账单生成的核心是「一个用户、一个周期、一张账单」。出账时要一次性取齐这个用户在周期内的用量、各 API 调用量和生效套餐,再按计费规则算出基础费用与超额费用,落到账单主表和明细表。这一步必须一次算完算准,因为后面所有环节——用户查询、发送通知、财务对账——都只读这一份结果,不再重算。

设计流程

按用户生成月度账单

  1. 步骤 1:锁定出账对象:用户标识、计费周期和该周期内生效的套餐
  2. 步骤 2:汇总周期内总调用量与各 API 调用量,作为本次计费的用量基准
  3. 步骤 3:按规则计算套餐月费与超额费用,分别写入基础费用和超额费用
  4. 步骤 4:生成账单主记录与逐条明细,校验明细汇总等于账单金额

关注点:账单粒度、用量口径、费用明细与金额一致性。

批量生成账单

月底定时任务

单张账单算对了,还要保证上万个用户能准时拿到。这个月底任务负责遍历全部在付费用户,为每个用户调用一次出账逻辑,并把整体执行状态暴露出来。任务本身必须可重入:网络抖动或进程重启导致重跑时,同一个用户同一周期不能出现两张账单——这正是后面练习里要回答的问题。

设计流程

月底定时任务

  1. 步骤 1:在每月结算日按分区拉取全部待出账用户,生成待处理任务清单
  2. 步骤 2:逐个调用出账逻辑写库,对已存在账单的周期直接跳过而不是重建
  3. 步骤 3:记录每个用户的处理结果与失败原因,支持中断后按批次续跑
  4. 步骤 4:统计本批成功率并对失败用户补跑,全部完成后才进入发送环节

关注点:任务可重入、批次进度可观测、失败用户可补偿。

账单查询 API

获取用户账单列表

用户最常做的一件事就是翻账单。列表接口要按周期倒序返回该用户的账单摘要,每条至少带出周期、总额、已付或未付状态和出账时间,并支持分页。这类接口读多写少,但数据量会随月份线性增长,所以查询要直接打在已建好索引的账单表上,不要在请求里现算聚合。

设计流程

获取用户账单列表

  1. 步骤 1:确定列表返回字段:账单号、计费周期、总金额、支付状态与出账时间
  2. 步骤 2:按用户标识加计费周期倒序查询,走账单表的用户维度索引
  3. 步骤 3:用游标或偏移分页限制单页条数,并只返回已出账的账单

关注点:分页稳定性、列表查询性能、状态字段的可信度。

获取单个账单详情

列表只回答「有哪些账单」,详情才回答「这笔钱是怎么来的」。详情接口要给出账单基础信息、套餐与用量拆分、基础费用与超额费用的分项金额、支付状态以及费用明细列表,让用户能自己核对每一笔超额费用。用户申诉时客服看到的也应该就是这份数据,而不是另做一份统计。

设计流程

获取单个账单详情

  1. 步骤 1:按账单号定位账单主记录,并校验调用者与账单所属用户一致
  2. 步骤 2:组装基础信息、用量拆分、费用分项和支付状态,读取费用明细列表
  3. 步骤 3:校验各项金额之和等于账单总额,且明细条数与用量口径一致

关注点:费用分项可核对、明细可下钻、账单归属的鉴权。

账单发送

自动发送账单

账单生成出来不等于用户看得到,发送环节决定了账单能不能在月底及时触达用户。发送前要确认账单金额和状态已经落库,发送时带上账期、金额和查看详情的入口,并留下发送记录。发送失败不能重发到用户身上造成「重复扣费」的错觉,重试必须幂等。

设计流程

自动发送账单

  1. 步骤 1:只挑选金额已落库、状态为待发送的账单进入发送队列
  2. 步骤 2:按账期、金额和明细入口组装通知内容,保证用户能看懂这笔账
  3. 步骤 3:以账单号作为发送幂等键,记录发送时间与结果,只重试未成功的账单
  4. 步骤 4:发送完成后回写账单状态,并统计送达率供财务核对

关注点:发送时机、通知幂等、用户可理解的信息完整。

练习

练习 1

月底定时任务因为网络问题重试了一次,同一个用户的账单可能被生成两遍。你会怎么避免重复扣费?

计费幂等账单系统

解题思路:

账单系统最重要的是可追溯和幂等,不能只靠「任务应该只跑一次」。核心是唯一键约束、可重试的生成过程,以及把账单生成与实际扣款分成两条独立链路。

详细步骤:

账单系统最重要的是可追溯和幂等,不能只靠“任务应该只跑一次”。

可以这样设计:

  1. 账单唯一键:用 user_id + billing_period 作为唯一约束,同一周期只能有一张正式账单。
  2. 生成过程可重试:重试时先查账单是否已存在,存在就直接返回,不再重复创建。
  3. 费用明细可追溯:账单金额来自明细表,明细也要有唯一标识,避免重复写入。
  4. 支付和账单分开:生成账单不等于扣款,扣款也要有独立的支付流水号和幂等键。

验证时可以故意让任务中途失败,再重复执行,检查账单数量、明细数量和支付流水是否都没有重复。

最终答案:

用 user_id + billing_period 作账单唯一约束,同一周期只允许一张正式账单;生成过程做成可重试,重试时先查账单是否已存在,存在就直接返回;费用明细同样要有唯一标识避免重复写入;账单生成与扣款分离,扣款另设支付流水号与幂等键。验收时用重复触发同一周期的任务来验证只扣一次。

当前架构

技术架构
客户端

用户请求

GET https://dashboard.kuaiyizhi.cn/api/v3/weather?city=北京
负载均衡层

Nginx 负载均衡

应用服务

Nginx

Python

Public API Gateway

Admin API

Static

Admin Dashboard


MySQL

Redis 缓存 + 限流

外部服务

MySQL 计费库

消息队列

外部天气 API

发现内容有问题?

告诉我们哪里需要改进。