goWs

README

goWs

基于gorilla封装的并发安全的Golang Websocket组件

结构体

WsConnection

// WsConnection表示维护的一个websocket类型.
type WsConnection struct {
	// 隐藏了内部字段
}

WsMessage

// WsMessage描述了一个消息实体.
type WsMessage struct {
	// 消息发送对象
	To MsgTo
	// The message types are defined in RFC 6455, section 11.8.
	MessageType int
	// 消息内容
	Data []byte
}

// ToType定义了消息发送的对象类型.
type ToType string

// MsgTo定义了消息发送的对象.
type MsgTo struct {
	ToType ToType
	To     string
}

通过WsMessage类，在内部进行对应消息的转发，如消息的一对一；一对多等。 1、WsMessage中To字段是内部自定义的一个类型MsgTo，指定了消息发送的对象， MsgTo包含字段ToType以及字段To：字段ToType即消息发送的对象类型，分别是ToAll(发送给所有在线连接)、ToGroup(发送给群组在线连接)以及ToConn(发送给指定连接)； 字段To即具体对象。 2、MessageType是消息的具体类型； 3、Data是消息内容。

接口

type Conn interface {
	Close() error
	Open(w http.ResponseWriter, r *http.Request) error
	Receive() (msg *WsMessage, err error)
	Write(msg *WsMessage) (err error)
}

接口Conn对外暴露了4个方法。方法Close即Close掉NewWsConnection构造的连接；方法Open会将HTTP服务器连接升级到WebSocket协议； 方法Receive接收客户端发送过来的消息；方法Write将消息发向客户端。

// Collection描述了客户端维护的websocket在线连接接口的具体类型.
type Collection interface {
	// 将连接写入集合
	Set(id string, wsConn *websocket.Conn) error
	// 从集合中获取对应id的连接
	Get(id string) (wsConn *websocket.Conn, err error)
	// 通过groupName获取对应的连接列表
	GetGroup(groupName string) (wsConnList []*websocket.Conn, err error)
	// 获取所有连接
	GetAll() (wsConnList []*websocket.Conn, err error)
	// 将id对应的连接从集合中删除
	Del(id string) error
}

接口Collection描述了是如何维护一个在线连接。使用前，请先实现此接口。

// HeartBeater描述了维持心跳所需要的数据
type HeartBeater interface {
	// 校验是否客户端Ping请求
	IsPingMsg(msg []byte) bool
	// 获取服务端->客户端Pong请求数据
	GetPongMsg() []byte
	// 获取心跳间隔有效时间（单位是秒）。如果两次心跳大于这个有效时间，连接将断开
	GetHeartbeatTime() int
}

接口HeartBeater描述了维持心跳所需要的数据。使用前，请先实现此接口。

方法说明

func NewWsConnection(collect Collection, heartBeater HeartBeater) *WsConnection

方法NewWsConnection为新建一个WsConnection连接。 入参collect为Collection接口类的具体实现；入参heartBeater为HeartBeater接口的具体实现。

func (conn *WsConnection) Close() error
func (conn *WsConnection) Open(w http.ResponseWriter, r *http.Request) error
func (conn *WsConnection) Receive() (msg *WsMessage, err error)
func (conn *WsConnection) Write(msg *WsMessage) (err error)

上面4个方法是接口Conn对外暴露的4个方法。

快速开始

import (
   "fmt"
   "github.com/gorilla/websocket"
   "github.com/lcr2000/goWs"
   "net/http"
)

func Ws(w http.ResponseWriter, r *http.Request) {
   conn := ws.NewWsConnection(collect{}, beat{})
   if err := conn.Open(w, r); err != nil {
   	return
   }
   for {
   	msg, err := conn.Receive()
   	if err != nil {
   		break
   	}
   	fmt.Println(string(msg.Data))
   	err = conn.Write(&ws.WsMessage{
   		To:          msg.To,
   		MessageType: msg.MessageType,
   		Data:        msg.Data,
   	})
   	if err != nil {
   		break
   	}
   }
}

// collect为实现Collection接口的具体类。
type collect struct{}

func (e collect) Set(id string, wsConn *websocket.Conn) error {
   return nil
}

func (e collect) Get(id string) (wsConn *websocket.Conn, err error) {
   return
}

func (e collect) GetGroup(groupName string) (wsConnList []*websocket.Conn, err error) {
   return
}

func (e collect) GetAll() (wsConnList []*websocket.Conn, err error) {
   return
}

func (e collect) Del(id string) error {
   return nil
}

// beat为实现HeartBeater接口的具体类。
type beat struct{}

func (b beat) IsPingMsg(msg []byte) bool {
   return false
}

func (b beat) GetPongMsg() []byte {
   return []byte{}
}

func (b beat) GetHeartbeatTime() int {
   return 10
}

Documentation

Index

• Variables
• type Collection
• type Conn
• type HeartBeater
• type MsgTo
• type ToType
• type WsConnection
  • func NewWsConnection(collect Collection, heartBeater HeartBeater) *WsConnection
  • func (conn *WsConnection) Close() error
  • func (conn *WsConnection) GetWsConnId() string
  • func (conn *WsConnection) Open(w http.ResponseWriter, r *http.Request) error
  • func (conn *WsConnection) Receive() (msg *WsMessage, err error)
  • func (conn *WsConnection) Write(msg *WsMessage) (err error)
• type WsMessage

Variables

var (
	// websocket连接已关闭
	ErrWsConnClose = errors.New("websocket connection closed")
	// websocket唯一连接id不能为空
	ErrIdEmpty = errors.New("id is null")
)

Types

type Collection

type Collection interface {
	// 将连接写入集合
	Set(id string, wsConn *websocket.Conn) error
	// 从集合中获取对应id的连接
	Get(id string) (wsConn *websocket.Conn, err error)
	// 通过groupName获取对应的连接列表
	GetGroup(groupName string) (wsConnList []*websocket.Conn, err error)
	// 获取所有连接
	GetAll() (wsConnList []*websocket.Conn, err error)
	// 将id对应的连接从集合中删除
	Del(id string) error
}

Collection描述了客户端维护的websocket在线连接接口的具体类型.

type Conn

type Conn interface {
	Close() error
	Open(w http.ResponseWriter, r *http.Request) error
	Receive() (msg *WsMessage, err error)
	Write(msg *WsMessage) (err error)
}

type HeartBeater

type HeartBeater interface {
	// 校验是否客户端Ping请求
	IsPingMsg(msg []byte) bool
	// 获取服务端->客户端Pong请求数据
	GetPongMsg() []byte
	// 获取心跳间隔有效时间（单位是秒）。如果两次心跳大于这个有效时间，连接将断开
	GetHeartbeatTime() int
}

HeartBeater描述了维持心跳所需要的数据

type MsgTo

type MsgTo struct {
	ToType ToType
	To     string
}

MsgTo定义了消息发送的对象.

type ToType

type ToType string

ToType定义了消息发送的对象类型.

const (
	// 发送给所有在线连接
	ToAll ToType = "All"
	// 发送给群组在线连接
	ToGroup ToType = "Group"
	// 发送给指定连接
	ToConn ToType = "Conn"
)

描述了消息发送的对象

type WsConnection

type WsConnection struct {
	// contains filtered or unexported fields
}

WsConnection表示维护的一个websocket类型.

func NewWsConnection

func NewWsConnection(collect Collection, heartBeater HeartBeater) *WsConnection

NewWsConnection为新建一个WsConnection连接. collect为Collection接口类的具体实现；heartBeater为HeartBeater接口的具体实现.

func (*WsConnection) Close

func (conn *WsConnection) Close() error

func (*WsConnection) GetWsConnId

func (conn *WsConnection) GetWsConnId() string

GetWsConnId获取WsConnection中唯一连接id

func (*WsConnection) Open

func (conn *WsConnection) Open(w http.ResponseWriter, r *http.Request) error

func (*WsConnection) Receive

func (conn *WsConnection) Receive() (msg *WsMessage, err error)

func (*WsConnection) Write

func (conn *WsConnection) Write(msg *WsMessage) (err error)

type WsMessage

type WsMessage struct {
	// 消息发送对象
	To MsgTo
	// The message types are defined in RFC 6455, section 11.8.
	MessageType int
	// 消息内容
	Data []byte
}

WsMessage描述了一个消息实体.