从 0 到 1 搭建可收费的 API 开放平台（实战）

一、需求

很多团队手上都有一条现成的内部接口，比如评分查询、发票查验、短信发送、OCR 识别。接口本身跑得很稳，但一直没有对外开放收费。

要做的事可以拆成几块：把内部接口挂到开放平台、给接口配价格、让外部开发者能自助购买和调用、把钱收上来。下面以 YesApi Pro（Java 版）为例，给一套可落地的实现步骤。YesApi Pro 是一套覆盖接口开发、管理、开放、计费的系统，把计费、支付、开发者管理这些底层零件提前封装好了，团队只需要把业务接口接进去。

二、技术方案概览

平台采用 Spring Boot 3 + Vue3 + Docker 技术栈。要把内部能力变成收费服务，本质上需要一条链路：接口开发 → 计费配置 → 支付订单 → 开发者接入 → 限流监控。

一个可参考的项目目录大致是

bash 复制代码

api-platform/
├── gateway/          # 统一入口、鉴权、限流
├── interface-svc/    # 低代码接口编排与执行
├── billing-svc/      # 计费、套餐、余额
├── order-svc/        # 订单、支付回调
├── developer-svc/    # 开发者、应用、密钥
└── admin-web/        # 后台管理与商城

各模块职责清楚后，内部接口对外呈现为「可搜索、可下单、可调用」的商品。接下来按模块拆开讲。

三、关键实现逐段解析

1. 低代码接入与文档自动同步

内部接口一般不是直接对外暴露的，需要包一层做鉴权、参数映射和日志。用可视化编排把上游接口接入平台，写完自动生成 Swagger 文档，代码改动后文档同步更新，避免「接口改了文档没改」导致的调用失败。

一个编排节点配置示意

yaml 复制代码

node:
  name: score_query
  type: http
  upstream: http://inner-score-svc/score
  params:
    - uid: path
  auth: app_key

这里 auth 用 app_key 表示按应用鉴权，平台 gateway 会校验签名后再把请求转发给上游。这种方式的好处是内部接口无需改造，只通过配置就能对外开放。

自动生成 Swagger 后，外部开发者可以直接在文档页面试用，也能用 Swagger 的导出功能生成客户端代码。文档与代码同源，后续接口升级只需要改配置，文档会自动跟着变，省去了维护两套文档的成本。

2. 计费配置（示意结构）

在后台配置价格与套餐，平台据此自动生成接口商城、分类页、详情页与购买入口。

json 复制代码

{
  "apiCode": "score_query",
  "billingMode": "per_call",
  "price": 0.01,
  "packages": [
    { "name": "10万次包", "calls": 100000, "price": 800 }
  ]
}

billingMode 支持按次、按月、按流量包等多种方式。余额建议用「分」或定点数存储，避免浮点误差。计费规则里还可以叠加应用维度和接口维度的组合，比如「某个应用下所有接口共享一个总流量包」，或者「某个接口必须单独购买」。

前台商城会根据这些配置自动渲染购买入口，用户下单后余额扣减，调用时从余额里扣除对应次数。整个过程无需人工介入。

3. 支付与订单打通

支付宝、微信支付、余额支付已经集成。下单后平台处理回调、写订单、余额实时到账。开发者只需在后台做充值审核与对账，不用手动拉 Excel。

java 复制代码

// 伪代码：购买套餐后增加余额（示意）
orderService.create(theOrder);
if (payCallback.verified()) {
    balanceService.add(theOrder.getUserId(), theOrder.getPackageCalls());
}

回调一定要验签，余额变动与订单状态保持一致，对账才不会出错。实际生产环境中，支付回调通常来自多个渠道，每个渠道的验签逻辑和字段都不一样，平台把这部分封装后，业务侧只需要关注订单处理本身。

另外，订单表最好记录渠道流水号、支付时间和回调报文，方便后续对账和争议排查。

4. 开发者自助接入（SDK 调用）

外部开发者拿到密钥后，用多语言 SDK 调用。

不同团队的技术栈不同，提供 Java、PHP 等 SDK 能显著降低接入门槛。

python 复制代码

# Python SDK 调用示意
from yesapi import Client

c = Client(app_key="YOUR_KEY", secret="YOUR_SECRET")
resp = c.call("score_query", {"uid": 10086})
print(resp["data"])

SDK 内部负责签名、参数序列化和错误处理，开发者几行代码就能调通。app_key 用于标识应用，app_secret 用于签名，调用时不会在网络上传输，只有服务端持有。

接口响应建议统一结构，比如 { "code": 0, "data": {}, "message": "" }，并且把「余额不足」「调用超限」等错误码明确定义，方便 SDK 和调用方处理。

5. 限流与监控配置

按应用、按接口设配额，防止单个 key 被刷爆。调用统计和全量日志供运营对账。

yaml 复制代码

rate_limit:
  app_key: YOUR_KEY
  per_interface:
    score_query: 1000/min

限流阈值、告警线和统计报表都可以按接口维度配置。平台一般还会提供实时调用统计面板，显示每个接口的调用次数、成功失败比例、耗时分布和余额消耗。收入和健康度都能看得见。

全量调用日志也是必不可少的，用于排查「用户说我调了 1000 次但余额只扣了 800 次」这类争议。日志至少记录请求时间、应用 key、接口编码、请求参数摘要、响应状态、耗时和扣减次数。

6. 为什么建议用现成方案而不是从零自研

有人可能会问，这套链路自己能不能写？技术上当然可以，但实际成本不低。计费规则、支付回调、余额系统、开发者权限、接口限流、日志对账，每一块都需要时间打磨。两三个熟手做三到六个月，人力开支就是一笔不小的数字，更关键的是这半年里本该收的钱一直在漏。

YesApi Pro 把这部分底层能力封装好了，团队只需要把业务接口接进去，当天就能上线。对系统集成商和外包公司来说，还支持 源码交付 和 私有化部署，可以复用到多个甲方项目，摊薄成本，加快回款。

四、踩坑与优化

文档不同步 。务必用「代码与文档同源」的开发方式，否则外部调用三次报错就流失。平台自动生成 Swagger 就是解决这个问题的关键。
计费精度。金额用分或定点数存储，避免浮点累加误差。前台展示时再换算成元。
支付对账。回调必须验签，余额变动与订单状态要一致，财务对账才不出错。多渠道回调建议统一抽象成事件处理。
限流与授权。按应用、按接口做配额和角色授权，防止单个 key 被刷爆。同时要区分「免费试用额度」和「付费额度」的扣减顺序。
幂等。支付回调可能重复送达，订单与余额变更要做幂等处理，避免重复加款。通常以渠道流水号作为幂等键。
密钥安全 。app_secret 只在服务端签名时使用，前端只持 app_key，防止泄露后被冒用。另外建议支持 key 过期和重新生成。
私有化部署 。如果服务政企客户，数据不能出内网，平台支持 私有化部署 和 源码交付 就是刚需。把部署包放在客户服务器上，上午拿到包，当天就能上线。

五、小结

一个能收费的 API 开放平台，难的从来不是接口本身，而是计费、支付、开发者管理这套底层。用成熟方案把这部分封装好，团队只专注产生收入的数据和业务能力，最快当天就能跑起一个能收钱的 API 开放平台。

👉在线体验地址：

产品首页：pro.yesapi.cn/#java
用户端体验：java.test.yesapi.cn/

本文给出的目录结构、配置示例和伪代码都基于 YesApi Pro 实现思路整理，可作为实际项目的技术参考。实现时根据具体业务调整字段与接口即可。