什么是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

---

类比解释

1. GET 是在图书馆借书：你获取了书（资源）的副本，书本身不会被修改。
2. POST 是买新书放进书架：你创建了一本新书，并把它放到指定位置。
3. PUT 是用新书换旧书：你替换了一本书的内容，但书的位置没有变。
4. 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 和版本控制

示例代码

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": "user@example.com"})
}

---

https://github.com/0voice