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

HTTP Method

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

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

在HTTP1.1版本,也就是HTTP 1系列的最后一个版本中,也是我们当下比较常用的HTTP版本,增加了更多的HTTP 方法。比如OPTIONS, PUT, DELETE, TRACECONNECT,这样在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方法的示例,第一个表示获取所有用户的信息;第二个表示获取id123用户的信息。

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

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

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

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

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

删除非常简单,也是操作单个资源,这里是删除id123的这个用户。

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 进行返回。

1
2
3
4
type User struct {
	ID   uint64
	Name string
}

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

1
2
3
4
5
6
7
8
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方法注册。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
	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用户的部分信息
	})

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

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
// 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方法,我们可以包装一下使用。

1
2
3
4
5
6
7
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
}

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

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

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

小结

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

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

好了,到这里这篇就结束了,好看的话,点个赞吧,这是对我最大的支持了。更多关于Gin的讨论可以加入我的星球Golang Gin 实战,有更深入的讨论,一对一的答疑,公众号和博客没有的源代码分析。

扫码加入Golang Gin 实战星球

精彩文章推荐

Golang Gin 实战(一)| 快速安装入门

Go语言经典库使用分析(三)| Gorilla Handlers 详细介绍

为了答谢新老朋友的转发、阅读和点赞支持,我给大家包了个现金红包,关注我的公众号,即可参与抽奖。在看到50,下次抽奖增加金额!

本文为原创文章,转载注明出处,欢迎扫码关注公众号flysnow_org或者网站 https://www.flysnow.org/ ,第一时间看后续精彩文章。觉得好的话,请猛击文章右下角「在看」,感谢支持。

扫码关注