账单统计
场景
付费套餐上线后,第一批用户开始付费。
但财务部门找到我:
财
需求:
- 每月自动生成账单
- 统计每个用户的调用量
- 计算超额部分
- 发送账单给用户
问题分析
我查了一下当前的统计系统:
| 字段名 | 类型 | 约束 / 说明 |
|---|
id | BIGINT | PRIMARY KEY, AUTO_INCREMENT |
endpoint | VARCHAR(255) | NOT NULL |
params | TEXT | 请求参数 |
response_status | INT | HTTP 状态码 |
response_time | INT | 响应时间(ms) |
created_at | TIMESTAMP | DEFAULT CURRENT_TIMESTAMP |
| id | endpoint | params | response_status | response_time | created_at |
|---|
1 | /api/weather | city=北京 | 200 | 118 | 2026-03-31 14:00:00 |
2 | /api/weather | city=上海 | 200 | 132 | 2026-03-31 14:01:00 |
3 | /api/weather | city=广州 | 500 | 240 | 2026-03-31 14:02:00 |
| 字段名 | 类型 | 约束 / 说明 |
|---|
id | INT | PRIMARY KEY, AUTO_INCREMENT |
email | VARCHAR(255) | UNIQUE, NOT NULL |
password_hash | VARCHAR(255) | NOT NULL |
api_key | VARCHAR(64) | UNIQUE, NOT NULL |
plan | VARCHAR(50) | DEFAULT 'free' |
daily_limit | INT | DEFAULT 1000 |
created_at | TIMESTAMP | DEFAULT CURRENT_TIMESTAMP |
| id | email | plan | daily_limit | created_at |
|---|
1 | alice@demo.com | free | 1000 | 2026-04-08 10:32:11 |
2 | bob@demo.com | pro | 100000 | 2026-04-11 09:15:02 |
3 | ops@demo.com | basic | 10000 | 2026-04-13 21:44:36 |
| 字段名 | 类型 | 约束 / 说明 |
|---|
id | BIGINT | PRIMARY KEY, AUTO_INCREMENT |
user_id | INT | NOT NULL |
endpoint | VARCHAR(255) | NOT NULL |
hour | TIMESTAMP | 精确到小时 |
total_calls | INT | DEFAULT 0 |
success_calls | INT | DEFAULT 0 |
error_calls | INT | DEFAULT 0 |
avg_response_time | FLOAT | 平均响应时间(ms) |
created_at | TIMESTAMP | DEFAULT CURRENT_TIMESTAMP |
| user_id | endpoint | hour | total_calls | success_calls | error_calls |
|---|
1001 | /api/weather | 2026-04-20 10:00 | 132 | 128 | 4 |
1002 | /api/forecast | 2026-04-20 10:00 | 91 | 90 | 1 |
| 字段名 | 类型 | 约束 / 说明 |
|---|
id | BIGINT | PRIMARY KEY, AUTO_INCREMENT |
user_id | INT | NOT NULL |
endpoint | VARCHAR(255) | NOT NULL |
date | DATE | 统计日期 |
total_calls | INT | DEFAULT 0 |
success_calls | INT | DEFAULT 0 |
error_calls | INT | DEFAULT 0 |
avg_response_time | FLOAT | 平均响应时间(ms) |
p95_response_time | FLOAT | 95分位响应时间(ms) |
p99_response_time | FLOAT | 99分位响应时间(ms) |
created_at | TIMESTAMP | DEFAULT CURRENT_TIMESTAMP |
| user_id | endpoint | date | total_calls | success_calls | error_calls |
|---|
1001 | /api/weather | 2026-04-20 | 2410 | 2368 | 42 |
1002 | /api/forecast | 2026-04-20 | 1832 | 1810 | 22 |
| 字段名 | 类型 | 约束 / 说明 |
|---|
id | BIGINT | PRIMARY KEY, AUTO_INCREMENT |
user_id | INT | NOT NULL |
month | DATE | 每月1号 |
total_calls | INT | DEFAULT 0 |
total_success | INT | DEFAULT 0 |
total_error | INT | DEFAULT 0 |
avg_daily_calls | FLOAT | 日均调用次数 |
peak_hour_calls | INT | 峰值小时调用量 |
most_used_endpoint | VARCHAR(255) | 最常调用接口 |
created_at | TIMESTAMP | DEFAULT CURRENT_TIMESTAMP |
| user_id | month | total_calls | total_success | total_error | avg_daily_calls |
|---|
1001 | 2026-04 | 58420 | 57110 | 1310 | 1947 |
1002 | 2026-04 | 40680 | 39920 | 760 | 1356 |
问题:
- 统计表每月聚合一次,不是实时的
- 没有按 API 分别统计
- 没有按时间段统计(用于计算超限)
- 没有计费相关的字段
账单系统设计
需求分析
账单需要包含:
1. 基本信息(用户、周期、套餐)
2. 使用情况(总调用量、各 API 调用量)
3. 费用明细(基础费用、超额费用)
4. 支付状态
计费规则:
- 基础费用:套餐月费
- 超额费用:超出套餐部分按次计费
- 超额价格:¥0.001/次(1 元 1000 次)
数据库设计
| 字段名 | 类型 | 约束 / 说明 |
|---|
id | BIGINT | PRIMARY KEY, AUTO_INCREMENT |
endpoint | VARCHAR(255) | NOT NULL |
params | TEXT | 请求参数 |
response_status | INT | HTTP 状态码 |
response_time | INT | 响应时间(ms) |
created_at | TIMESTAMP | DEFAULT CURRENT_TIMESTAMP |
| id | endpoint | params | response_status | response_time | created_at |
|---|
1 | /api/weather | city=北京 | 200 | 118 | 2026-03-31 14:00:00 |
2 | /api/weather | city=上海 | 200 | 132 | 2026-03-31 14:01:00 |
3 | /api/weather | city=广州 | 500 | 240 | 2026-03-31 14:02:00 |
| 字段名 | 类型 | 约束 / 说明 |
|---|
id | INT | PRIMARY KEY, AUTO_INCREMENT |
email | VARCHAR(255) | UNIQUE, NOT NULL |
password_hash | VARCHAR(255) | NOT NULL |
api_key | VARCHAR(64) | UNIQUE, NOT NULL |
plan | VARCHAR(50) | DEFAULT 'free' |
daily_limit | INT | DEFAULT 1000 |
created_at | TIMESTAMP | DEFAULT CURRENT_TIMESTAMP |
| id | email | plan | daily_limit | created_at |
|---|
1 | alice@demo.com | free | 1000 | 2026-04-08 10:32:11 |
2 | bob@demo.com | pro | 100000 | 2026-04-11 09:15:02 |
3 | ops@demo.com | basic | 10000 | 2026-04-13 21:44:36 |
| 字段名 | 类型 | 约束 / 说明 |
|---|
id | BIGINT | PRIMARY KEY, AUTO_INCREMENT |
user_id | INT | NOT NULL |
endpoint | VARCHAR(255) | NOT NULL |
hour | TIMESTAMP | 精确到小时 |
total_calls | INT | DEFAULT 0 |
success_calls | INT | DEFAULT 0 |
error_calls | INT | DEFAULT 0 |
avg_response_time | FLOAT | 平均响应时间(ms) |
created_at | TIMESTAMP | DEFAULT CURRENT_TIMESTAMP |
| user_id | endpoint | hour | total_calls | success_calls | error_calls |
|---|
1001 | /api/weather | 2026-04-20 10:00 | 132 | 128 | 4 |
1002 | /api/forecast | 2026-04-20 10:00 | 91 | 90 | 1 |
| 字段名 | 类型 | 约束 / 说明 |
|---|
id | BIGINT | PRIMARY KEY, AUTO_INCREMENT |
user_id | INT | NOT NULL |
endpoint | VARCHAR(255) | NOT NULL |
date | DATE | 统计日期 |
total_calls | INT | DEFAULT 0 |
success_calls | INT | DEFAULT 0 |
error_calls | INT | DEFAULT 0 |
avg_response_time | FLOAT | 平均响应时间(ms) |
p95_response_time | FLOAT | 95分位响应时间(ms) |
p99_response_time | FLOAT | 99分位响应时间(ms) |
created_at | TIMESTAMP | DEFAULT CURRENT_TIMESTAMP |
| user_id | endpoint | date | total_calls | success_calls | error_calls |
|---|
1001 | /api/weather | 2026-04-20 | 2410 | 2368 | 42 |
1002 | /api/forecast | 2026-04-20 | 1832 | 1810 | 22 |
| 字段名 | 类型 | 约束 / 说明 |
|---|
id | BIGINT | PRIMARY KEY, AUTO_INCREMENT |
user_id | INT | NOT NULL |
month | DATE | 每月1号 |
total_calls | INT | DEFAULT 0 |
total_success | INT | DEFAULT 0 |
total_error | INT | DEFAULT 0 |
avg_daily_calls | FLOAT | 日均调用次数 |
peak_hour_calls | INT | 峰值小时调用量 |
most_used_endpoint | VARCHAR(255) | 最常调用接口 |
created_at | TIMESTAMP | DEFAULT CURRENT_TIMESTAMP |
| user_id | month | total_calls | total_success | total_error | avg_daily_calls |
|---|
1001 | 2026-04 | 58420 | 57110 | 1310 | 1947 |
1002 | 2026-04 | 40680 | 39920 | 760 | 1356 |
| 字段名 | 类型 | 约束 / 说明 |
|---|
id | INT | PRIMARY KEY, AUTO_INCREMENT |
name | VARCHAR(100) | UNIQUE, NOT NULL |
display_name | VARCHAR(100) | NOT NULL |
endpoint | VARCHAR(255) | NOT NULL |
method | VARCHAR(10) | DEFAULT 'GET' |
category | VARCHAR(50) | weather/news/finance/tools |
external_api_url | VARCHAR(255) | 上游服务地址 |
requires_auth | BOOLEAN | DEFAULT TRUE |
cache_ttl | INT | 缓存时间(秒) |
rate_limit_factor | INT | DEFAULT 1 |
status | VARCHAR(20) | active/deprecated/maintenance |
is_public | BOOLEAN | DEFAULT TRUE |
created_at | TIMESTAMP | DEFAULT CURRENT_TIMESTAMP |
updated_at | TIMESTAMP | ON UPDATE CURRENT_TIMESTAMP |
| id | name | display_name | category | method | cache_ttl | status |
|---|
1 | weather | 天气查询 | weather | GET | 3600 | active |
2 | news | 新闻快讯 | news | GET | 300 | active |
3 | stock | 股票行情 | finance | GET | 60 | maintenance |
user_api_permissionsFields| 字段名 | 类型 | 约束 / 说明 |
|---|
id | INT | PRIMARY KEY, AUTO_INCREMENT |
user_id | INT | NOT NULL |
api_id | INT | NOT NULL, FK -> api_definitions.id |
granted_at | TIMESTAMP | DEFAULT CURRENT_TIMESTAMP |
expires_at | TIMESTAMP | NULL 表示长期有效 |
status | VARCHAR(20) | active/revoked/expired |
| id | user_id | api_id | granted_at | expires_at | status |
|---|
8001 | 101 | 1 | 2026-04-10 10:00:00 | NULL | active |
8002 | 101 | 2 | 2026-04-10 10:00:00 | 2026-05-10 10:00:00 | active |
8003 | 204 | 3 | 2026-04-01 09:15:00 | 2026-04-30 23:59:59 | expired |
| 字段名 | 类型 | 约束 / 说明 |
|---|
id | BIGINT | NOT NULL, AUTO_INCREMENT |
user_id | INT | NOT NULL |
endpoint | VARCHAR(255) | NOT NULL |
params | TEXT | 请求参数 |
response_time | INT | 毫秒 |
status | VARCHAR(50) | 调用状态 |
created_at | TIMESTAMP | 分区键 |
pk | PRIMARY KEY(id, created_at) | 支持范围分区 |
| partition | range | records | storage | hotness |
|---|
p202401 | < 2024-02-01 | 58,200,000 | 370 GB | cold |
p202402 | < 2024-03-01 | 61,900,000 | 395 GB | warm |
pmax | MAXVALUE | ongoing | rolling | hot |
| 字段名 | 类型 | 约束 / 说明 |
|---|
id | BIGINT | NOT NULL |
user_id | INT | NOT NULL |
endpoint | VARCHAR(255) | NOT NULL |
response_time | INT | 毫秒 |
status | VARCHAR(50) | 调用状态 |
created_at | TIMESTAMP | 分层依据 |
storage_tier | VARCHAR(20) | hot/warm/cold |
archive_uri | VARCHAR(255) | 冷数据对象存储地址 |
| tier | time_range | query_freq | storage | cost_level |
|---|
hot | 0-30 days | high | MySQL 主库 | high |
warm | 30-180 days | medium | MySQL 从库 | medium |
cold | >180 days | low | 对象存储 | low |
| 字段名 | 类型 | 约束 / 说明 |
|---|
id | INT | PRIMARY KEY, AUTO_INCREMENT |
name | VARCHAR(50) | UNIQUE, free/basic/pro/enterprise |
display_name | VARCHAR(100) | 套餐展示名 |
price_monthly | DECIMAL(10,2) | 月费 |
daily_limit | INT | 每日配额 |
rate_limit_per_second | INT | 每秒限流 |
burst_capacity | INT | 突发容量 |
max_apis | INT | 可用 API 数量 |
data_retention_days | INT | 数据保留天数 |
support_type | VARCHAR(50) | community/email/priority/dedicated |
custom_domain | BOOLEAN | 是否支持自定义域名 |
created_at | TIMESTAMP | DEFAULT CURRENT_TIMESTAMP |
| id | name | price_monthly | daily_limit | rate_limit_per_second | support_type |
|---|
1 | free | 0.00 | 1000 | 1 | community |
2 | basic | 99.00 | 10000 | 10 | email |
3 | pro | 499.00 | 100000 | 100 | priority |
| 字段名 | 类型 | 约束 / 说明 |
|---|
id | INT | PRIMARY KEY, AUTO_INCREMENT |
user_id | INT | UNIQUE, FK -> users.id |
plan_id | INT | FK -> pricing_plans.id |
billing_cycle | VARCHAR(20) | monthly/yearly |
status | VARCHAR(20) | active/cancelled/expired/past_due |
current_period_start | TIMESTAMP | 当前周期开始 |
current_period_end | TIMESTAMP | 当前周期结束 |
cancel_at_period_end | BOOLEAN | 期末取消标记 |
payment_method_id | VARCHAR(255) | 支付渠道 ID |
updated_at | TIMESTAMP | ON UPDATE CURRENT_TIMESTAMP |
| id | user_id | plan_id | billing_cycle | status | current_period_end |
|---|
501 | 101 | 2 | monthly | active | 2026-05-31 23:59:59 |
502 | 204 | 3 | yearly | active | 2027-04-30 23:59:59 |
503 | 305 | 1 | monthly | past_due | 2026-04-30 23:59:59 |
| 字段名 | 类型 | 约束 / 说明 |
|---|
id | INT | PRIMARY KEY, AUTO_INCREMENT |
user_id | INT | FK -> users.id |
subscription_id | INT | FK -> user_subscriptions.id |
billing_period_start | DATE | 账期开始 |
billing_period_end | DATE | 账期结束 |
subtotal | DECIMAL(10,2) | 小计 |
tax | DECIMAL(10,2) | 税费 |
total | DECIMAL(10,2) | 总计 |
total_calls | INT | 周期调用总量 |
plan_limit | INT | 套餐周期限额 |
overage_calls | INT | 超额次数 |
status | VARCHAR(20) | draft/sent/paid/overdue/cancelled |
sent_at | TIMESTAMP | 发送时间 |
paid_at | TIMESTAMP | 支付时间 |
| id | user_id | billing_period_start | billing_period_end | total | status |
|---|
10001 | 101 | 2026-04-01 | 2026-04-30 | 132.40 | paid |
10002 | 204 | 2026-04-01 | 2026-04-30 | 529.00 | sent |
10003 | 305 | 2026-04-01 | 2026-04-30 | 99.00 | overdue |
| 字段名 | 类型 | 约束 / 说明 |
|---|
id | INT | PRIMARY KEY, AUTO_INCREMENT |
invoice_id | INT | FK -> invoices.id |
description | VARCHAR(255) | 费用项描述 |
quantity | INT | 数量 |
unit_price | DECIMAL(10,2) | 单价 |
amount | DECIMAL(10,2) | 金额 |
item_type | VARCHAR(50) | base_fee/overage/discount/tax |
metadata | JSON | 扩展信息 |
| id | invoice_id | description | quantity | unit_price | amount |
|---|
20001 | 10001 | 基础套餐费(Basic) | 1 | 99.00 | 99.00 |
20002 | 10001 | 超额调用费 | 28400 | 0.001 | 28.40 |
20003 | 10001 | 税费 | 1 | 5.00 | 5.00 |
账单生成逻辑
按用户生成月度账单
账单生成的核心是「一个用户、一个周期、一张账单」。出账时要一次性取齐这个用户在周期内的用量、各 API 调用量和生效套餐,再按计费规则算出基础费用与超额费用,落到账单主表和明细表。这一步必须一次算完算准,因为后面所有环节——用户查询、发送通知、财务对账——都只读这一份结果,不再重算。
设计流程按用户生成月度账单
- 步骤 1:锁定出账对象:用户标识、计费周期和该周期内生效的套餐
- 步骤 2:汇总周期内总调用量与各 API 调用量,作为本次计费的用量基准
- 步骤 3:按规则计算套餐月费与超额费用,分别写入基础费用和超额费用
- 步骤 4:生成账单主记录与逐条明细,校验明细汇总等于账单金额
关注点:账单粒度、用量口径、费用明细与金额一致性。
批量生成账单
月底定时任务
单张账单算对了,还要保证上万个用户能准时拿到。这个月底任务负责遍历全部在付费用户,为每个用户调用一次出账逻辑,并把整体执行状态暴露出来。任务本身必须可重入:网络抖动或进程重启导致重跑时,同一个用户同一周期不能出现两张账单——这正是后面练习里要回答的问题。
设计流程月底定时任务
- 步骤 1:在每月结算日按分区拉取全部待出账用户,生成待处理任务清单
- 步骤 2:逐个调用出账逻辑写库,对已存在账单的周期直接跳过而不是重建
- 步骤 3:记录每个用户的处理结果与失败原因,支持中断后按批次续跑
- 步骤 4:统计本批成功率并对失败用户补跑,全部完成后才进入发送环节
关注点:任务可重入、批次进度可观测、失败用户可补偿。
账单查询 API
获取用户账单列表
用户最常做的一件事就是翻账单。列表接口要按周期倒序返回该用户的账单摘要,每条至少带出周期、总额、已付或未付状态和出账时间,并支持分页。这类接口读多写少,但数据量会随月份线性增长,所以查询要直接打在已建好索引的账单表上,不要在请求里现算聚合。
设计流程获取用户账单列表
- 步骤 1:确定列表返回字段:账单号、计费周期、总金额、支付状态与出账时间
- 步骤 2:按用户标识加计费周期倒序查询,走账单表的用户维度索引
- 步骤 3:用游标或偏移分页限制单页条数,并只返回已出账的账单
关注点:分页稳定性、列表查询性能、状态字段的可信度。
获取单个账单详情
列表只回答「有哪些账单」,详情才回答「这笔钱是怎么来的」。详情接口要给出账单基础信息、套餐与用量拆分、基础费用与超额费用的分项金额、支付状态以及费用明细列表,让用户能自己核对每一笔超额费用。用户申诉时客服看到的也应该就是这份数据,而不是另做一份统计。
设计流程获取单个账单详情
- 步骤 1:按账单号定位账单主记录,并校验调用者与账单所属用户一致
- 步骤 2:组装基础信息、用量拆分、费用分项和支付状态,读取费用明细列表
- 步骤 3:校验各项金额之和等于账单总额,且明细条数与用量口径一致
关注点:费用分项可核对、明细可下钻、账单归属的鉴权。
账单发送
自动发送账单
账单生成出来不等于用户看得到,发送环节决定了账单能不能在月底及时触达用户。发送前要确认账单金额和状态已经落库,发送时带上账期、金额和查看详情的入口,并留下发送记录。发送失败不能重发到用户身上造成「重复扣费」的错觉,重试必须幂等。
设计流程自动发送账单
- 步骤 1:只挑选金额已落库、状态为待发送的账单进入发送队列
- 步骤 2:按账期、金额和明细入口组装通知内容,保证用户能看懂这笔账
- 步骤 3:以账单号作为发送幂等键,记录发送时间与结果,只重试未成功的账单
- 步骤 4:发送完成后回写账单状态,并统计送达率供财务核对
关注点:发送时机、通知幂等、用户可理解的信息完整。
练习
练习 1
月底定时任务因为网络问题重试了一次,同一个用户的账单可能被生成两遍。你会怎么避免重复扣费?
计费幂等账单系统
解题思路:
账单系统最重要的是可追溯和幂等,不能只靠「任务应该只跑一次」。核心是唯一键约束、可重试的生成过程,以及把账单生成与实际扣款分成两条独立链路。
详细步骤:
账单系统最重要的是可追溯和幂等,不能只靠“任务应该只跑一次”。
可以这样设计:
- 账单唯一键:用
user_id + billing_period 作为唯一约束,同一周期只能有一张正式账单。
- 生成过程可重试:重试时先查账单是否已存在,存在就直接返回,不再重复创建。
- 费用明细可追溯:账单金额来自明细表,明细也要有唯一标识,避免重复写入。
- 支付和账单分开:生成账单不等于扣款,扣款也要有独立的支付流水号和幂等键。
验证时可以故意让任务中途失败,再重复执行,检查账单数量、明细数量和支付流水是否都没有重复。
最终答案:
用 user_id + billing_period 作账单唯一约束,同一周期只允许一张正式账单;生成过程做成可重试,重试时先查账单是否已存在,存在就直接返回;费用明细同样要有唯一标识避免重复写入;账单生成与扣款分离,扣款另设支付流水号与幂等键。验收时用重复触发同一周期的任务来验证只扣一次。
当前架构
GET https://dashboard.kuaiyizhi.cn/api/v3/weather?city=北京