专栏首页飞雪无情的博客Golang Gin 实战(二)| 简便的Restful API 实现

Golang Gin 实战(二)| 简便的Restful API 实现

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

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用户的部分信息
	})

此外还有不常用的HEADOPTIONSTRACECONNECT等方法,从中可以看出,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路径中的参数,下一篇我们再讲。

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

本文参与腾讯云自媒体分享计划,欢迎正在阅读的你也加入,一起分享。

我来说两句

0 条评论
登录 后参与评论

相关文章

  • Golang Gin 实战(十二)| ProtoBuf 使用和源码分析原理实现

    ProtoBuf最近几年也算比较流行,它是一种语言无关,平台无关,并且可以扩展,并结构数据序列化的方法。相比JSON/XML这类文本格式的,ProtoBuf是二...

    飞雪无情
  • Golang Gin 实战(一)| 快速安装入门

    Gin 是一个非常优秀的Golang Web Framework,它不光API友好,性能也非常高,并且设计简洁,便于入门。所以它(Gin)非常受欢迎,在Gith...

    飞雪无情
  • Golang Gin 实战(五)| 接收数组和 Map

    在 上一篇 Golang Gin 实战(四)| URL查询参数的获取和原理分析 文章中,因为文章篇幅问题,QueryArray和QueryMap没有介绍,这篇文...

    飞雪无情
  • 【Go API 开发实战 5】基础1:启动一个最简单的 RESTful API 服务器

    要编写一个 RESTful 风格的 API 服务器,首先需要一个 RESTful Web 框架,笔者经过调研选择了 GitHub star 数最多的 Gin。采...

    腾讯技术工程官方号
  • Golang Gin 实战(三)| 路由参数

    在 上一篇 Golang Gin 实战(二)| 简便的Restful API 实现 文章中,我们留了一个疑问,假如我们有很多用户,我们要为他们一个个注册路由(路...

    飞雪无情
  • 如何构建交互式的RESTful API文档

    相信后端开发同学都写过API文档,如果你只开发API接口而不写文档会估计会被喷,而且写文档确实是个好习惯。但是写文档这个事确实挺痛苦的,之前我的做法是在内部开发...

    xiaojunzhou
  • Golang Gin 实战(十)| XML渲染

    虽然当前基于XML的API应用不多,但是Gin也提供了便捷的XML生成,可以把这些用于需要XML的地方,比如网站的sitemap,rss订阅的atom等。

    飞雪无情
  • Beego:简约 & 强大并存的 Go 应用框架

    Beego 是一个快速开发 Go 应用的 HTTP 框架,他可以用来快速开发 API、Web 及后端服务等各种应用,是一个 RESTful 的框架,主要设计灵感...

    yuanyi928
  • Golang Gin 实战(十一)| HTML模板渲染

    终于又到一个重头戏了。在整个服务端开发中,一个是API,一个就是网页,当前的API大部分都是通过JSON提供了,而网页就是通过HTML提供了。所以对于这么大的需...

    飞雪无情

扫码关注云+社区

领取腾讯云代金券