WSO2 Usage Plans、Metering 与 Billing 如何配置？

2026-10-24支付小周

结论

WSO2 文档中的 metering 和 billing，通常针对特定的平台发行版或云端多租户方案。这并不表示任意 WSO2 产品在 standalone mode 下部署后，都会自动提供完整的用量套餐、计费规则和账单模板配置功能。

在 standalone mode 下，可以把相关能力分为三层：

使用 WSO2 API Manager 的 subscription policy、application policy 和 API policy 等机制控制调用额度与速率。
从分析数据、日志或自定义事件中采集实际用量。
将用量数据交给外部计费系统，由其计算费用并生成账单。

具体来说：

可以自定义使用套餐，但这类套餐首先用于限流和配额管理，不一定等同于商业计费套餐。
Metering 可以基于网关指标、分析事件或自定义日志实现。
Billing rules 一般需要自行开发，或者接入独立的计费平台。
Billing template 通常不是 standalone WSO2 的通用配置项，更适合在外部账单系统中定制。

不同代际的 WSO2 产品差异很大。早期的 WSO2 Stratos、后来的 WSO2 API Manager，以及当前产品中的 monetization、analytics 和 throttling，所指的概念并不完全相同。实施前需要确认正在评估的产品和版本，并以相应版本的文档为准。

Usage Plan 应如何定义

如果 “usage plan” 指 API 调用套餐，可以用 API Manager 的策略模型来表达，例如：

每分钟最多调用 100 次；
每月最多调用 100 万次；
超过配额后拒绝请求；
为不同套餐设置不同的突发流量限制。

策略名称可以直接对应业务套餐：

FREE
STANDARD
PREMIUM

下面是一个概念性的套餐定义：

name: STANDARD
quota:
  requestCount: 1000000
  period: MONTH
rateLimit:
  requestCount: 100
  period: MINUTE
overage:
  action: BLOCK

这段 YAML 只用于说明数据模型，不表示所有 WSO2 版本都能直接导入这种格式。实际创建方式可能是管理控制台、REST API、部署配置或控制平面接口，具体取决于对应版本提供的能力。

这里还需要区分两个概念：

限流套餐决定客户端能调用多少次，以及调用速度有多快。
商业套餐定义免费额度、单价、阶梯价格、税费和结算周期。

WSO2 的流量策略更适合处理限流套餐。商业套餐通常还需要单独的计费服务。

Metering 如何实现

Metering 需要为每一次可计费行为生成可审计的用量记录。记录中建议至少包含以下字段：

{
  "eventId": "8df9e659-62df-4cb5-a209-b33d57bf5101",
  "tenantId": "customer-a",
  "applicationId": "mobile-app",
  "apiId": "orders-api",
  "operation": "POST /orders",
  "timestamp": "2026-09-01T08:15:30Z",
  "statusCode": 201,
  "requestCount": 1,
  "requestBytes": 842,
  "responseBytes": 2130,
  "latencyMs": 184
}

常见的处理流程如下：

API Gateway
    -> 生成访问事件
    -> 日志、分析平台或消息队列
    -> 用量聚合服务
    -> 计费引擎
    -> 账单系统

聚合用量时，不能只依赖限流计数器。限流计数器用于实时控制流量，未必能满足账单系统对数据完整性、长期留存和可追溯性的要求。

Metering 还需要明确以下统计口径：

请求到达网关时计费，还是成功响应后计费；
4xx、5xx 和超时请求是否计费；
重试是否算作一次新的计费调用；
按请求次数、数据量、响应时间还是业务结果计费；
月度统计使用 UTC，还是客户所在时区；
用量事件重复投递时如何去重。

可以使用稳定的 eventId 进行幂等处理，防止消息重试造成重复收费。

Billing Rules 如何定义

计费规则可以放在独立服务或规则引擎中。下面是一个阶梯计费模型示例：

plan: STANDARD
currency: USD
billingCycle: MONTHLY

includedUsage:
  requests: 100000

tiers:
  - from: 100001
    to: 1000000
    unitPrice: 0.0008
  - from: 1000001
    unitPrice: 0.0005

billableStatuses:
  - 200-399

tax:
  rate: 0.00

对应的费用公式可以写成：

billable_usage = max(successful_requests - included_requests, 0)

subtotal =
    min(billable_usage, 900000) × 0.0008
    + max(billable_usage - 900000, 0) × 0.0005

total = subtotal + tax

生产环境还要处理套餐变更、按天折算、退款、优惠、税率、最低消费和账期关闭等情况。这些通常不属于 API 网关本身的职责。

计费接口可以采用下面这样的设计：

POST /billing/v1/usage
Content-Type: application/json
Idempotency-Key: 8df9e659-62df-4cb5-a209-b33d57bf5101

{
  "customerId": "customer-a",
  "metric": "api.successful_request",
  "quantity": 1,
  "occurredAt": "2026-09-01T08:15:30Z",
  "dimensions": {
    "api": "orders-api",
    "operation": "POST /orders"
  }
}

这个接口也是集成设计示例，并非 WSO2 官方提供的固定 API。

Billing Template 能否自定义

使用外部计费或财务系统时，账单模板一般可以按需定制，内容包括：

企业名称和 Logo；
客户及税务信息；
套餐名称和账期；
API 用量明细；
阶梯单价；
折扣、税费和应付金额；
PDF、HTML 或邮件格式。

例如，可以通过模板变量生成 HTML 账单：

<h1>Invoice {{ invoice.number }}</h1>

<p>Billing period: {{ invoice.period }}</p>
<p>Customer: {{ customer.name }}</p>

<table>
  <thead>
    <tr>
      <th>API</th>
      <th>Usage</th>
      <th>Unit price</th>
      <th>Amount</th>
    </tr>
  </thead>
  <tbody>
    {{#each items}}
    <tr>
      <td>{{ apiName }}</td>
      <td>{{ quantity }}</td>
      <td>{{ unitPrice }}</td>
      <td>{{ amount }}</td>
    </tr>
    {{/each}}
  </tbody>
</table>

<strong>Total: {{ invoice.currency }} {{ invoice.total }}</strong>

如果某个 WSO2 发行版自带 billing UI 或 invoice 模块，能否修改模板以及如何扩展，完全取决于具体版本。不能仅凭 “平台支持 billing” 就推断系统中存在统一的 billing-template.xml 或类似配置文件。

WSO2 Usage Plans、Metering 与 Billing 如何配置？

结论

Usage Plan 应如何定义

Metering 如何实现

Billing Rules 如何定义

Billing Template 能否自定义

推荐的落地方式