1. API 基础认知：什么是 API、工作原理与 RESTful 风格

说实话，我刚开始接触后端开发那会儿，对 API 的理解特别模糊。总觉得这东西很玄乎，像是两个系统之间在「隔空喊话」。后来做多了项目才明白——API 其实就是一套约定好的接口规则，让不同的软件能互相通信。

今天咱们就来聊聊 API 的基础。我会结合自己踩过的坑，帮你把这块彻底搞懂。

1.1 什么是 API？

API 的全称是 Application Programming Interface，翻译过来叫「应用程序编程接口」。说白了，它就是一个中间人。

你想想看，你点外卖的时候，不会直接跑去后厨找厨师吧？你通过外卖 App 下单，App 把订单传给餐厅，餐厅做好再通过 App 告诉你「饭好了」。这里的 App 就是 API——它帮你和餐厅（后端服务）沟通。

核心定义：API 是一组预定义的函数、协议和工具，用于构建软件应用。它定义了不同软件组件之间如何交互。

我在项目中遇到过不少新人，上来就问「API 到底长什么样？」其实很简单——API 就是一个 URL 地址。你往这个地址发请求，它给你返回数据。比如：

GET https://api.example.com/users/123

这条请求的意思是：帮我查一下用户 ID 为 123 的信息。服务器收到后，会返回一段 JSON 数据：

{
  "id": 123,
  "name": "张三",
  "email": "zhangsan@example.com"
}

嗯，就是这么直白。

1.2 API 的工作原理：请求-响应模型

API 的工作方式，本质上就是请求-响应模型。客户端发请求，服务端给响应。整个过程分四步：

  1. 客户端发起请求——比如你的前端页面、手机 App 或 Postman 工具
  2. 服务端接收并处理——后端程序解析请求，查数据库或做计算
  3. 服务端返回响应——把结果包装成 JSON/XML 格式发回来
  4. 客户端解析使用——前端拿到数据渲染页面，或 App 展示给用户

我习惯把这个过程比作「点菜」：你（客户端）看菜单（API 文档），告诉服务员（API 网关）要什么菜（请求参数），厨师（后端服务）做好后端上来（响应数据）。

个人经验：刚开始写 API 时，我总把逻辑全塞在一个接口里。后来发现这样维护起来特别痛苦。建议每个接口只做一件事，保持单一职责。

下面这张图能帮你更直观地理解整个过程：

客户端 （浏览器/App） API 网关 （接口层） 后端服务 （业务逻辑） ① 请求 ② 转发 ③ 响应 ④ 返回 数据库 读写 API 请求-响应模型工作流程 客户端 → API 网关 → 后端服务 → 数据库 → 逐层返回

1.3 RESTful API 设计风格简介

说到 API 设计，就绕不开 REST。REST 的全称是 Representational State Transfer，翻译过来叫「表现层状态转移」。名字听着挺唬人，其实核心思想就一句话：用 URL 表示资源，用 HTTP 方法表示操作。

我个人习惯把 RESTful API 的设计原则总结成三点：

  • 资源导向——每个 URL 代表一个资源，比如 /users 代表用户集合，/users/123 代表某个用户
  • 使用标准 HTTP 方法——GET 查、POST 增、PUT 改、DELETE 删
  • 无状态——每次请求都包含所有必要信息，服务端不保存客户端状态

我曾经踩过的坑：刚开始设计 API 时，我用 /getUser、/createUser 这种动词式 URL。后来被同事骂了一顿——RESTful 风格应该用名词，动词交给 HTTP 方法。正确的做法是 GET /users、POST /users。

来看一个对比表格，你就明白了：

操作 非 RESTful（错误） RESTful（正确）
查询用户列表 GET /getUsers GET /users
创建新用户 POST /createUser POST /users
更新用户信息 POST /updateUser?id=123 PUT /users/123
删除用户 GET /deleteUser?id=123 DELETE /users/123

你想想看，用动词式 URL 有什么问题？第一，它把操作写死在 URL 里，不够灵活；第二，不同开发者可能用不同的动词，团队协作时容易混乱。而 RESTful 风格统一了规范，大家一看就懂。

我的建议：刚开始学 RESTful 设计时，可以记住这个口诀——「名词复数做路径，HTTP 方法表动作，状态码来反馈结果」。比如 GET /users 返回 200，POST /users 返回 201，DELETE /users/123 返回 204。

另外，RESTful 还有一个重要原则——使用合适的 HTTP 状态码。我见过不少项目，不管成功失败都返回 200，然后在响应体里写 {"code": 0, "msg": "success"}。这样做其实违背了 HTTP 协议的本意。正确的做法是：

  • 200 OK —— 查询成功
  • 201 Created —— 创建成功
  • 204 No Content —— 删除成功
  • 400 Bad Request —— 参数错误
  • 404 Not Found —— 资源不存在
  • 500 Internal Server Error —— 服务器内部错误

嗯，这里要注意：状态码不是越多越好。我一般只用 6-8 个常用的，够用就行。搞太多反而增加沟通成本。

最后总结一下今天的内容：API 就是系统间的通信契约，请求-响应模型是它的核心工作方式，而 RESTful 风格是目前最主流的设计规范。掌握了这些基础，后面咱们讲工具调用和集成实战时，你就能更快上手了。

公众号:蓝海资料掘金营，微信deep3321

← 上一章 📖 返回目录 下一章 →