1.4 API 设计与交互

1.4 API 设计与交互

本节摘要：前后端靠 API（接口）通信。本节讲清 API 是什么、RESTful 设计原则（资源、方法、状态码）、请求与响应的数据格式（JSON），以及一次完整的交互流程——这是第 2-4 章所有框架练习的核心。

阅读收获

阅读完本节，你应当能够：

1. 解释 API 的作用
2. 掌握 RESTful 设计原则
3. 理解 HTTP 方法与状态码
4. 看懂 JSON 数据格式
5. 复述一次完整交互

一、问题与直觉

"前端怎么拿到数据？"——靠 API。把 API 想成餐厅的"菜单 + 上菜规矩"：菜单写清有什么菜（资源），规矩写清怎么点（方法）。前端照菜单点菜（请求 API），后厨按规矩上菜（返回数据）。API 就是前后端之间的"约定"。

二、核心原理

2.1 RESTful 设计原则

• 资源：用 URL 表示（如 /users）
• 方法：用 HTTP 方法表动作（GET 读、POST 增、PUT 改、DELETE 删）
• 状态码：用标准码表结果（200、404、500）

2.2 交互流程

三、工程实践要点

3.1 HTTP 方法速查

3.2 常见状态码

💡 关键直觉：API 设计先定"资源"，再定"方法"——想清楚有哪些资源（用户、订单），每个资源支持哪些操作，接口就清楚了。

3.3 测试 API 的工具

浏览器：GET 直测
Postman/API 工具：全方法测试
curl：命令行测试
​

⚠️ 常见坑：忽略状态码。接口"没报错"不等于"成功"——先看状态码再信数据，是调试 API 的第一习惯。

本节速览

• 要点一：API 是前后端的约定
• 要点二：RESTful 三要素——资源、方法、状态码
• 要点三：JSON 是通用的数据语言
• 要点四：流程——请求、路由、查询、响应
• 要点五：先定资源再定方法
• 要点六：先看状态码再信数据

通用基础打完了，第 2 章开始第一个框架——Spring Boot。

常见疑问

Q1：RESTful 到底在讲什么？

讲的是"用资源的方式组织接口"。核心三条：资源用名词表示（用户就是 /users，不要写 /getUser）；动作用 HTTP 方法表示（GET 读、POST 增、PUT 改、DELETE 删）；结果用状态码表示（200 成功、404 没找到、500 出错）。遵守这套约定，接口对使用者来说就像一套统一语法——看到一个 URL 和方法，就能猜出它的用途。

Q2：GET 和 POST 的区别只有"获取"和"提交"吗？

还有几个关键差异要记住：GET 参数放在 URL 里（可见、有长度限制、会被记录在日志和浏览器历史），POST 参数放在请求体里（不可见、可传大数据、不会被缓存）。所以敏感数据（密码）绝不能放 GET 的 URL 里。另外，从语义上 GET 应该是"只读不改变数据"的，POST 会创建数据——虽然技术上后端可以实现成别的样子，但设计接口时应该遵守这个约定。

Q3：状态码 200、400、404、500 分别代表什么？

200 表示成功；400 表示请求本身有问题（比如参数缺失、格式错误），是"你给错了"；404 表示资源不存在；500 表示服务器内部出错，是"我这边炸了"。区分它们的意义在于：状态码是接口的"体检报告"，前端根据它决定怎么提示用户。如果所有情况都返回 200，错误就被藏起来了，排查问题会非常困难。

Q4：JSON 为什么成了前后端通用的数据格式？

因为它简单、易读、跨语言。JSON 就是"键值对 + 数组"的嵌套组合，几乎所有编程语言都有现成的解析库。后端返回 JSON，前端拿到直接变对象用，不用做复杂的格式转换。相比 XML 它更轻，相比自定义格式它更标准。所以三个框架返回数据，默认都是 JSON。

工程实践要点

动手建议：找任何一个公开 API 或用 Postman 发一个真实请求，把"方法 + 地址 + 状态码 + 响应体"四样东西记录一次。你马上会发现，接口的响应体绝大多数就是 JSON，状态码也符合本节讲的约定。这一步的真实体验，会让你在学第 2-4 章写接口时，立刻明白自己写的东西前端会怎么用。

实战演练：设计一套接口

把本节知识落地的第一步，是设计一套完整的接口方案。假设你要做一个"图书管理"系统，前端需要一个图书列表页和一个新增图书的表单，请按下述思路设计：

首先列资源清单。核心资源是"图书"，可以叫 books。围绕它还有可能需要的资源：分类（categories）、借阅记录（borrows）。本练习先聚焦 books 一个资源。

接着为每个资源定义操作方法。图书要有哪些操作？查列表、查单个、新增、修改、删除——五件套。对应的 RESTful 写法是：查列表用 GET 指向 /books；查单个用 GET 指向 /books/1 这种带 id 的路径；新增用 POST 指向 /books；修改用 PUT 指向 /books/1；删除用 DELETE 指向 /books/1。把这张"操作与接口对照表"写出来，你的接口骨架就成型了。

然后定义数据格式。图书的数据至少包含：书名、作者、分类、价格、库存。前后端约定用 JSON 交换，字段名统一为英文小写（title、author、category、price、stock）。这步要写清楚：请求里传什么、响应里返什么，字段缺一不可。

最后定义错误约定。约定：找不到图书返回 404；参数缺失返回 400；服务器异常返回 500。响应体统一格式：成功时直接返回数据，失败时返回一个包含错误信息的对象。

这套设计做完，你就有了一份可以直接实现成代码的接口文档。第 2-4 章写接口时，就是把这份设计翻译成三个框架各自的语法。你会发现，虽然三个框架写法差异很大，但"接口长什么样"完全由这份设计决定——这正说明 API 设计在框架之前、并且独立于框架。

一句话记忆

RESTful 接口的套路是固定的：先定资源，再定方法，再定数据格式，最后定错误约定。设计先行，实现只是翻译。能独立设计一套接口的人，已经抓住了后端开发的骨架。