RESTful风格

RESTful风格

RESTful 风格是一种软件架构风格，它定义了一组约束和原则，用于创建Web服务。REST（Representational State Transfer，表述性状态转移），目的是描述一组架构原则，以实现软件系统的可伸缩性。RESTful Web服务遵循这些原则，使得它们具有无状态、可缓存、统一接口等特点。

RESTful 架构的六个基本原则

客户端-服务器（Client-Server）：客户端和服务器之间的分离，它们通过定义良好的API进行通信。

无状态（Stateless）：每个请求从客户端到服务器必须包含理解请求所需的所有信息，服务器不会存储任何请求的状态。

可缓存（Cacheable）：服务器必须明确表示响应是否可缓存，以及如何缓存。

统一接口（Uniform Interface）：为了简化和解耦架构，接口需要是统一的。RESTful架构通过使用标准的HTTP方法（如GET、POST、PUT、DELETE等）来实现这一点。

分层系统（Layered System）：客户端通常不能直接和最终的服务器通信，而是可能通过中间服务器进行通信，这些中间服务器可以提供额外的功能，如认证、负载均衡等。

按需代码（Code on Demand，可选）：服务器可以临时扩展或定制客户端的功能，通过发送可执行代码给客户端（例如，JavaScript脚本）。

RESTful API的设计

在设计RESTful API时，通常遵循以下最佳实践：

使用URI表示资源：每个资源都应该有一个唯一的URI，例如/users/1表示ID为1的用户资源。
使用HTTP方法表示操作：使用标准的HTTP方法来执行对资源的操作，例如使用GET获取资源，POST创建资源，PUT更新资源，DELETE删除资源。
使用HTTP状态码表示操作结果：使用状态码（如200 OK, 201 Created, 404 Not Found等）来表示操作的结果。
使用MIME类型（Media Types）：在请求和响应中明确指定内容类型，如json，xml等。
支持条件请求：通过HTTP头（如If-Modified-Since）支持条件GET请求，以减少不必要的数据传输。
错误处理:在出现错误时，服务器应返回适当的状态码和错误信息。

RESTful API示例

以下是一个简单的RESTful API示例，使用Gin框架创建一个用户资源的Web服务：

package main

import (
	"net/http"

	"github.com/gin-gonic/gin"
)
type User struct{
	ID int `json:"id"`
	Name string 	`json:"name"`
}
func main() {
	r := gin.Default()
	// 用户资源合集
	users:=[]User{
		{ID:1,Name:"Alice"},
		{ID:2,Name:"Tom"},

	}
	// 获取所有用户
	r.GET("/users",func(c *gin.Context){
		c.JSON(http.StatusOK,users)
	}
)
	// 获取单个用户
	r.GET("/users/:id",func(c *gin.Context){
		id:=c.Param("id")
		for _, user := range users {
			if user.ID==id{
				c.JSON(http.StatusOK,user)
				return
			}
		}
		c.JSON(http.statusNotFound,gin.H{
			"message":"user not found"
		})
	})
	// 创建新用户
	r.POST("/users",func(c *gin.Context){
		var user User
		if err:=c.ShouldBindJSON(&user);err !=nil{
			c.JSON(http.StatusBadRequest,gin.H{
				"message":err.Error()

			})
			return
		}
		users=append(users, user)
		c.JSON(http.StatusCreated,user)

	})

	// 更新用户
	r.PUT("/users/:id",func(c *gin.Context){
		id:=c.Param("id")
		for i,user := range users {
			if user.ID==id{
				if err:=c.ShouldBindJSON(&user);err!=nil{
					c.JSON(http.StatusBadRequest,gin.H{
						"message":err.Error()
					})
					return
				}
				user[i]=user
				c.JSON(http.StatusOK,user)
				return
			}
		}
		c.JSON(http.StatusNotFound,gin.H{"message":"User not found"})
	})
// 删除用户
r.DELETE("/users/:id",func(c *gin.Context){
	id:c.Param("id")
	for i,user:=range users{
		if user.ID==id{
			users=append(users[:i],users[:i-1]... )
			c.JSON(http.StatusOK,gin.H{
				"message":"user deleted"

			})
			return
		}
	}
	c.JSON(http.StatusNotFound,gin.H{"message":"user not found"})
})

r.Run(":8080")

}

RESTful请求方法

RESTful API 使用标准的 HTTP 请求方法（如 GET、POST、PUT、DELETE）来对资源进行操作，并通过 URL 标识资源。

序号	方法	描述
1	GET （select）	请求指定的页面信息，并返回实体主体。
2	POST（create）	向指定资源提交数据进行处理请求（例如提交表单或者上传文件）。数据被包含在请求体中。POST 请求可能会导致新的资源的建立和/或已有资源的修改。
3	PUT（update）	在服务器更新资源（更新完整资源）从客户端向服务器传送的数据取代指定的文档的内容。
4	DELETED	请求服务器删除指定的页面。
5	PATCH	是对 PUT 方法的补充，用来对已知资源进行局部更新 。

状态码

HTTP状态码是由服务器在HTTP响应中返回的三位数字代码，用于表示对客户端请求的处理结果。状态码分为五个不同的类别，每个类别有其特定的含义：

1xx（信息性状态码）：表示接收的请求正在处理。

100 Continue：客户端应继续其请求。
101 Switching Protocols：服务器已理解请求并请求客户端切换协议。

2xx（成功状态码）：表示请求正常处理完毕。

200 OK：请求成功，服务器返回了请求的资源。
201 Created：请求成功，并且服务器创建了新的资源。
202 Accepted：服务器已接受请求，但尚未处理。
204 No Content：服务器成功处理了请求，但没有返回任何内容。

3xx（重定向状态码）：需要后续操作以完成请求。

301 Moved Permanently：请求的资源已永久移动到新位置。
302 Found（旧称“Moved Temporarily”）：请求的资源现在临时从不同的URI响应请求。
304 Not Modified：自从上次请求后，请求的资源未修改过。

4xx（客户端错误状态码）：表示请求包含语法错误或无法完成。

400 Bad Request：服务器不理解请求的语法。
401 Unauthorized：请求要求身份验证。
403 Forbidden：服务器拒绝请求。
404 Not Found：服务器找不到请求的资源。
405 Method Not Allowed：不允许使用请求行中指定的方法。

5xx（服务器错误状态码）：服务器在处理请求的过程中发生了错误。

500 Internal Server Error：服务器遇到错误，无法完成请求。
501 Not Implemented：服务器不具备完成请求的功能。
502 Bad Gateway：服务器作为网关或代理，从上游服务器收到无效响应。
503 Service Unavailable：服务器暂时不可用（超载或停机维护）。
504 Gateway Timeout：服务器作为网关或代理，但是没有及时从上游服务器收到请求。