API 管理
天气 API 运行稳定,但用户需求更多。
用户反馈
你们只有天气 API 吗?
需要新闻 API
需要股票查询 API
需要 IP 归属地查询
我决定扩展 API 种类:
第一阶段新增 API:
- 新闻 API - 获取热点新闻
- 股票 API - 查询股票行情
- IP 查询 API - 查询 IP 归属地
- 邮箱验证 API - 验证邮箱有效性
未来计划:
- 货币汇率 API
- 二维码生成 API
- 短链接 API
- 图片压缩 API
选型边界
为什么先做统一 API 管理模型
- 触发问题
- 新增多个 API 后,如果每个 API 都单独写鉴权、限流、缓存和数据源配置,维护成本会快速失控。
- 候选方案
- 每个 API 独立实现、统一配置表、自研 API 管理模型、直接接入成熟 API Gateway。
- 选择理由
- 当前平台还在快速试错,自研轻量模型能先统一元数据、权限、套餐和数据源配置,不必一开始引入重型网关。
- 代价
- 需要维护注册流程和配置校验;模型设计不当会让后续 API 接入受限。
- 暂不解决
- 暂不做完整 API Gateway 的插件体系、灰度发布和流量编排,先把多个 API 的基础管理统一起来。
数据库设计
统一管理模型最终要落在数据上。这一步先定表结构,后面注册机制、处理流程和文档生成都从这套元数据里读写。
| 字段名 | 类型 | 约束 / 说明 |
|---|---|---|
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 | 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 |
| 字段名 | 类型 | 约束 / 说明 |
|---|---|---|
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 |
API 注册机制
接入的 API 越多,越不能靠人记。注册机制就是把「这个接口是什么、归谁管、受什么限制」变成一份必须填的登记表,填不全就不许上线。这样后面每个 API 的处理逻辑才可能真正统一。
API 注册机制
- 步骤 1:定义统一的注册信息:接口标识、路由、请求参数与返回结构
- 步骤 2:登记所属数据源、缓存策略、超时时间与限流阈值
- 步骤 3:标注所需的权限范围和所属套餐,明确这条 API 归谁管
- 步骤 4:启动时校验注册信息是否完整,缺项就拒绝启动而不是留到运行时
关注点:新 API 接入时必须登记哪些元数据,以及缺项能否被拦住。
统一处理流程
这一节是整个 API 管理模型的心脏:鉴权、限流、缓存、数据源、序列化全都按注册表里的配置走。新增 API 不再写新的处理流程,只是往表里多添一行数据。
统一处理流程
- 步骤 1:先解析请求并校验 API Key,拿到用户身份与权限范围
- 步骤 2:再按注册的元数据执行限流、配额扣减与缓存查找
- 步骤 3:未命中缓存时调用对应的数据源适配器,拿到原始数据后做格式转换
- 步骤 4:把结果写回缓存、记录调用日志,再按注册的返回结构序列化输出
关注点:不同 API 共用同一条链路时,各环节的顺序与扩展点。
新闻 API
新闻是第一个接入统一模型的 API,它的特点是量大、更新快、列表维度多。把它跑通,后面股票、IP 的接入基本就是照着填注册表。
新闻 API
- 步骤 1:确定新闻数据源和返回结构,注册接口标识与所需的查询参数
- 步骤 2:按十分钟的更新节奏设置缓存 TTL,并配置对应的主动更新任务
- 步骤 3:把列表分页和筛选条件纳入缓存 key 的设计,避免命中率被稀释
- 步骤 4:为数据源配置超时和重试策略,外部抖动时不拖垮整个服务
关注点:新闻接口的时效要求、数据源选择与缓存参数。
股票 API
股票接口是四个新 API 里对新鲜度要求最高的,也因此最能检验缓存参数是不是按数据特征分档设置。五秒 TTL 加上主动刷新,是速度和上游压力之间的折中。
股票 API
- 步骤 1:注册行情接口的路由与股票代码参数,指定对应的数据源适配器
- 步骤 2:把缓存 TTL 设为五秒左右,并配置定时刷新任务让返回结果带上数据时间戳
- 步骤 3:为高频调用设置限流阈值,避免单个热门代码拖垮行情源
关注点:行情接口的新鲜度要求,以及缓存时间的取值。
IP 查询 API
IP 查询是四个接口里最简单的一个:数据几乎不变、来源稳定、不需要主动刷新。把它作为对照,能清楚地看出缓存参数随数据特征变化带来的收益。
IP 查询 API
- 步骤 1:注册 IP 查询接口的参数与返回字段,绑定 IP 库这类本地数据源
- 步骤 2:把缓存 TTL 设为二十四小时,标注静态属性并在 IP 库更新时批量失效
- 步骤 3:核对更新后新分配的 IP 能否查到归属地,确认批量失效已经生效
关注点:几乎不变的数据如何登记,以及长缓存带来的收益。
自动生成文档
文档最怕和实现脱节,接口一多就没人记得改。与其靠人维护,不如让文档直接从注册表生成——注册表是唯一事实来源,文档自然就不会过期。
自动生成文档
- 步骤 1:让文档生成器直接读取注册表里的接口元数据,不再手工维护文档
- 步骤 2:从参数定义生成请求示例,写明必填项、默认值与取值范围
- 步骤 3:按接口所属的权限范围过滤文档内容,外部用户看不到内部接口
- 步骤 4:把错误码与限流规则一并写进文档,减少调用方的试错成本
关注点:文档与实现是否同源,以及对外暴露的信息边界。
API 列表
接口列表是用户认识这个平台的入口,它既是目录也是权限边界的体现。把权限过滤放在列表这一步,用户就不会点到调不通的接口,也少一半的咨询。
API 列表
- 步骤 1:从注册表汇总所有已启用接口,输出接口标识、路径与一句话说明
- 步骤 2:按分类和标签分组,让用户能快速找到自己需要的接口
- 步骤 3:只展示当前用户权限范围内的接口,未授权的不出现在列表里
- 步骤 4:对列表接口本身做缓存,并定期刷新以反映新上线的接口
关注点:对外暴露的接口清单如何做到准确且不过度暴露。
用户请求
GET https://dashboard.kuaiyizhi.cn/api/v4/weather?city=北京Nginx 负载均衡
Nginx
Public API Gateway
Admin API
Admin Dashboard
MySQL
Redis 集群 + 哨兵
MySQL 分层集群
消息队列
离线数仓
发现内容有问题?
告诉我们哪里需要改进。
