📚 课程目录第1章 API设计概述

1. API 设计概述

说到 API 设计，这玩意儿听起来挺唬人，其实说白了就是「两个系统怎么聊天」的一套规矩。你想想看，前端要拿数据，后端得给数据，中间没有一份明确的契约，那不乱套了吗？

我个人习惯在动手写代码之前，先把 API 的边界画清楚。接口设计得好，后面联调就顺；设计得含糊，你就等着被前后端来回拉扯吧。

API 的全称是 Application Programming Interface —— 应用程序编程接口。定义可以背，但理解更重要。我更喜欢把它比作一个「翻译官」：系统 A 想调用系统 B 的能力，不需要知道 B 内部怎么实现的，只要按 API 约定的格式发个请求就行。

接口的本质就三件事：输入、输出、规则。你传什么参数，它返回什么结构，中间走什么协议，这些写清楚，API 就立住了。

核心观点：API 是系统的边界，也是团队协作的契约。边界不清，代码必乱。

我记得刚入行那会儿，对接过一个第三方支付 API。文档写得含糊，字段含义靠猜，我硬是调了三天才跑通第一笔交易。那时候我就明白——API 设计好不好，直接影响对接效率。你省掉的文档功夫，最终都会变成别人的加班时间。

现在市面上主流的 API 风格有三类。我给你捋一捋，每种我都踩过坑。

REST 是目前最普及的风格，核心思想是「资源导向」。把业务实体抽象成资源，用 HTTP 方法表达操作：GET 查、POST 增、PUT 全量改、DELETE 删。我在项目里用 REST 最多，说实话，大部分场景它都够用。团队里新手也能快速上手，因为思路很直观。

GraphQL 是 Facebook 搞出来的查询语言。它最大的特点是「你要什么就给什么」，前端不再忍受过度获取或者获取不足。我之前有个项目从 REST 迁移到 GraphQL 之后，接口调用次数直接砍了一半。但代价是——服务端复杂度上去了，缓存策略也得重新设计。

gRPC 基于 HTTP/2 和 Protobuf，性能是真的猛。我曾在微服务场景下用 gRPC 替换 REST，延迟降了 40% 左右。不过调试起来比 REST 麻烦，工具链没那么成熟，浏览器端支持也有限。适合内部服务间通信，不适合直接暴露给浏览器。

三种风格没有的优劣，我通常这样选：

维度	REST	GraphQL	gRPC
数据格式	JSON / XML	JSON（查询语言）	Protobuf（二进制）
传输协议	HTTP/1.1 或 HTTP/2	HTTP/2	HTTP/2
学习成本	低	中	高
性能	中等	中等（查询解析有开销）	高（二进制 + 多路复用）
浏览器友好度	极高	高	低（需 gRPC-web）
典型场景	公开 API / CRUD	复杂查询 / 灵活前端	微服务间 RPC

我的建议：对外公开 API 首选 REST，内部服务优先考虑 gRPC，前端数据组合复杂的场景试试 GraphQL。别为了炫技选不合适的协议。

搞 API 设计，另一个绕不开的问题就是：到底让调用方等着，还是不等？

同步调用，就像你打电话——拨出去，对方接了，你说一句他回一句，全程保持连接。API 发出请求后，线程一直等到响应回来才往下走。逻辑简单，但调用方被「卡住」了。我在设计用户登录接口时用的就是同步，因为你需要立刻知道登录成功还是失败。

异步调用，就像发微信——你把消息发出去，不用等对方立马回复，他看到了自然会回你。API 发出请求后立刻返回一个「已收到」的凭证，后续通过回调、轮询或事件通知拿结果。我曾经在支付系统里处理支付确认，用的就是异步回调。用户付款后，系统异步通知商户，而不是让用户干等着。

避坑提醒：我曾经在一个项目里把不该异步的接口做成了异步——就是一个简单的用户信息查询，结果前端要多写一套轮询逻辑，反而更慢。同步和异步不是谁高级，而是看场景。需要实时响应的，别硬上异步。

说白了，选同步还是异步，就一个问题：调用方能接受等多久？ 100 毫秒内出结果的，同步搞定；超过 1 秒甚至更久的，考虑异步。

为了让你更直观地看明白本章的知识脉络，我画了一张结构图：

你看，整个知识体系分三层：先搞清楚 API 是什么，再选风格，最后定通信方式。每一步都影响最终的架构质量。API 设计没有银弹，理解这些基础概念，你就能在实际项目中做出更明智的选择。