一、API 基础概念
什么是 API？
API，全称是 Application Programming Interface（应用程序编程接口）。
说白了，它就是两个软件系统之间的「传话筒」。你想想看，我们写程序时，经常需要让 A 系统去拿 B 系统的数据。怎么拿？总不能直接连人家数据库吧？这时候 API 就派上用场了。
我个人习惯把 API 比作餐厅里的服务员。你（客户端）想吃什么（数据），不需要自己进厨房（服务器内部），只需要告诉服务员（API），他会帮你把菜端上来。嗯，这个比喻虽然老套，但确实贴切。
核心要点：API 是一套预先定义好的规则，让不同软件之间可以互相通信、交换数据。它隐藏了内部实现细节，只暴露必要的接口。
API 的工作原理
API 的工作流程其实很简单，就四个步骤：
- 客户端发起请求 —— 你的程序向 API 服务器发送一个请求
- 服务器处理请求 —— API 服务器收到请求后，开始干活
- 服务器返回响应 —— 处理完数据，打包成响应返回给客户端
- 客户端解析响应 —— 你的程序拿到数据，该干嘛干嘛
我在项目中遇到过不少新手，以为 API 调用就是「发个请求等结果」这么简单。其实中间还有认证、限流、缓存、重试机制等等。不过那是后话了，咱们先把基础打牢。
RESTful API 设计原则
REST（Representational State Transfer）是目前最主流的 API 设计风格。它不是标准，而是一套设计理念。我做了这么多年 API，发现遵循 REST 原则的接口，用起来就是顺手。
核心原则有这么几条：
| 原则 | 说明 | 举个例子 |
|---|---|---|
| 资源导向 | 把一切看作资源，用名词定义 URL | /users 表示用户资源 |
| 使用标准 HTTP 方法 | GET 查、POST 增、PUT 改、DELETE 删 | GET /users/123 获取用户 |
| 无状态 | 每次请求都包含所有必要信息 | 不依赖服务器保存会话 |
| 统一接口 | 所有资源使用相同的交互方式 | 一致的请求/响应格式 |
| 可缓存 | 响应应明确是否可缓存 | 使用 Cache-Control 头 |
我的小建议：设计 URL 时，用复数名词，比如 /orders 而不是 /order。层级关系用斜杠表示，比如 /users/123/orders。别用动词，比如 /getUser 这种就很不 RESTful。
API 的请求与响应结构
一个典型的 HTTP 请求长什么样？咱们直接看代码：
// 一个完整的 API 请求示例
POST /api/v1/users HTTP/1.1
Host: example.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
Content-Type: application/json
Accept: application/json
{
"name": "张三",
"email": "zhangsan@example.com",
"role": "developer"
}请求由四部分组成：
- 请求行 —— 方法 + URL + HTTP 版本
- 请求头 —— 元数据，比如认证信息、内容类型
- 空行 —— 分隔头部和正文
- 请求体 —— 实际要发送的数据（GET 请求没有）
对应的响应结构：
HTTP/1.1 201 Created
Content-Type: application/json
Location: /api/v1/users/42
{
"id": 42,
"name": "张三",
"email": "zhangsan@example.com",
"role": "developer",
"createdAt": "2025-01-15T08:30:00Z"
}曾经踩过的坑：我曾经在项目里把状态码用错了。创建资源用了 200 而不是 201，导致前端同事的缓存逻辑全乱了。记住：200 OK 是通用成功，201 Created 是创建成功，204 No Content 是删除成功。状态码别乱用，这是约定俗成的规矩。
常见的 HTTP 状态码，我整理了一张表：
| 分类 | 状态码 | 含义 | 使用场景 |
|---|---|---|---|
| 2xx 成功 | 200 | OK | 查询成功，返回数据 |
| 201 | Created | 创建资源成功 | |
| 204 | No Content | 删除成功，无返回体 | |
| 4xx 客户端错误 | 400 | Bad Request | 参数校验失败 |
| 401 | Unauthorized | 未认证或 token 过期 | |
| 404 | Not Found | 资源不存在 | |
| 5xx 服务端错误 | 500 | Internal Server Error | 服务器内部异常 |
| 503 | Service Unavailable | 服务暂时不可用 |
嗯，到这里 API 的基础概念就讲完了。你可能会问：「这些我都懂了，然后呢？」别急，下一章咱们会深入讲 API 的认证机制和实际调用技巧。不过在那之前，建议你把今天的内容消化一下，尤其是 RESTful 的设计原则，这玩意儿在面试里经常被问到。