zzserver

zzServer

基于 Go 的轻量 WebSocket 服务端框架，采用 hub 单协程管理连接，通过 IRouter 接口处理业务逻辑，支持与 Gin 集成。

特性

• WebSocket 长连接，内置 Ping/Pong 心跳与读超时检测
• 同一连接可同时接收 TextMessage 与 BinaryMessage
• 默认发送类型可配置（Text / Binary），也支持按消息指定发送类型
• 与 Gin 集成：可在同一端口同时提供 HTTP API 与 WebSocket
• 广播、按连接 ID 查找、遍历在线客户端
• 优雅关闭：停止监听 → 回调 → 断开所有客户端 → 停止 hub

安装

go get gitee.com/douyaye/zzserver

依赖：Go 1.24+、Gin、Gorilla WebSocket。

快速开始

package main

import (
    "log"
    "net/http"

    "gitee.com/douyaye/zzserver"
    "github.com/gin-gonic/gin"
    "github.com/gorilla/websocket"
)

func main() {
    srv := zzserver.NewZZServer()

    g := gin.Default()
    g.GET("/hello", func(c *gin.Context) {
        c.JSON(http.StatusOK, gin.H{"code": 0})
    })

    srv.SetGinEngine(g)       // 不设置则自动生成默认 Gin
    srv.SetRouter(&MyRouter{})
    srv.SetWebsocketPort(9999)
    srv.SetWsPath("/")        // 可选，默认 "/"

    if err := srv.Start(); err != nil {
        log.Fatal(err)
    }

    srv.WaitCloseSignal(nil, nil)
}

type MyRouter struct {
    zzserver.BaseRouter
}

func (r *MyRouter) OnMessage(c *zzserver.Client, msgType int, message []byte) {
    switch msgType {
    case websocket.TextMessage:
        c.SendText("收到: " + string(message))
    case websocket.BinaryMessage:
        c.Send(websocket.BinaryMessage, message)
    }
}

func (r *MyRouter) OnConnected(c *zzserver.Client) {
    log.Printf("客户端 %d 已连接, IP=%s", c.ConnectionIndex, c.GetIP())
}

func (r *MyRouter) OnDisconnect(c *zzserver.Client) {
    log.Printf("客户端 %d 已断开", c.ConnectionIndex)
}

连接地址：

ws://127.0.0.1:9999/          WebSocket（默认 Text 发送）
http://127.0.0.1:9999/hello   HTTP 接口

更多示例见 example/json（JSON 文本）和 example/protobuf（Protobuf 二进制）。

路由接口 IRouter

实现 IRouter，或嵌入 BaseRouter 只重写需要的方法：

type IRouter interface {
    OnMessage(c *Client, msgType int, message []byte)
    OnDisconnect(c *Client)
    OnServerClose()
    OnConnected(c *Client)
}

Server API

配置

生命周期

Start() 可能返回的错误：

• ErrRouterNotSet — 未设置 Router
• ErrPortNotSet — 未设置端口
• ErrAlreadyStarted — 重复调用 Start()

客户端管理

Client API

字段

发送消息

发送队列满时会自动断开连接。

连接信息

使用注意

发送与接收类型

• SetMessageType 只影响该连接的默认发送类型（SendByte / SendText / SendJson）
• 接收类型由每条消息的 msgType 参数决定，同一连接可混用 Text 与 Binary

OnMessage 不要阻塞

OnMessage 在读协程中同步执行，阻塞会卡住该连接后续消息的读取。解析、落库等耗时操作应 go func() { ... }() 异步处理。

空闲踢人

框架不内置空闲超时，可自行定时 Range 检查 LastMsgTime()：

go func() {
    ticker := time.NewTicker(5 * time.Second)
    defer ticker.Stop()
    for range ticker.C {
        deadline := time.Now().Add(-30 * time.Second)
        srv.Range(func(c *zzserver.Client) bool {
            if c.LastMsgTime().Before(deadline) {
                c.Close()
            }
            return true
        })
    }
}()

心跳 Pong 会刷新 LastMsgTime()，正常挂机的客户端不会被误踢。

关闭顺序

Close()
  ├─ 停止 HTTP 监听
  ├─ OnServerClose()
  ├─ 断开所有客户端
  └─ 停止 hub

架构简述

                    ┌─────────────┐
  WebSocket 连接 ──►│ 读协程       │──► OnMessage（业务）
                    └─────────────┘
                           │
                    connected / disconnected
                           ▼
                    ┌─────────────┐
                    │ hub 协程     │──► OnConnected / OnDisconnect
                    │ (clients map)│──► Range / Online / GetClient / 广播
                    └─────────────┘
                           │
                    ┌─────────────┐
                    │ 写协程       │◄── Send / bufSend
                    │ + Ping 心跳  │
                    └─────────────┘

示例项目

by. douya