路由组功能

在实际项目开发中，均是模块化开发。同一模块的API接口一般会有相同的接口前缀。
例如，对于一个xx管理模块，会有“xx添加”、“xx删除”、“xx修改”、“xx查询”。
一个学生管理模块的API如下：

学生注册：/student/Add
学生删除：/student/Delete
学生修改：/student/Modify
学生查询：/student/Search

路由组

Gin框架为我们提供了路由组功能。

func group(engine *gin.Engine) {
    userGroup := engine.Group("/user")
    //visit /user/Add
    userGroup.POST("/Add", func(context *gin.Context) {
        fmt.Println("request route: ", context.FullPath())
        //业务处理逻辑
    })

    //visit /user/Delete/:id
    userGroup.POST("/Delete/:id", func(context *gin.Context) {
        fmt.Println("request route: ", context.FullPath())
        //业务处理逻辑
    })

    //visit /user/Modify/:id
    userGroup.POST("/Modify/:id", func(context *gin.Context) {
        fmt.Println("request route: ", context.FullPath())
        //业务处理逻辑
    })

    //visit /user/Search?id=
    userGroup.GET("/Search", func(context *gin.Context) {
        fmt.Println("request route: ", context.FullPath())
        //业务处理逻辑
    })
}

• func (group *RouterGroup) Group(relativePath string, handlers ...HandlerFunc) *RouterGroup：该函数用于定义一个group即一个公共的访问前缀。
  • relativePath string：相对路径，即公共前缀名。
  • handlers ...HandlerFunc：处理函数，由于是可变长度参数，故这里占时为空。

根据type RouterGroup struct的源码：

type RouterGroup struct {
    Handlers HandlersChain
    basePath string
    engine   *Engine
    root     bool
}

var _ IRouter = &RouterGroup{}

可以看到其实现了一个IRouter接口，该接口包含了GET、POST等方法，通过这些方法可以实现该路由组中的具体实现方法。

附：IRouter接口的声明

type IRoutes interface {
    Use(...HandlerFunc) IRoutes

    Handle(string, string, ...HandlerFunc) IRoutes
    Any(string, ...HandlerFunc) IRoutes
    GET(string, ...HandlerFunc) IRoutes
    POST(string, ...HandlerFunc) IRoutes
    DELETE(string, ...HandlerFunc) IRoutes
    PATCH(string, ...HandlerFunc) IRoutes
    PUT(string, ...HandlerFunc) IRoutes
    OPTIONS(string, ...HandlerFunc) IRoutes
    HEAD(string, ...HandlerFunc) IRoutes

    StaticFile(string, string) IRoutes
    Static(string, string) IRoutes
    StaticFS(string, http.FileSystem) IRoutes
}

完整的请求

一个完整的请求应该包含请求、处理请求和返回结果三个步骤，在服务器端对请求处理完成之后，应该将结果返回给客户端。

Gin框架中提供了一下返回请求的数据格式

[]byte 和 string

之前的实例中，我们都用[]byte来返回数据。

• func (ResponseWriter) Write([]byte) (int, error)：用于向接收端输出[]byte切片。该方法被定义于官方的http包中
• func (ResponseWriter) WriteString(string) (int, error)：用于向接收端输出string。该方法被定义在context包中

JSON

在项目开发中，JSON格式规范使用更为普遍。Gin框架直接支持将返回数据组装成JSON格式返回给客户端。

将map格式转换成JSON格式

func mapToJSON(engine *gin.Engine) {
    engine.GET("/mapToJSON", func(context *gin.Context) {
        fmt.Println("request route: ", context.FullPath())
        //向前端传回JSON数据
        context.JSON(200, map[string]interface{}{
            "code":    0,                                      //在开发过程中，自己定义的一个状态码。这里用0代表成功
            "message": "OK",                                   //返回的一个状态码
            "data":    "request route: " + context.FullPath(), //返回的内容
        })
    })
}

• func (c *Context) JSON(code int, obj interface{})：这个函数可以将map[string]interface{}类型的变量自动地转换成json数据，并返回给前端。其有两个参数，
  • 第一个code int表示返回的http状态码，可选200、300等状态码，或者直接使用golang提供的net/http包中的http.StatusOK（代表200状态码）等已经定义好的常量。
  • 第二个obj interface{}表示任意obj，这里可以是map[string]interface{}类型或者是struct类型（下一个示例）。

将struct格式转换为JSON格式

type Response struct {
    Code    int
    Message string
    Data    interface{}
}

func structToJSON(engine *gin.Engine) {
    engine.GET("/structToJSON", func(context *gin.Context) {
        fmt.Println("request route: ", context.FullPath())
        resp := Response{
            Code:    0,
            Message: "OK",
            Data:    "request route: " + context.FullPath(),
        }
        context.JSON(200, &resp)
    })
}

HTML

除了JSON格式以外，gin框架还支持返回HTML格式的数据。可以直接渲染HTML页面。

HTML模板传入

func returnHTML(engine *gin.Engine) {
    engine.GET("/returnHTML", func(context *gin.Context) {
        fmt.Println("request route: ", context.FullPath())
        //设置html文件目录的位置。设置过以后，这些html文件才能被engine访问
        engine.LoadHTMLGlob("./returnResultFormat/HTML/*")

        //设置静态文件目录（映射）
        engine.Static("/img","./returnResultFormat/image")

        //错误示范：context.HTML(http.StatusOK, "./returnResultFormat/HTML/index.html", nil) //直接这样加载会报错。
        context.HTML(http.StatusOK, "index.html", gin.H{
            "something":"这句话是由后端传入的",
        })
    })
}

• func (c *Context) HTML(code int, name string, obj interface{})：这个函数用于向前端返回一个HTML文档。被返回的HTML文档必须先由func (engine *Engine) LoadHTMLGlob(pattern string)函数定义html文件目录的位置，只有被定义过的内容才能被gin引擎访问。
  • 1. code int：返回的状态码
  • 2. name string：要加载的HTML模板名
  • 3. obj interface{}：要传入的模板信息，一般使用gin提供的结构type H map[string]interface{}（gin.H）传入。在前端的默认定义为{{.something}}。如果不需要传入信息，可以传入nil

设置HTML文件

• func (engine *Engine) LoadHTMLGlob(pattern string)：这个函数用于指定HTML模板的位置。只有设置过以后，这些html文件才能被engine访问。
  • pattern string HTML模板文件位置，这个位置可以相对于文件根目录指定。若想添加一个文件夹下所有的HTML文档，可以使用./path/*来传入。

设置静态资源的目录

• func (group *RouterGroup) Static(relativePath string, root string) IRoutes：这个函数用于指定静态文件（img等）的位置。只有设置过以后，才能被engine访问。通过这个函数指定的静态文件目录是映射关系
  • relativePath string 相对位置，指从前端页面访问该静态资源的位置。
  • root string 根目录位置，指engine引擎要从硬盘中的哪个位置找到该静态资源。注：这两个参数接受的都是文件夹路径，而非设置HTML文件处所代表的“文件”。所以无需在路径结尾添加*号。

附：前端HTML页面代码

<!DOCTYPE html>
<html lang="zh-cn">
<head>
    <meta charset="UTF-8">
    <title>Mona's Gin Test</title>
</head>
<body>
    <p>HTML页面已加载</p>
    <br>
    <p>{{.something}}</p>
    <p>上面的话是由模板系统传入</p>
    <p>下面这张图片是静态资源的用例</p>
    <img src="./img/74020281_p0.png">
</body>
</html>

附：项目路径树

$> tree /t ./
MONAGINWEB
    │
    └─returnResultFormat
        │  byteAndString.go
        │  cmd.go
        │  html.go
        │  json.go
        │
        ├─HTML
        │      index.html
        │
        └─image
                74020281_p0.png

请求参数绑定

在开发中，我们总会写username := context.PostForm("username")//解析POST类似的功能，每次只能实现对一个数据操作的方法。
Gin框架提供了实体绑定的功能，可以将表单数据与结构体绑定，从而达到简化上诉过程的方法。

用用户注册功能来实践表单实体绑定的操作：

type UserRegister struct{
    Username string `form:"username" binding:"required"`
    Password string `form:"password" binding:"required"`
    Phone    string `form:"phone" binding:"required"`
}

其中：
– form表示要与哪一个字段进行绑定
– binding表示该字段是否是一个必须字段（required代表必须）

GET、POST、POST JSON 数据绑定

将GET、POST、POST JSON数据绑定到服务器端的struct中。
以POST JSON为例：

//记住，struct里面必须是已导出的变量（其他位置可获取，否则err会提示成功，但无法成功绑定）
type jsonInfo struct {
    Name string `form:"Name"`
    Age  int    `form:"Age"`
    Sex  string `form:"Sex"`
}

func jsonBinder(engine *gin.Engine) {
    engine.POST("/JSONbinder", func(context *gin.Context) {
        fmt.Println("visit route: ", context.FullPath())
        var info jsonInfo//先创建一个变量以存储从前端获取到的数据
        //解析前端通过POST提交的JSON数据
        if err := context.BindJSON(&info); err != nil {//这里必须是引用上面创建的变量。
            log.Fatal(err.Error())
            return
        }
        fmt.Println("json bind successful, info: ", info.Name, info.Age, info.Sex)
        _, _ = context.Writer.Write([]byte("json bind successful, info:" + info.Name))
    })
}

• func (c *Context) BindJSON(obj interface{}) error：用于将获取到的JSON数据绑定到一个struct中。其中，obj interface{}是我们定义的object，该函数返回一个error。
• func (c *Context) ShouldBind(obj interface{}) error：用于绑定获取到的POST中的数据。
• func (c *Context) ShouldBindQuery(obj interface{}) error：用于绑定获取到的GET中的数据
• obj的定义参考上文定义的方法。

POST JSON使用的json用例：

{
"name":"The name",
"sex":"Girl",
"age":16
}

附：HTTP接口调试插件

平常开发者可能会使用一款叫做PostMan的软件，这个软件界面时全英文的，对国内用户可能不是很友好，而且还得下载软件。我接下来介绍的这款“插件”是一款Chrome插件，它可以实现API接口的调试。
CRAP-API 官网
Chrome 插件下载
以下是使用截图：