什么是RESTful API？
RESTful API 是一种基于 REST 架构风格 的接口设计方法，常用于前后端通信。REST 的全称是 Representational State Transfer（表现层状态转移），它基于 HTTP 协议，遵循以下原则：
1. 资源的表现层
- 每个资源使用唯一的 URL 表示。例如：
- 获取用户信息：
GET /users/123 - 获取文章列表：
GET /articles - 资源使用 HTTP 方法来操作：
GET：读取资源POST：创建资源PUT：更新资源DELETE：删除资源
2. 无状态性
- 每个请求都独立，不依赖上下文。例如，客户端每次请求必须携带身份验证信息。
3. 结构化数据
- 数据格式通常为 JSON 或 XML，但 JSON 是最流行的选择。
HTTP 方法讲解
HTTP 方法是 RESTful API 的核心，常见的四种方法分别是 GET 、POST 、PUT 和 DELETE，它们对应的是操作资源的不同动作。
1. GET：读取资源
- 作用：获取资源的内容或状态。
- 特点：
- 安全性：不会修改服务器数据。
- 幂等性：多次请求返回结果相同。
- 例子：
- 获取用户详情：
GET /users/123 - 获取文章列表：
GET /articles - 表格演示：
| 请求 URL | 描述 | 响应数据 |
|---|---|---|
GET /users/1 |
获取 ID 为 1 的用户 | { "id": 1, "name": "Alice", "email": "..." } |
2. POST：创建资源
- 作用：在服务器上新建一个资源。
- 特点：
- 非幂等性：同一请求可能创建多个相同的资源。
- 例子：
- 创建用户：
POST /users - 创建订单：
POST /orders - 表格演示：
| 请求 URL | 请求体（JSON） | 响应数据 |
|---|---|---|
POST /users |
{ "name": "Alice", "email": "..." } |
{ "id": 1, "name": "Alice", "email": "..." } |
3. PUT：更新资源
- 作用：更新资源的全部内容。
- 特点：
- 幂等性：多次请求结果一致。
- 例子：
- 更新用户信息：
PUT /users/123 - 表格演示：
| 请求 URL | 请求体（JSON） | 响应数据 |
|---|---|---|
PUT /users/1 |
{ "name": "Bob", "email": "..." } |
{ "id": 1, "name": "Bob", "email": "..." } |
4. DELETE：删除资源
- 作用：删除服务器上的资源。
- 特点：
- 幂等性：重复删除操作返回结果一致（资源不存在）。
- 例子：
- 删除用户：
DELETE /users/123 - 表格演示：
| 请求 URL | 描述 | 响应数据 |
|---|---|---|
DELETE /users/1 |
删除 ID 为 1 的用户 | { "message": "User deleted" } |
总结表格：HTTP 方法对比
| 方法 | 作用 | 是否幂等 | 请求体 | 示例 URL |
|---|---|---|---|---|
GET |
读取资源 | 是 | 无 | GET /users/123 |
POST |
创建资源 | 否 | 包含新建数据 | POST /users |
PUT |
更新资源 | 是 | 包含资源完整信息 | PUT /users/123 |
DELETE |
删除资源 | 是 | 无 | DELETE /users/123 |
类比解释
- GET 是在图书馆借书：你获取了书（资源）的副本，书本身不会被修改。
- POST 是买新书放进书架：你创建了一本新书，并把它放到指定位置。
- PUT 是用新书换旧书：你替换了一本书的内容，但书的位置没有变。
- DELETE 是扔掉书：你将书从书架中移除。
API 版本控制
API 版本控制是保证接口稳定性和向后兼容的重要策略。当接口发生变更时，使用版本号区分不同接口，避免影响已有用户。
常用的版本控制方式
| 方式 | 描述 | 示例 |
|---|---|---|
| URL 版本控制 | 在 URL 中添加版本号（最常见方式） | GET /v1/users/123 |
| 请求头版本控制 | 在请求头中加入版本信息 | Header: X-API-Version: 1 |
| 查询参数控制 | 在查询参数中添加版本号 | GET /users/123?version=1 |
| 域名控制 | 通过不同的子域名区分版本（较少使用） | https://v1.api.example.com |
网络相关知识补充
1. HTTP 与 HTTPS
- HTTP 是 RESTful API 传输数据的基础协议。
- HTTPS 是 HTTP 的安全版本，增加了数据加密（SSL/TLS），确保通信的安全性。
2. 状态码
RESTful API 通常返回以下状态码：
| 状态码 | 含义 | 说明 |
|---|---|---|
200 |
OK | 请求成功，返回数据 |
201 |
Created | 创建资源成功 |
400 |
Bad Request | 请求参数错误 |
401 |
Unauthorized | 身份验证失败 |
404 |
Not Found | 资源未找到 |
500 |
Internal Server Error | 服务器内部错误 |
3. 幂等性
- 幂等性是指多次相同的请求，结果不变：
GET、PUT、DELETE应是幂等的。POST通常不是幂等的。
简单用 Gin 实现 RESTful API 和版本控制
示例代码
go
package main
import (
"github.com/gin-gonic/gin"
)
func main() {
r := gin.Default()
// v1版本组
v1 := r.Group("/v1")
{
v1.GET("/users/:id", getUserV1)
}
// v2版本组
v2 := r.Group("/v2")
{
v2.GET("/users/:id", getUserV2)
}
r.Run(":8080")
}
func getUserV1(c *gin.Context) {
id := c.Param("id")
c.JSON(200, gin.H{"version": "v1", "id": id, "name": "User V1"})
}
func getUserV2(c *gin.Context) {
id := c.Param("id")
c.JSON(200, gin.H{"version": "v2", "id": id, "name": "User V2", "email": "[email protected]"})
}