主要特点

gows是一款方便易用的Go语言websocket库，gows使用简单，能够支持大量客户端连接。具体特征如下：

• 采用更加经济的内存分配机制，使得每台服务器可接入更多的客户端。
• 内置消息接收循环，简化了消息的接收以及处理。
• 支持permessage-deflate压缩，支持设置压缩阈值，只有大于阈值的消息才会压缩发送。
• 支持Close handshake，可以优雅地关闭websocket连接。
• 支持并发消息发送。

安装

go get github.com/haming123/wego/gows

快速上手

• 注册页面路由，启动web服务

package main
import (
  "github.com/haming123/wego/gows"
  "html/template"
  "net/http"
)
func main() {
  http.HandleFunc("/ws", HandlerWebSocket)
  http.HandleFunc("/index", func(w http.ResponseWriter, r *http.Request) {
    user := r.FormValue("user")
    t, _ := template.ParseFiles("./index.html")
    t.Execute(w, user)
  })
  http.ListenAndServe(":8080", nil)
}

其中：

1）/index是一个web页面，在该页面中连接websocket，发送并接收websocket消息。

2）在/ws页面中进行websocket握手并升级为websocket协议。

• 定义websocket连接对应的结构体

  在进行websocket握手前需要首先实现一个代表websocket连接的结构体，该结构体用于websocket事件的处理。该结构体需要实现以下接口方法：

OnClose(ws *WebSocket)
OnMessage(ws *WebSocket, opcode int, buff *ByteBuffer) error

当接收的消息时会调用OnMessage方法，消息的数据可以从buff中获取。websocket连接关闭时会调用OnClose方法。

type Client struct {
    ws   *gows.WebSocket
    user string
}

func (c *Client) OnClose(ws *gows.WebSocket) {
    log.Printf("OnClose: %s\n", c.user)
    c.ws = nil
}

func (c *Client) OnMessage(ws *gows.WebSocket, opcode int, vbuff *gows.ByteBuffer) error {
    log.Println("收到消息：", vbuff.GetString())
    c.ws.WriteString(vbuff.GetString())
    return nil
}

• 实现websocket握手处理器函数，将http连接升级为websocket连接

func HandlerWebSocket(w http.ResponseWriter, r *http.Request) {
    user := r.FormValue("user")
    ws, err := gows.Accept(w, r, nil, nil)
    if err != nil {
        http.Error(w, err.Error(), http.StatusInternalServerError)
        return
    }
    client := &Client{ws: ws, user: user}
    ws.Serve(client)
}

其中的Client结构体代表客户端链接，必须实现OnMessage方法以及OnClose方法。创建Client对象后调用ws.Serve来启动消息接收循环。

使用wego的web框架实现webSocket握手

func HandlerWebSocket(c *wego.WebContext) {
    user := c.Param.MustString("user")
    ws, err := c.AcceptWebsocket(nil, nil)
    if err != nil {
        c.AbortWithError(500, err)
        return
    }
    client := &Client{ws: ws, user: user}
    ws.Serve(client)
}

发送消息

• 发送文本消息

  若要发送文本格式的消息，请调用WriteText或WriteString函数：

func (ws *WebSocket) WriteText(data []byte) error {
    ......
}
func (ws *WebSocket) WriteString(data string) error {
    ......
}

• 若要发送二进制消息，使用WriteBinary方法

func (ws *WebSocket) WriteBinary(data []byte) error {
    ......
}

• 发送JSON数据

type Book struct {
    Name  string
    Price float64
}

err := ws.WriteJSON(Book{"Golang", 30.2})
if err != nil {
    log.Error(err)
    return
}

• 通过WriteCloser接口发送消息

writer := ws.NextWriter(gows.Frame_Text)
defer writer.Close()

_, err := writer.WriteString("hello")
if err != nil {
    log.Error(err)
    return
}

_, err := writer.WriteString(" world")
if err != nil {
    log.Error(err)
    return
}

启用消息压缩处理

package main
import (
	"github.com/haming123/wego/gows"
	"html/template"
	"net/http"
)
func main() {
	//开启发送压缩
	gows.UseFlate()
	//设置压缩的阈值，只有大于阈值的消息才会被压缩
	gows.SetMinCompressSize(512)
	http.HandleFunc("/ws", HandlerWebSocket)
	http.HandleFunc("/index", func(w http.ResponseWriter, r *http.Request) {
		user := r.FormValue("user")
		t, _ := template.ParseFiles("./index.html")
		t.Execute(w, user)
	})
	http.ListenAndServe(":8080", nil)
}

跨域处理函数

gows缺省不支持跨域访问，若需要开启跨域访问，则需要自定义跨域处理函数（通过：SetOriginCheckFunc来设置）。例如:

package main
import (
	"github.com/haming123/wego/gows"
	"html/template"
	"net/http"
)
func main() {
	//允许跨域访问
	gows.SetOriginCheckFunc(func(r *http.Request) bool {
		return true
	})
	http.HandleFunc("/ws", HandlerWebSocket)
	http.HandleFunc("/index", func(w http.ResponseWriter, r *http.Request) {
		user := r.FormValue("user")
		t, _ := template.ParseFiles("./index.html")
		t.Execute(w, user)
	})
	http.ListenAndServe(":8080", nil)
}

关闭客户端链接

关闭websocket时需要进行关闭协商：接任一端想关闭websocket，就发一个close frame给对端，对端收到该frame后，若之前没有发过close frame，则必须回复一个close frame。

采用协商方式关闭websocket连接，请调用CloseHandshake方法：

func (ws *WebSocket) CloseHandshake(code CloseCode, text string) error {
......
}

CloseHandshake方法中的code参数为webSocket关闭状态码。webSocket关闭状态码的列表如下所示：

const (
//正常关闭; 无论为何目的而创建, 该链接都已成功完成任务.
CloseNormalClosure CloseCode = 1000
//终端离开：可能因为服务端错误, 也可能因为浏览器正从打开连接的页面跳转离开.
CloseGoingAway CloseCode = 1001
//协议错误：由于协议错误而中断连接.
CloseProtocolError CloseCode = 1002
//数据格式错误：由于接收到不允许的数据类型而断开连接
CloseUnsupportedData CloseCode = 1003
//保留
CloseReserved CloseCode = 1004
//没有收到预期的状态码.
CloseNoCloseRcvd CloseCode = 1005
//异常关闭：用于期望收到状态码时连接非正常关闭 (也就是说, 没有发送关闭帧).
CloseAbnormalClosure CloseCode = 1006
//由于收到了格式不符的数据而断开连接 (如文本消息中包含了非 UTF-8 数据).
CloseInvalidPayload CloseCode = 1007
//由于收到不符合约定的数据而断开连接.
ClosePolicyViolation CloseCode = 1008
//由于收到过大的数据帧而断开连接.
CloseMessageTooBig CloseCode = 1009
//缺少扩展：客户端终止连接，因为期望一个或多个拓展, 但服务器没有.
CloseMandatoryExtension CloseCode = 1010
//内部错误：服务器终止连接，因为遇到异常
CloseInternalError CloseCode = 1011
//服务重启：服务器由于重启而断开连接.
CloseServiceRestart CloseCode = 1012
//稍后再试：服务器由于临时原因断开连接。
CloseTryAgainLater CloseCode = 1013
//错误的网关.
CloseBadGateway CloseCode = 1014
//握手错误：表示连接由于无法完成 TLS 握手而关闭 (例如无法验证服务器证书).
CloseTLSHandshake CloseCode = 1015
)