API 管理

场景

天气 API 运行稳定,但用户需求更多。

用户原声汇总

用户反馈

  • 你们只有天气 API 吗?

  • 需要新闻 API

  • 需要股票查询 API

  • 需要 IP 归属地查询

决策

我决定扩展 API 种类:

第一阶段新增 API:

  1. 新闻 API - 获取热点新闻
  2. 股票 API - 查询股票行情
  3. IP 查询 API - 查询 IP 归属地
  4. 邮箱验证 API - 验证邮箱有效性

未来计划:

  • 货币汇率 API
  • 二维码生成 API
  • 短链接 API
  • 图片压缩 API

选型边界

为什么先做统一 API 管理模型

触发问题
新增多个 API 后,如果每个 API 都单独写鉴权、限流、缓存和数据源配置,维护成本会快速失控。
候选方案
每个 API 独立实现、统一配置表、自研 API 管理模型、直接接入成熟 API Gateway。
选择理由
当前平台还在快速试错,自研轻量模型能先统一元数据、权限、套餐和数据源配置,不必一开始引入重型网关。
代价
需要维护注册流程和配置校验;模型设计不当会让后续 API 接入受限。
暂不解决
暂不做完整 API Gateway 的插件体系、灰度发布和流量编排,先把多个 API 的基础管理统一起来。

API 管理系统设计

数据库设计

统一管理模型最终要落在数据上。这一步先定表结构,后面注册机制、处理流程和文档生成都从这套元数据里读写。

api_definitionsFields
字段名类型约束 / 说明
idINTPRIMARY KEY, AUTO_INCREMENT
nameVARCHAR(100)UNIQUE, NOT NULL
display_nameVARCHAR(100)NOT NULL
endpointVARCHAR(255)NOT NULL
methodVARCHAR(10)DEFAULT 'GET'
categoryVARCHAR(50)weather/news/finance/tools
external_api_urlVARCHAR(255)上游服务地址
requires_authBOOLEANDEFAULT TRUE
cache_ttlINT缓存时间(秒)
rate_limit_factorINTDEFAULT 1
statusVARCHAR(20)active/deprecated/maintenance
is_publicBOOLEANDEFAULT TRUE
created_atTIMESTAMPDEFAULT CURRENT_TIMESTAMP
updated_atTIMESTAMPON UPDATE CURRENT_TIMESTAMP
api_definitionsRows
idnamedisplay_namecategorymethodcache_ttlstatus
1weather天气查询weatherGET3600active
2news新闻快讯newsGET300active
3stock股票行情financeGET60maintenance

统一 API 管理模型

API 注册机制

接入的 API 越多,越不能靠人记。注册机制就是把「这个接口是什么、归谁管、受什么限制」变成一份必须填的登记表,填不全就不许上线。这样后面每个 API 的处理逻辑才可能真正统一。

设计流程

API 注册机制

  1. 步骤 1:定义统一的注册信息:接口标识、路由、请求参数与返回结构
  2. 步骤 2:登记所属数据源、缓存策略、超时时间与限流阈值
  3. 步骤 3:标注所需的权限范围和所属套餐,明确这条 API 归谁管
  4. 步骤 4:启动时校验注册信息是否完整,缺项就拒绝启动而不是留到运行时

关注点:新 API 接入时必须登记哪些元数据,以及缺项能否被拦住。

统一处理流程

这一节是整个 API 管理模型的心脏:鉴权、限流、缓存、数据源、序列化全都按注册表里的配置走。新增 API 不再写新的处理流程,只是往表里多添一行数据。

设计流程

统一处理流程

  1. 步骤 1:先解析请求并校验 API Key,拿到用户身份与权限范围
  2. 步骤 2:再按注册的元数据执行限流、配额扣减与缓存查找
  3. 步骤 3:未命中缓存时调用对应的数据源适配器,拿到原始数据后做格式转换
  4. 步骤 4:把结果写回缓存、记录调用日志,再按注册的返回结构序列化输出

关注点:不同 API 共用同一条链路时,各环节的顺序与扩展点。

新增 API 接入流程

新闻 API

新闻是第一个接入统一模型的 API,它的特点是量大、更新快、列表维度多。把它跑通,后面股票、IP 的接入基本就是照着填注册表。

设计流程

新闻 API

  1. 步骤 1:确定新闻数据源和返回结构,注册接口标识与所需的查询参数
  2. 步骤 2:按十分钟的更新节奏设置缓存 TTL,并配置对应的主动更新任务
  3. 步骤 3:把列表分页和筛选条件纳入缓存 key 的设计,避免命中率被稀释
  4. 步骤 4:为数据源配置超时和重试策略,外部抖动时不拖垮整个服务

关注点:新闻接口的时效要求、数据源选择与缓存参数。

股票 API

股票接口是四个新 API 里对新鲜度要求最高的,也因此最能检验缓存参数是不是按数据特征分档设置。五秒 TTL 加上主动刷新,是速度和上游压力之间的折中。

设计流程

股票 API

  1. 步骤 1:注册行情接口的路由与股票代码参数,指定对应的数据源适配器
  2. 步骤 2:把缓存 TTL 设为五秒左右,并配置定时刷新任务让返回结果带上数据时间戳
  3. 步骤 3:为高频调用设置限流阈值,避免单个热门代码拖垮行情源

关注点:行情接口的新鲜度要求,以及缓存时间的取值。

IP 查询 API

IP 查询是四个接口里最简单的一个:数据几乎不变、来源稳定、不需要主动刷新。把它作为对照,能清楚地看出缓存参数随数据特征变化带来的收益。

设计流程

IP 查询 API

  1. 步骤 1:注册 IP 查询接口的参数与返回字段,绑定 IP 库这类本地数据源
  2. 步骤 2:把缓存 TTL 设为二十四小时,标注静态属性并在 IP 库更新时批量失效
  3. 步骤 3:核对更新后新分配的 IP 能否查到归属地,确认批量失效已经生效

关注点:几乎不变的数据如何登记,以及长缓存带来的收益。

API 文档

自动生成文档

文档最怕和实现脱节,接口一多就没人记得改。与其靠人维护,不如让文档直接从注册表生成——注册表是唯一事实来源,文档自然就不会过期。

设计流程

自动生成文档

  1. 步骤 1:让文档生成器直接读取注册表里的接口元数据,不再手工维护文档
  2. 步骤 2:从参数定义生成请求示例,写明必填项、默认值与取值范围
  3. 步骤 3:按接口所属的权限范围过滤文档内容,外部用户看不到内部接口
  4. 步骤 4:把错误码与限流规则一并写进文档,减少调用方的试错成本

关注点:文档与实现是否同源,以及对外暴露的信息边界。

API 列表

接口列表是用户认识这个平台的入口,它既是目录也是权限边界的体现。把权限过滤放在列表这一步,用户就不会点到调不通的接口,也少一半的咨询。

设计流程

API 列表

  1. 步骤 1:从注册表汇总所有已启用接口,输出接口标识、路径与一句话说明
  2. 步骤 2:按分类和标签分组,让用户能快速找到自己需要的接口
  3. 步骤 3:只展示当前用户权限范围内的接口,未授权的不出现在列表里
  4. 步骤 4:对列表接口本身做缓存,并定期刷新以反映新上线的接口

关注点:对外暴露的接口清单如何做到准确且不过度暴露。

当前架构

技术架构
客户端

用户请求

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

Nginx 负载均衡

应用服务

Nginx

Python

Public API Gateway

Admin API

Static

Admin Dashboard


MySQL

Redis 集群 + 哨兵

外部服务

MySQL 分层集群

消息队列

离线数仓

发现内容有问题?

告诉我们哪里需要改进。