1. API 基础概念与历史归纳总结
如果你问我，什么是学习 API 设计的第一道坎？
我的答案是：先把「API 到底是什么」这件事彻底搞清楚。
别笑，做了这么多年技术，我发现很多人挂在嘴上的 API，其实理解是模糊的。
我个人习惯把 API 看作「两个系统之间的合同」。
你提供什么输入，我承诺什么输出。
双方都按合同办事，谁也别耍赖。
1.1 概念拆解：从生活类比到技术真相
先举个生活例子。
你去餐厅吃饭。
菜单就是 API 文档。
你点菜（请求），后厨做菜（实现），服务员把菜端给你（响应）。
你不需要知道后厨怎么炒菜，后厨也不需要认识你。
这就是解耦。
回到技术世界，API 全称 Application Programming Interface。
说白了，就是应用程序对外暴露的一组「可调用的能力」。
它屏蔽了内部细节，只告诉调用方：你传什么参数，得到什么结果。
我记得有一次帮团队重构一个老系统。
业务方说：「我们想把订单服务拆出来，但所有调用方都直接连数据库了。」
这就是没有 API 层的结果——耦合到骨头里。
后来我们硬着头皮加了一层 RESTful 接口，花了三个月才割完肉。
1.2 历史发展：从 RPC 到 GraphQL
API 不是凭空冒出来的。
它走了很长一段路。
| 年代 | 风格 | 核心特点 | 痛点 |
|---|---|---|---|
| 1990s | XML-RPC / SOAP | 远程调用，强类型，WSDL 描述 | 过于厚重，解析慢，学习成本高 |
| 2000s | REST | 资源导向，HTTP 语义，轻量 JSON | 无状态约束，复杂查询困难 |
| 2015+ | GraphQL | 按需查询，单一端点，强类型 Schema | 缓存难，N+1 问题，服务端复杂度上移 |
你想想看，为什么 REST 能打败 SOAP？
因为 SOAP 协议里塞了太多无关信息。
一个简单的问候请求，SOAP 要包三层信封。
而 REST 直接用 HTTP 动词 + URI，干净利落。
1.3 API 的核心要素
不管什么风格的 API，下面这些东西是跑不掉的。
- 端点（Endpoint）：URL 路径，例如
/users/123 - 方法（Method）：GET / POST / PUT / DELETE / PATCH
- 请求头（Headers）：认证、内容类型、缓存控制
- 请求体（Body）：JSON 或表单数据
- 响应状态码（Status Code）：2xx 成功，4xx 客户端错误，5xx 服务端错误
- 版本控制（Versioning）：
/v1/users或Accept: application/vnd.example.v2+json
嗯，这里要注意一点。
很多新手会把状态码当摆设，永远返回 200。
我曾经在一个项目里接手过「全员 200」的 API。
业务异常靠响应体里的 code 字段区分。
结果客户端判断逻辑到处都是 if-else，调试起来像在猜谜。
1.4 解耦思想：API 设计的灵魂
有了 API 概念，下一步就是理解「为什么需要 API」。
答案就两个字：解耦。
解耦意味着服务可以独立部署、独立升级、独立扩展。
但解耦不是免费的。
你需要在 API 设计阶段就定好边界。
我一般这样判断解耦是否到位：
如果修改一个服务的内部逻辑，不需要通知其他团队修改调用代码，那就算解耦了。
否则，你的 API 本质上只是一层「漂亮的外壳」。
为什么这件事容易搞砸？
因为业务永远是贪婪的。
今天要加个字段，明天要改个行为。
如果 API 设计时没有预留扩展空间，后面就只能打补丁。
补丁多了，接口就变得像牛皮癣。
1.5 一张图读懂本章知识体系
1.6 小结
这一章我们走完了从概念到历史的快车道。
你理解了 API 到底是什么，也知道它经历了哪些阶段。
更重要的是，你明白了「解耦」才是 API 设计的终极目标。
不要小看这些基础知识。
我接手的许多混乱项目，根源就是团队在「什么是 API」上没对齐。
有人把 API 当数据库视图，有人把 API 当远程函数调用器。
只有大家对契约性质达成共识，后面才能谈设计模式、解耦策略。