API 基础概念：从定义到全生命周期管理
聊 API 之前，我先问个问题：你每天点外卖、刷短视频、用支付软件，背后有多少次 API 调用？我告诉你，光一个支付动作，可能就触发了十几二十次。说白了，API 就是软件之间的「翻译官」——它让不同的系统能互相说话。
我做了十几年 API 治理，见过太多因为基础概念没搞明白就翻车的项目。今天咱们就把 API 的定义、设计原则、版本管理和生命周期管理这几个核心概念掰开揉碎讲清楚。
一、API 到底是什么？
API，全称 Application Programming Interface，应用程序编程接口。别被这个高大上的名字唬住。你想想看，你去餐厅吃饭，菜单就是 API——你告诉服务员你要什么菜（请求），后厨做好端上来（响应）。你不需要知道后厨怎么炒菜，也不需要知道食材从哪里来。
API 干的就是这个事：
- 定义契约：请求长什么样，响应长什么样，白纸黑字写清楚
- 隐藏实现：调用方不需要关心内部逻辑
- 标准化交互：不管背后是 Java、Python 还是 Go，接口统一
核心要点：API 的本质是「约定大于实现」。接口一旦发布，就是你和调用方之间的合同。改接口？得双方同意。
我在项目中遇到过最典型的反面教材：某团队把数据库表结构直接暴露成 API，字段名用拼音缩写。结果前端改一次需求，后端就得改接口，两边天天吵架。嗯，这就是没搞懂 API 的「契约」本质。
二、RESTful API 设计原则
REST 不是一种技术，是一套设计风格。全称 Representational State Transfer，表现层状态转化。听着绕口？我换个说法：把资源当成名词，用 HTTP 动词当操作。
我习惯把 RESTful 设计拆成 6 条铁律：
| 原则 | 说明 | 反面案例 |
|---|---|---|
| 资源导向 | URL 只表示资源，不表示操作 | /getUser?id=1 ❌ |
| HTTP 动词语义化 | GET 查、POST 增、PUT 全量改、PATCH 部分改、DELETE 删 | POST /deleteUser ❌ |
| 无状态 | 每次请求携带全部信息，服务端不存会话 | 依赖 Session 做认证 ❌ |
| 统一接口 | 所有资源遵循相同的交互模式 | 有的返回 JSON，有的返回 XML ❌ |
| 分层系统 | 客户端不知道直接连的是网关还是后端 | 客户端硬编码后端地址 ❌ |
| 可缓存 | 利用 HTTP 缓存机制减少请求 | 所有响应都设 Cache-Control: no-cache ❌ |
来看一个实际例子。假设我们要设计用户资源的 API：
# 好的设计
GET /users # 获取用户列表
GET /users/{id} # 获取单个用户
POST /users # 创建用户
PUT /users/{id} # 全量更新用户
PATCH /users/{id} # 部分更新用户
DELETE /users/{id} # 删除用户
# 糟糕的设计
GET /getUserList # 动词在 URL 里
POST /createUser # 动词在 URL 里
POST /updateUser # 动词在 URL 里
GET /deleteUser?id=1 # 用 GET 做删除我的经验：URL 里只用名词复数形式，不要出现动词。如果实在需要「激活」「停用」这类操作，用 PATCH 修改状态字段，别搞 POST /activateUser 这种设计。
三、API 版本管理策略
版本管理是个老大难问题。我曾经接手过一个项目，API 没有版本号，前端直接调 /api/user。后来后端改了字段名，前端没同步，线上炸了整整 40 分钟。从那以后，我定了一条死规矩：API 必须带版本号，没有例外。
常见的版本管理策略有三种：
| 策略 | 实现方式 | 优点 | 缺点 |
|---|---|---|---|
| URL 路径 | /v1/users、/v2/users |
直观、容易路由 | URL 变长、版本扩散 |
| 请求头 | Accept: application/vnd.myapp.v1+json |
URL 干净、灵活 | 调试不方便、文档要求高 |
| 查询参数 | /users?version=1 |
实现简单 | 容易被忽略、缓存混乱 |
我个人习惯用 URL 路径方式。为什么？因为一眼就能看出来版本号，运维排查问题的时候不用翻请求头。但要注意：版本号不要用 v1.1 这种小版本号，API 版本只应该在大版本变更时递增。
避坑指南：我曾经见过一个团队，API 版本号跟业务版本号绑定，业务发版一次 API 版本就升一次。结果一年下来 API 版本到了 v47，调用方根本不知道用哪个。记住：API 版本只在你做了不兼容的变更时才升级。
什么算不兼容的变更？
- 删除或重命名字段
- 改变字段类型（比如 string 改成 int）
- 修改请求/响应结构
- 改变认证方式
什么算兼容的变更？
- 新增字段（客户端忽略即可）
- 新增可选参数
- 扩展枚举值
- 提升性能或增加缓存
四、API 生命周期管理
API 不是写完就完事的。它跟人一样，有出生、成长、衰老和死亡的过程。我把它分成 6 个阶段：
每个阶段都有它的「坑」。我挑几个重点说说：
规划阶段
别一上来就写代码。先搞清楚：谁在用这个 API？用来干什么？数据从哪里来？我曾经见过一个项目，API 做完了才发现没有数据源，最后只能从 Excel 里导数据，性能惨不忍睹。
设计阶段
这个阶段最重要。我习惯先写 API 文档再写代码——文档就是契约。用 OpenAPI 规范（以前叫 Swagger）把接口定义好，让前后端并行开发。设计时要考虑：
- 字段命名用 snake_case 还是 camelCase？统一就行
- 分页怎么设计？
?page=1&size=20还是?offset=0&limit=20 - 错误码怎么定义？别用 HTTP 状态码当业务错误码
我的习惯：错误响应统一用 { "code": 10001, "message": "用户不存在", "detail": "..." } 这种结构。code 是业务错误码，message 是人可读的提示，detail 是调试信息。HTTP 状态码只表示请求是否成功到达服务器。
发布与运维
发布不是把代码部署上去就完事了。要灰度发布——先让 5% 的流量走新版本，观察 24 小时没问题再全量。运维阶段要有监控：
- QPS（每秒请求数）
- 响应时间 P99（99% 的请求在多少毫秒内完成）
- 错误率
- 慢查询日志
退役阶段
这个阶段最容易被忽略。API 不用了，不能直接关服务器。要提前通知调用方，给至少 3-6 个月的迁移窗口期。我见过最离谱的事：某公司直接下线了一个老 API，结果调用方是银行的核心系统，导致对账失败，赔了不少钱。
避坑指南：退役 API 时，先在响应头加 Deprecation: true 和 Sunset: Sat, 31 Dec 2024 23:59:59 GMT，让调用方提前感知。等到了截止日期，返回 410 Gone 而不是 404 Not Found——这样调用方知道是 API 被废弃了，而不是地址写错了。
好了，API 的基础概念就聊到这儿。记住三句话：API 是契约，REST 是风格，版本和生命周期是治理的命根子。后面我们会一步步深入，把这些概念落地成真正的工程实践。