Gin 框架学习笔记(03)— 输出响应与渲染

Gin 框架中,对 HTTP 请求可以很方便有多种不同形式的响应。比如响应为 JSONXML 或者是 HTML 等。

Context 的以下方法在 Gin 框架中把内容序列化为不同类型写入到响应主体中。

// HTML 呈现指定文件名的 HTTP 模板。
// 更新 HTTP 状态代码并将 Content-Type设置为 “text/html”。
// 参见 http://golang.org/doc/articles/wiki/
func (c *Context) HTML(code int, name string, obj interface{})

// IndentedJSON 将给定结构序列化为漂亮的 JSON(缩进+结束行)到响应体中。
// 同时将 Content-Type设置为 “application/json”。
// 警告:建议仅将此用于开发目的,因为打印漂亮的 JSON 会占用更多 CPU 和带宽。
// 请改用 Context.JSON() 。
func (c *Context) IndentedJSON(code int, obj interface{})

// SecureJSON 将给定结构序列化为安全 JSON 到响应主体中。
// 如果给定的结构是数组值,则默认将 “while(1)” 添加到响应主体。
// 将 Content-Type设置为 “application/json” 。
func (c *Context) SecureJSON(code int, obj interface{})

// JSONP 将给定结构序列化为 JSON 到响应体中。
// 它可跨域向服务器请求数据。
// 将 Content-Type 设置为 “application/javascript” 。
func (c *Context) JSONP(code int, obj interface{})

// JSON 将给定结构序列化为 JSON 到响应主中。
// 将 Content-Type 设置为 “application/json” 。
func (c *Context) JSON(code int, obj interface{})

// AsciiJSON 将给定结构作为 JSON 序列化到响应体中,并将 Unicode 序列化为 ASCII 字符串。
// 将 Content-Type 设置为 “application/json” 。
func (c *Context) AsciiJSON(code int, obj interface{})

// PureJSON 将给定结构序列化为 JSON 到响应体中。
// 与 JSON 不同,PureJSON 不会用他们的 Unicode 实体替换特殊的 HTML 字符。
func (c *Context) PureJSON(code int, obj interface{})

// XML 将给定结构序列化为 XML 到响应体中。
// 将 Content-Type 设置为 “application/xml” 。
func (c *Context) XML(code int, obj interface{})

// YAML 将给定结构序列化为 YAML 到响应体中。
func (c *Context) YAML(code int, obj interface{})

// ProtoBuf 将给定结构序列化为 ProtoBuf 到响应体中。
func (c *Context) ProtoBuf(code int, obj interface{})

// String 将给定字符串写入到响应体中。
func (c *Context) String(code int, format string, values ...interface{})

// Redirect 将 HTTP 重定向返回到特定位置。
func (c *Context) Redirect(code int, location string)

// Data 将一些数据写入正文流并更新 HTTP 状态代码。
func (c *Context) Data(code int, contentType string, data []byte)

// DataFromReader 将指定的读取器写入正文流并更新 HTTP 代码。
func (c *Context) DataFromReader(code int, contentLength int64, contentType string, reader io.Reader, extraHeaders map[string]string)

// File 以有效的方式将指定的文件写入正文流。
func (c *Context) File(filepath string)

// FileAttachment 以有效的方式将指定的文件写入正文流中在客户端,
// 通常会使用给定的文件名下载该文件。
func (c *Context) FileAttachment(filepath, filename string)

// SSEvent 将 Server-Sent 事件写入正文流。
func (c *Context) SSEvent(name string, message interface{})

// Stream 发送流响应并返回布尔值,表示“客户端在流中间断开连接”。
func (c *Context) Stream(step func(w io.Writer) bool) bool

1. XML/JSON/YAML/ProtoBuf 响应

这些响应的方法可以把数据序列化为对应数据编码方式。

func main() {
    router := gin.Default()

    router.GET("/someJSON", func(c *gin.Context) {
        c.JSON(http.StatusOK, gin.H{"userinfo": "Mo", "status": http.StatusOK})
    })

    router.GET("/moreJSON", func(c *gin.Context) {
        // 也可使用一个结构体
        var msg struct {
            Name     string `json:"user"`
            UserInfo string
            Number   int
        }
        msg.Name = "Lena"
        msg.UserInfo = "Mo"
        msg.Number = 123
        // 注意 msg.Name 在 JSON 中变成了 "user"
        c.JSON(http.StatusOK, msg)
    })

    router.GET("/someXML", func(c *gin.Context) {
        c.XML(http.StatusOK, gin.H{"userinfo": "Mo", "status": http.StatusOK})
    })

    router.GET("/someYAML", func(c *gin.Context) {
        c.YAML(http.StatusOK, gin.H{"userinfo": "Mo", "status": http.StatusOK})
    })

    router.GET("/someProtoBuf", func(c *gin.Context) {
        name := "Lena"
        // protobuf 的具体定义写在 pb/user文件中。
        data := &pb.UserInfo{
            UserType: 101,
            UserName: name,
            UserInfo: "Mo",
        }
        // 将输出被 protobuf 序列化了的数据
        c.ProtoBuf(http.StatusOK, data)
    })

    // 监听并启动服务
    router.Run(":8080")
}

程序运行在 Debug 模式时,在命令行运行下面命令:

curl -v http://localhost:8080/someProtoBuf

命令行返回:

> GET /someProtoBuf HTTP/1.1
> Host: localhost:8080
> User-Agent: curl/7.47.0
> Accept: */*
>
< HTTP/1.1 200 OK
< Content-Type: application/x-protobuf
< Date: Sun, 14 Jul 2019 10:13:42 GMT
< Content-Length: 12
<

继续运行命令:

curl -v http://localhost:8080/someYAML

命令行返回:

> GET /someYAML HTTP/1.1
> Host: localhost:8080
> User-Agent: curl/7.47.0
> Accept: */*
>
< HTTP/1.1 200 OK
< Content-Type: application/x-yaml; charset=utf-8
< Date: Sun, 14 Jul 2019 10:13:45 GMT
< Content-Length: 25
<
status: 200
userinfo: Mo

继续保持程序运行,通过浏览器访问 http://localhost:8080/moreJSON ,页面显示:

{"user":"Lena","UserInfo":"Mo","Number":123} 

通过浏览器访问 http://localhost:8080/someJSON ,页面显示:

{"status":200,"userinfo":"Mo"}

通过浏览器访问 http://localhost:8080/someXML ,页面显示:

<map>
<userinfo>Mo</userinfo>
<status>200</status>
</map>

从以上命令行运行命令情况以及浏览器访问显示,以及控制台输出可以看到 Gin 框架可以根据需要,把内容序列化为不同 Content-Type 类型写入到响应体。

下面以 c.JSON() 方法为例,来说说这类方法实现渲染的过程,下面是 c.JSON() 方法的定义:

func (c *Context) JSON(code int, obj interface{}) {
    c.Render(code, render.JSON{Data: obj})
}

c.Render() 方法中,第二个参数是结构体对象 render.JSON{Data: obj} ,这个结构体定义在 render/json.go 文件中,并且这个结构体还有两个方法:

// Render (JSON) writes data with custom ContentType.
func (r JSON) Render(w http.ResponseWriter) (err error) {
    if err = WriteJSON(w, r.Data); err != nil {
        panic(err)
    }
    return
}

// WriteContentType (JSON) writes JSON ContentType.
func (r JSON) WriteContentType(w http.ResponseWriter) {
    writeContentType(w, jsonContentType)
}

这两个方法实现了在 render/render.go 中定义的接口:

type Render interface {
    // Render writes data with custom ContentType.
    Render(http.ResponseWriter) error
    // WriteContentType writes custom ContentType.
    WriteContentType(w http.ResponseWriter)
}

所以,程序可以通过 c.Render() 这个渲染的通用方法来适配不同的渲染器,因为其第二个参数对应着 render 目录下的众多渲染器,比如 JSONPHTML 等等。这些渲染器都实现了接口 Render ,所以都可以通过 c.Render() 方法来把渲染后的结果响应给客户端。

2. JSONP 响应

JSONP 可以向不同域的服务器跨域请求数据。如果查询参数存在回调,则将回调添加到响应体中。在 Gin 框架中,支持 JSONP 响应,下面分两部分来说明 Gin 框架中 JSONP 的使用。

服务端输出 JSONP

func main() {
    router := gin.Default()

    router.GET("/jsonp", func(c *gin.Context) {
        data := map[string]interface{}{
            "foo": "bar",
        }

        // callback 是 x
        // 将输出:x({\\"foo\\":\\"bar\\"})
        c.JSONP(http.StatusOK, data)
    })

    // 监听并启动服务
    router.Run(":8080")
}

客户端调用:

<div id="divJsonp"></div>
<script>
$.getJSON("<http://localhost:8080/jsonp?callback=?">, function(data) {
    var html = '<ul>';
    html += '<li>' + data["foo"] + '</li>';
    html += '</ul>';

    $('#divJsonp').html(html);
});
</script>

首先把服务端运行在 Debug 模式,为了模拟跨域,这里把客户端所在目录作为 Web 服务在 8081 端口运行起来。可在浏览器访问:http://localhost:8081/j.html ,页面显示:

  • bar

从控制台输出可以看到服务端正常接收了 jsonp 调用,且浏览器页面能正常展示服务端响应的内容。

3. SecureJSON 响应

SecureJSON() 方法将给定结构序列化为安全 JSON 到响应主体中。如果给定的结构是数组值,则默认将 while (1) 添加到响应主体。该响应方法会将 Content-Type 设置为 application/json 。使用 SecureJSON() 方法来防止 JSON劫持。

func main() {
    router := gin.Default()

    // 可以自定义添加安全 JSON 前缀
    // router.SecureJsonPrefix(")]}',\\n")

    router.GET("/someJSON", func(c *gin.Context) {
        names := []string{"lena", "austin", "foo"}

        // SecureJsonPrefix() 设置优先,
        // 否则将会输出:   while(1);["lena","austin","foo"]
        c.SecureJSON(http.StatusOK, names)
    })

    // 监听并启动服务
    router.Run(":8080")
}

运行程序,通过浏览器访问 http://localhost:8080/someJSON ,页面显示:

while(1);["lena","austin","foo"]

如自定义设置安全前缀 router.SecureJsonPrefix(")]}',\\n"),则页面显示:)]}', ["lena","austin","foo"]
这些添加前缀的方法对提升数据的读安全有较好的防护作用,在开发中建议要增强数据安全意识,避免不必要安全问题的发生。

4. AsciiJSON 响应

AsciiJSON() 方法将给定结构作为 JSON 序列化到响应体中,并将 Unicode 序列化为 ASCII 字符串。该响应方法会将 Content-Type 设置为 application/json

func main() {
    router := gin.Default()

    router.GET("/someJSON", func(c *gin.Context) {
        data := gin.H{
            "lang": "GO语言",
            "tag":  "<br>",
        }

        // 输出 : {"lang":"GO\\u8bed\\u8a00","tag":"\\u003cbr\\u003e"}
        c.AsciiJSON(http.StatusOK, data)
    })

    // 监听并启动服务
    router.Run(":8080")
}

运行程序,通过浏览器访问 http://localhost:8080/someJSON ,页面显示:

{"lang":"GO\\u8bed\\u8a00","tag":"\\u003cbr\\u003e"}

5. PureJSON 响应

PureJSON() 方法将给定结构序列化为 JSON 到响应体中。与 JSON 不同,PureJSON() 方法不会用 Unicode 实体替换特殊的 HTML 字符。

func main() {
    router := gin.Default()

    // Unicode 实体
    router.GET("/json", func(c *gin.Context) {
        c.JSON(200, gin.H{
            "html": "<b>Hello, world!</b>",
        })
    })

    // 纯字符标识
    router.GET("/purejson", func(c *gin.Context) {
        c.PureJSON(200, gin.H{
            "html": "<b>Hello, world!</b>",
        })
    })

    // 监听并启动服务
    router.Run(":8080")
}

运行程序,通过浏览器访问 http://localhost:8080/json ,页面显示:

{"html":"\\u003cb\\u003eHello, world!\\u003c/b\\u003e"}

访问 http://localhost:8080/purejson ,页面显示:

{"html":"<b>Hello, world!</b>"}

通过对比可以知道, JSON() 方法与 PureJSON() 方法的区别在于,

  • PureJSON() 不会对内容进行任何的编码转义处理
  • JSON() 以及 AsciiJSON() 方法都会对内容进行变码转义处理
  • SecureJSON() 方法甚至会额外添加其他内容。

但不管怎么,这些方法都有其使用场景,为开发人员提供了更多便利的选择。

6. DataFromReader 响应

DataFromReader() 方法将指定的读取器写入正文流并更新 HTTP 状态码。也就是从数据流读取数据后处理并更新 HTTP 状态码。

func main() {
    router := gin.Default()
    router.GET("/someDataFromReader", func(c *gin.Context) {
        response, err := http.Get("<https://raw.githubusercontent.com/gin-gonic/logo/master/color.png>")
        if err != nil || response.StatusCode != http.StatusOK {
            c.Status(http.StatusServiceUnavailable)
            return
        }

        reader := response.Body
        contentLength := response.ContentLength
        contentType := response.Header.Get("Content-Type")

        extraHeaders := map[string]string{

            // 做为附件下载保存
            // "Content-Disposition": `attachment; filename="gopher.png"`,

            // 直接在浏览器显示
            "Content-Type": "image/png",
        }

        c.DataFromReader(http.StatusOK, contentLength, contentType, reader, extraHeaders)
    })

    router.GET("/file", func(c *gin.Context) {
        // 输出当前目录 main.go 文件内容
        c.File("main.go")
    })

    router.GET("/attach", func(c *gin.Context) {
        // 下载当前目录 main.go 文件为 test-main.go
        c.FileAttachment("./main.go", "test-main.go")
    })

    router.Run(":8080")
}

运行程序,通过浏览器访问 http://localhost:8080/someDataFromReader ,程序会读取 https://raw.githubusercontent.com/gin-gonic/logo/master/color.png 这张图,然后在页面显示这张图,这个过程并不是 HTML 标签来完成,而是通过程序来读取图片数据然后设置 “Content-Type”: "image/png " 才呈现出来的。
在上面代码中,如果 extraHeaders 设置为第一种则会作为附件下载保存这张图片。可以这样理解这个方法:可以从任何 Reader 读取数据并按 extraHeaders 的配置来响应渲染内容。
而为了更多演示说明有关文件处理,可通过浏览器访问 http://localhost:8080/file ,会直接在浏览器中显示源文件代码,另外通过浏览器访问 http://localhost:8080/attach ,会在浏览器中下载保存源文件 main.go 为 test-main.go 文件。这两个方法 File() 和 FileAttachment() 不会经常使用,但比较有用。

7. Redirect 重定向

重定向也可以认为是响应的一种方式。这里列举了两种方式,一种是常见的 301 重定向,还有一种是其实是 GinHandler 重新指定,通过 HandleContex() 方法来重新调用其他的 Handler

func main() {
    router := gin.Default()

    // 直接重定向到外部站点
    router.GET("/re", func(c *gin.Context) {
        c.Redirect(http.StatusMovedPermanently, "http://www.baidu.com/")
    })

    // 间接重定向到内部 Handler
    router.GET("/handle", func(c *gin.Context) {
        c.Request.URL.Path = "/hi"
        router.HandleContext(c)
        c.JSON(200, gin.H{"Handler": "handle"})
    })

    router.GET("/hi", func(c *gin.Context) {
        c.JSON(200, gin.H{"hello": "world"})
    })

    // 监听并启动服务
    router.Run(":8080")
}

程序运行在 Debug 模式时,通过浏览器访问 http://localhost:8080/handle ,页面显示:

{"hello":"world"}
{"Handler":"handle"}

控制台输出:

[GIN-debug] GET /re --> main.main.func1 (3 handlers)
[GIN-debug] GET /handle --> main.main.func2 (3 handlers)
[GIN-debug] GET /hi --> main.main.func3 (3 handlers)
[GIN-debug] Listening and serving HTTP on :8080
[GIN] 2019/07/14 - 22:24:41 | 200 | 996.8µs | ::1 | GET /hi
[GIN] 2019/07/14 - 22:24:41 | 200 | 26.9291ms | ::1 | GET /handle

可以看到实际上执行了两个 Handler 处理程序,响应状态码为: 200 ,并不是真正的重定向,但可以通过 HandleContex() 方法在程序中实现 Handler 的嵌套调用。

程序运行继续运行,在命令行运行:

curl -v http://localhost:8080/re

命令行返回

> GET /re HTTP/1.1
> Host: localhost:8080
> User-Agent: curl/7.47.0
> Accept: */*
>
< HTTP/1.1 301 Moved Permanently
< Content-Type: text/html; charset=utf-8
< Location: <http://www.baidu.com/>
< Date: Sun, 14 Jul 2019 14:21:25 GMT
< Content-Length: 56
<
<a href="<http://www.baidu.com/>">Moved Permanently</a>.

返回的状态码为: 301 ,说明 Redirect() 方法实现了真正的重定向。而通过浏览器访问 http://localhost:8080/re ,将会重定向打开百度首页。

原文地址:https://gitbook.cn/gitchat/column/5dab061e7d66831b22aa0b44/topic/5dab09fd7d66831b22aa0b5e

评论
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包

打赏作者

wohu007

你的鼓励将是我创作的最大动力

¥1 ¥2 ¥4 ¥6 ¥10 ¥20
扫码支付:¥1
获取中
扫码支付

您的余额不足,请更换扫码支付或充值

打赏作者

实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值