API 基础概念与通信结构详解
应用程序编程接口（API）是软件系统之间交互的桥梁，尤其在现代分布式架构中扮演核心角色。REST 作为主流设计风格，因其简洁性和可扩展性被广泛采用。
核心概念解析
REST 架构要素：
- 资源： 系统中的实体对象，如用户、订单、文章等。
- 表现形式： 数据序列化格式，常用 JSON、XML 或二进制流。
- 状态转移： 通过 HTTP 方法触发资源状态变更，如 GET 查询、POST 创建、PUT 更新、DELETE 删除。
六项架构约束： 客户端-服务端分离、无状态通信、可缓存响应、统一接口、分层系统、支持按需代码（可选）。
API 类型对比
- REST API： 同一 URI 支持多种操作，依赖标准 HTTP 动词表达意图。
- 非 REST API： 操作语义隐含在路径或参数中，常仅用 GET/POST 实现所有功能。
- RESTful API： 严格遵循 REST 原则，强调资源标识清晰、操作幂等、状态无依赖。
为何选择 REST？
相比早期 SOAP 协议（基于 XML、重量级、强类型），REST 更轻量、灵活，支持多数据格式，适合 Web 和移动端快速迭代。虽安全性不如 SOAP 内建机制，但可通过 HTTPS、JWT 等方案弥补。
请求结构剖析
1. 请求地址（URL）
基础格式：https://domain.com/api/entity
带参示例：https://api.site.com/books?author=鲁迅&limit=10
2. 请求方法
- GET：读取资源
- POST：创建资源
- PUT：完整替换资源
- PATCH：局部更新资源
- DELETE：移除资源
3. 请求头（Headers）
关键字段示例：
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json
Accept: application/json
4. 请求体（Body）
用于携带数据，常见于 POST/PUT/PATCH：
{
"title": "朝花夕拾",
"author": "鲁迅",
"year": 1928
}
响应结构组成
1. 状态码
- 200 OK —— 成功返回数据
- 201 Created —— 资源创建成功
- 400 Bad Request —— 客户端参数错误
- 401 Unauthorized —— 缺少有效凭证
- 404 Not Found —— 资源不存在
- 500 Internal Server Error —— 服务端异常
2. 响应头
示例：
Content-Type: application/json
Content-Length: 204
Set-Cookie: session_id=abc123; Path=/; HttpOnly
3. 响应体
成功示例：
{
"id": 7,
"title": "呐喊",
"author": "鲁迅",
"published": 1923
}
失败示例：
{
"code": "ERR_INVALID_TOKEN",
"detail": "Token 已过期或签名无效"
}
完整交互示例
查询资源（GET）
GET /api/books/7
Authorization: Bearer xxx
Accept: application/json
→ 200 OK
{
"id": 7,
"title": "彷徨",
"author": "鲁迅"
}
创建资源（POST）
POST /api/books
Content-Type: application/json
{
"title": "野草",
"author": "鲁迅"
}
→ 201 Created
Location: /api/books/8
{
"id": 8,
"title": "野草",
"author": "鲁迅"
}
局部更新（PATCH）
PATCH /api/books/7
Content-Type: application/json
{
"title": "故事新编"
}
→ 200 OK
{
"id": 7,
"title": "故事新编",
"author": "鲁迅"
}
删除资源（DELETE）
DELETE /api/books/7
→ 204 No Content
关键要点总结
- 请求四要素： URL + Method + Headers + Body（视情况）
- 响应三部分： Status Code + Headers + Body（视情况）
- 前后端通过 JSON 格式交换数据，前端使用 fetch 或 axios 发起调用，后端使用 Express、Django、Spring Boot 等框架处理逻辑。
