API 版本管理与安全基础：鉴权方式、限流与 HTTPS 必选

接口一旦上线，就会有别的程序在调用它。这时候你改一个字段名、换一种返回格式，所有老调用方可能全部报错。所以"上线后如何演进"和"如何防止被滥用"是接口设计的两个必修课。本文讲清版本管理、鉴权、限流和 HTTPS 这四件事。

一、为什么需要版本管理

软件在演进，接口也会变，但调用方不可能跟着你同步升级。版本管理就是给接口加一个"兼容层"：新旧版本同时存在，老用户继续用 v1，新功能放在 v2，大家各取所需，互不影响。

假设你的订单接口要从"整单返回"改成"分页返回"，直接改会让老调用方拿不到数据。正确的做法是发布一个 v2，让老调用方继续用 v1，等他们迁移完再下线 v1。迁移周期通常给 6-12 个月。

二、两种主流版本化方式

1. URL 路径版本化：把版本号写进路径，如 https://api.example.com/v2/orders。优点是直观、缓存友好，缺点是一个 URL 只能对应一个版本。这是绝大多数团队的首选。

2. Header 版本化：版本号放在请求头里，如 Accept: application/vnd.example.v2+json。优点是 URL 干净，缺点是难调试、难缓存，运维人员看不到版本信息。

两者对比：

对比项 URL 路径版本化 Header 版本化
可读性 高，一眼可见 低，藏在请求头里
缓存友好 是 否
使用难度 简单 较复杂
适用场景 多数团队默认选择 追求 URL 纯净的少数场景

无论哪种方式，核心原则都一样：v1 发布后不要删，只增不改，删除要提前公告。完整的接口设计规范可以参考RESTful API 设计最佳实践。

三、三种鉴权方式对比

接口不能谁都能调，需要证明"你是谁、有没有权限"。三种最常见的鉴权方式：

方式 原理 优点 缺点 适合场景
API Key 一串密钥随请求发送 实现简单、上手快 密钥易泄露、难单独吊销 内部工具、后端到后端
Basic Auth 用户名:密码做 Base64 编码 极简，浏览器原生支持 本质明文传输，必须配 HTTPS 临时调试
OAuth2 授权服务器发令牌（Token） 细粒度权限、可吊销、标准成熟 实现复杂、需要授权服务器 面向用户的第三方应用

关键提醒：API Key 和 Basic Auth 都不是为了"安全传输"设计的，密钥相当于明文的"钥匙"。它们必须配合 HTTPS 使用，否则钥匙等于挂在门口。需要面向最终用户的登录授权时，优先考虑 OAuth2，具体实现可看API 安全与 OAuth/JWT 指南，以及JWT 鉴权实现指南。

四、限流：给接口装上"水龙头"

限流（Rate Limiting）用来控制单位时间内的请求数量，防止单个调用方把服务器打垮，也是防止恶意刷接口最有效的手段之一。常见的实现是令牌桶：每秒往桶里放一定数量的"令牌"，每处理一个请求消耗一个令牌，桶空了就拒绝新请求。

一个典型配置：每用户每分钟 60 次请求（即每秒 1 次）。超过后接口返回 429 Too Many Requests，并在响应头里告知何时可以重试（如 Retry-After: 30）。合理的限流策略能显著降低被打垮的风险，也能控制成本。

五、HTTPS：API 的必选项

前面反复提到 HTTPS，它不是"建议"，而是"必选"。原因有三：一是防止数据在传输途中被偷看（比如密码、令牌、订单信息）；二是防止内容被篡改；三是很多浏览器和系统对非 HTTPS 接口会直接拦截。HTTPS 的原理和证书相关内容，可看HTTPS 入门。鉴权、限流、加密这些维度合在一起，才构成一个安全的接口，更多可以看网站安全加固指南。

六、常见问题（FAQ）

Q1：v1 到底什么时候可以下线？ 建议统计 v1 的调用量，连续 1-2 个月调用量接近零，并在官网公告至少 30 天后，再考虑下线。

Q2：API Key 泄露了怎么办？ 立刻在后台吊销并重新生成，同时检查访问日志确认泄露前有没有异常调用。所以密钥一定要放在服务端环境变量里，不要写进前端代码。

Q3：限流会不会误伤正常用户？ 会，所以阈值要留余量（建议按峰值调用量的 2-3 倍设置），并给调用方清晰的 429 提示和重试机制。

Q4：小项目也要 OAuth2 吗？ 不必。如果是你自己产品的两个服务之间调用，API Key + HTTPS 足够；只有当第三方要登录你的平台时才需要 OAuth2。

七、小结

一句话总结：接口版本化让旧用户不受影响，鉴权决定谁能进，限流防止被刷爆，HTTPS 保证传输安全。 四件事一起做，接口才敢放心对外。想继续学习后端对接相关内容，可收藏后端对接分类。