Golang Gin 实战（二）| 简便的Restful API 实现

在RESTful API 设计规范中，有一部分是针对HTTP 方法动作的定义，规定了这些方法对于具体资源的操作方式，比如GET、POST这两个是我们常用的，除了他们，HTTP还定义了很多HTTP 方法。

HTTP Method

最开始的HTTP 0.9版本只有一个GET方法，也就是我们在浏览器中直接输入网址回车请求的方法，这是一个幂等方法，用于获取服务器上的资源。

在HTTP 1.0的时候又增加了HEAD和POST方法，其中常用的就是POST方法，一般用于我们给服务端提交一个资源，导致服务器的资源发生变化。

在HTTP1.1版本，也就是HTTP 1系列的最后一个版本中，也是我们当下比较常用的HTTP版本，增加了更多的HTTP 方法。比如OPTIONS, PUT, DELETE, TRACE和CONNECT，这样在HTTP 1.1 版本中，HTTP的方法达到了8个。

下面我们看下这些方法被赋予的意义。

GET

GET方法请求一个指定资源的表示形式. 使用GET的请求应该只被用于获取数据.

HEAD

HEAD方法请求一个与GET请求的响应相同的响应，但没有响应体.

POST

POST方法用于将实体提交到指定的资源，通常导致在服务器上的状态变化或副作用.

PUT

PUT方法用请求有效载荷替换目标资源的所有当前表示。

DELETE

DELETE方法删除指定的资源。

CONNECT

CONNECT方法建立一个到由目标资源标识的服务器的隧道。

OPTIONS

OPTIONS方法用于描述目标资源的通信选项。

TRACE

TRACE方法沿着到目标资源的路径执行一个消息环回测试。

PATCH

PATCH方法用于对资源应用部分修改。

以上摘自https://developer.mozilla.org/ 对于HTTP 请求方法的介绍。

通过以上的介绍，我们可以看到，其实HTTP的规范，对这些方法的用途都有了明确的定义，而我们使用的过程中，也尽可能的遵循这些定义，这样我们在开发中才可以更好的协作。对于以上请求方法，目前的大部分浏览器都支持。

RESTful API 规范

其实我们应该可以发现，我们开发的一个个Web应用服务或者程序，其实就是对服务器的资源的CRUD（创建、检索、更新和删除），所以 RESTful API 的规范建议我们使用特定的HTTP方法来对服务器上的资源进行操作。

在 RESTful API 中，使用的主要是以下五种HTTP方法：

1. GET，表示读取服务器上的资源
2. POST，表示在服务器上创建资源
3. PUT,表示更新或者替换服务器上的资源
4. DELETE，表示删除服务器上的资源
5. PATCH，表示更新/修改资源的一部分

这里我通过一些URL示例来更好的说明这些HTTP方法的使用。

HTTP GET https://www.flysnow.org/users
HTTP GET https://www.flysnow.org/users/123

以上是两个GET方法的示例，第一个表示获取所有用户的信息；第二个表示获取id为123用户的信息。

HTTP POST https://www.flysnow.org/users

这表示创建一个用户，会通过POST给服务器提供创建这个用户所需的全部信息。注意这里users是个复数

HTTP PUT https://www.flysnow.org/users/123

这表示要更新/替换id为123的这个用户，在更新的时候，会通过PUT提供更新这个用户需要的全部用户信息。这里PUT和POST不太一样的是，从URL上看，PUT操作的是单个资源，比如这里id为123的这个用户。

HTTP DELETE https://www.flysnow.org/users/123

删除非常简单，也是操作单个资源，这里是删除id为123的这个用户。

HTTP PATCH https://www.flysnow.org/users/123

PATCH也更新资源，它和PUT不一样的是，它只能更新这个资源的部分信息，而不是全部(这种也叫替换)，是部分更新。所以我们无需提供全部用户信息给服务器，需要更新哪些就提供哪些。

RESTful API 规范关于这部分HTTP方法的定义是非常好的，这让我们可以在编写API的时候更加规范，可读性强，便于协作。RESTful API规范这么好，对于我们强大的Golang Gin这个框架来说，自然不会忘记，Golang Gin为我们提供了一套非常简洁的接口，让我们可以很容易的实现RESTful API的规范。

Gin RESTful API 实现。

现在我们通过一个具体的Go代码示例，来演示如上我们所说的RESTful API定义的资源操作，但是这里的实现我们以演示Gin便捷的HTTP Method方法注册为主，会忽略很多具体业务逻辑的代码，并且不会严格的按照RESTful API的 Status Code 进行返回。

type User struct {
	ID   uint64
	Name string
}

首先我们定义一个用户User，用来表示我们需要操作的用户。

func main() {
	users := []User{{ID: 123, Name: "张三"}, {ID: 456, Name: "李四"}}
	r := gin.Default()
	r.GET("/users", func(c *gin.Context) {
		c.JSON(200, users)
	})
	r.Run(":8080")
}

这里我们通过GET方法就可以很容易的注册一HTTP GET请求的处理逻辑，这里是返回所有的用户信息，JSON的格式。

我们运行这段代码，在浏览器里打开http://localhost:8080/users,就可以看到如下信息：

[{"ID":123,"Name":"张三"},{"ID":456,"Name":"李四"}]

Gin不光为我们提供了快捷的GET方法，还有其他方法，可以很容易的让我们实现对应的HTTP Method方法注册。

	r.POST("/users", func(context *gin.Context) {
		//创建一个用户
	})
	r.DELETE("/usrs/123", func(context *gin.Context) {
		//删除ID为123的用户
	})
	r.PUT("/usrs/123", func(context *gin.Context) {
		//更新ID为123的用户
	})

	r.PATCH("/usrs/123", func(context *gin.Context) {
		//更新ID为123用户的部分信息
	})

此外还有不常用的HEAD、OPTIONS、TRACE、CONNECT等方法，从中可以看出，Gin的API非常友好，可以让我们很容易的使用相应的方法来注册我们对某个HTTP Method的处理。

有的朋友们可能会想，我这么一个个注册太麻烦了，比如想一次注册所有的HTTP Method的方法，有没有便捷的方式。别说，这个还真有。

// Any registers a route that matches all the HTTP methods.
// GET, POST, PUT, PATCH, HEAD, OPTIONS, DELETE, CONNECT, TRACE.
func (group *RouterGroup) Any(relativePath string, handlers ...HandlerFunc) IRoutes {
	group.handle("GET", relativePath, handlers)
	group.handle("POST", relativePath, handlers)
	group.handle("PUT", relativePath, handlers)
	group.handle("PATCH", relativePath, handlers)
	group.handle("HEAD", relativePath, handlers)
	group.handle("OPTIONS", relativePath, handlers)
	group.handle("DELETE", relativePath, handlers)
	group.handle("CONNECT", relativePath, handlers)
	group.handle("TRACE", relativePath, handlers)
	return group.returnObj()
}

Gin提供了Any方法，可以一次性注册以上这些HTTP Method方法。如果你只想注册其中某两个、或者三个方法，Gin就没有这样的便捷方法了，不过Gin为我们提供了通用的Handle方法，我们可以包装一下使用。

func Handle(r *gin.Engine, httpMethods []string, relativePath string, handlers ...gin.HandlerFunc) gin.IRoutes {
	var routes gin.IRoutes
	for _, httpMethod := range httpMethods {
		routes = r.Handle(httpMethod, relativePath, handlers...)
	}
	return routes
}

有了这个函数，我们就可以类似如下这样使用：

    Handle(r, []string{"GET", "POST"}, "/", func(c *gin.Context) {
		//同时注册GET、POST请求方法
	})

虽然这种方式比较便利，但是并不太推荐，因为他破坏了Resultful 规范中HTTP Method的约束。

小结

到这里这篇也就要结束了，在这篇中，虽然我们是在讲Gin的这些便捷的方法注册，但是我们也介绍了HTTP Method，Restful API规范，这样相信大家知道来龙去脉，可以对这些方法的使用更容易理解。

相信大家也看到了，如果对于这些请求的URL我们一个个去注册，比如张三用户和李四用户，分别注册一个对应的GET方法，是很繁琐的，所以Gin为我们提供了URL路由的模糊匹配，比如URL路径中的参数，下一篇我们再讲。

好了，到这里这篇就结束了，好看的话，点个赞吧，这是对我最大的支持了。