gohub

README

GoHub - 高性能分布式 Go WebSocket 框架

GoHub 是一个基于Gorilla WebSocket开发的、强大的分布式WebSocket框架，专为高并发实时通信系统设计。其核心优势在于完全分布式架构设计和高效的消息分发机制，可轻松扩展至数十万并发连接，同时保持高吞吐量和低延迟。

🌟 核心特性

• 🚀 极简 API: 几行代码即可启动功能完整的 WebSocket 服务器
• 🌐 分布式设计: 内置集群支持，支持 NATS 和 Redis 作为消息总线
• 📨 灵活的消息处理: 基于类型的消息路由和自定义处理器
• 🏠 房间管理: 内置房间/频道功能，支持跨节点通信
• 🔐 认证授权: JWT 认证和细粒度权限控制
• 📊 可观测性: 集成 Prometheus 指标和结构化日志
• ⚡ 高性能: 单节点支持 10万+ 并发连接

🚀 快速开始

安装

go get github.com/chenxilol/gohub

最简单的示例

package main

import (
	"context"
	"log"
	"github.com/chenxilol/gohub/server"
)

func main() {
	// 创建服务器 - 就是这么简单！
	srv, err := server.NewServer(nil) // 使用默认配置
	if err != nil {
		log.Fatal(err)
	}

	// 启动服务器
	log.Println("Server starting on :8080...")
	if err := srv.Start(); err != nil {
		log.Fatal(err)
	}
}

添加自定义消息处理器

package main

import (
	"context"
	"encoding/json"
	"log"
	"github.com/chenxilol/gohub/server"
	"github.com/chenxilol/gohub/pkg/hub"
)

func main() {
	// 创建服务器
	srv, err := server.NewServer(&server.Options{
		Address:        ":8080",
		AllowAnonymous: true,
	})
	if err != nil {
		log.Fatal(err)
	}

	// 注册消息处理器
	srv.RegisterHandler("echo", func(ctx context.Context, client *hub.Client, data json.RawMessage) error {
		// 直接回显消息
		return client.Send(hub.Frame{
			MsgType: 1, // TextMessage
			Data:    data,
		})
	})

	// 启动服务器
	log.Fatal(srv.Start())
}

监听事件

// 监听客户端连接事件
srv.On(sdk.EventClientConnected, func(ctx context.Context, event sdk.Event) error {
	log.Printf("Client connected: %s", event.ClientID)
	return nil
})

// 监听客户端断开事件
srv.On(sdk.EventClientDisconnected, func(ctx context.Context, event sdk.Event) error {
	log.Printf("Client disconnected: %s", event.ClientID)
	return nil
})

💻 更多示例

1. 带认证的服务器

srv, err := server.NewServer(&server.Options{
	Address:        ":8080",
	EnableAuth:     true,
	AllowAnonymous: false,
	JWTSecretKey:   "your-secret-key",
	JWTIssuer:      "your-app-name",
})

2. 集群模式（使用 NATS）

srv, err := server.NewServer(&server.Options{
	Address:       ":8080",
	EnableCluster: true,
	BusType:       "nats",
	NATSConfig: &nats.Config{
		URLs: []string{"nats://localhost:4222"},
		Name: "gohub-node-1",
	},
})

3. 集群模式（使用 Redis）

srv, err := server.NewServer(&server.Options{
	Address:       ":8080",
	EnableCluster: true,
	BusType:       "redis",
	RedisConfig: &redis.Config{
		Addr:     "localhost:6379",
		Password: "",
		DB:       0,
	},
})

4. 添加自定义 HTTP 端点

// 添加统计 API
srv.HandleFunc("/api/stats", func(w http.ResponseWriter, r *http.Request) {
	stats := map[string]interface{}{
		"clients": srv.SDK().GetClientCount(),
		"rooms":   srv.SDK().GetRoomCount(),
	}
	json.NewEncoder(w).Encode(stats)
})

// 添加房间广播 API
srv.HandleFunc("/api/broadcast/room", func(w http.ResponseWriter, r *http.Request) {
	var req struct {
		RoomID  string      `json:"room_id"`
		Message interface{} `json:"message"`
	}
	
	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
		http.Error(w, "Invalid request", http.StatusBadRequest)
		return
	}

	msgBytes, _ := json.Marshal(req.Message)
	srv.SDK().BroadcastToRoom(req.RoomID, msgBytes)
	
	w.WriteHeader(http.StatusOK)
})

📊 与其他WebSocket框架对比

5. 使用 SDK 进行高级操作

特性	GoHub	Melody	Gorilla WebSocket	go-netty-ws
分布式支持	✅ 完全内置	❌ 无	❌ 无	⚠️ 有限
跨节点消息传递	✅ NATS/Redis	❌ 需自行实现	❌ 需自行实现	⚠️ 有限
消息分发机制	✅ 类型化路由	❌ 简单回调	❌ 基础接口	⚠️ 有限
房间/频道管理	✅ 内置	⚠️ 有限支持	❌ 需自行实现	❌ 需自行实现
认证与授权	✅ JWT + 细粒度权限	❌ 需自行实现	❌ 需自行实现	❌ 需自行实现
指标监控	✅ Prometheus	❌ 需自行实现	❌ 需自行实现	❌ 需自行实现
SDK支持	✅ 服务端	❌ 无	❌ 无	⚠️ 有限
活跃维护	✅ 是	⚠️ 有限	✅ 是	⚠️ 有限

// 获取 SDK 实例
sdk := srv.SDK()

// 向所有客户端广播
sdk.BroadcastAll([]byte(`{"type":"announcement","message":"Hello everyone!"}`))

// 向特定客户端发送消息
sdk.SendToClient(clientID, []byte(`{"type":"private","message":"Hello!"}`))

// 创建房间
sdk.CreateRoom("room-1", "Chat Room", 100)

// 让客户端加入房间
sdk.JoinRoom("room-1", clientID)

// 向房间广播
sdk.BroadcastToRoom("room-1", []byte(`{"type":"room","message":"Welcome!"}`))

// 获取房间成员
members, _ := sdk.GetRoomMembers("room-1")

🔌 客户端连接

JavaScript 示例

// 连接到服务器
const ws = new WebSocket('ws://localhost:8080/ws');

// 如果启用了认证
// const ws = new WebSocket('ws://localhost:8080/ws?token=your-jwt-token');

ws.onopen = () => {
	console.log('Connected to GoHub');
	
	// 发送消息
	ws.send(JSON.stringify({
		message_type: "echo",
		data: { text: "Hello, GoHub!" }
	}));
};

ws.onmessage = (event) => {
	const message = JSON.parse(event.data);
	console.log('Received:', message);
};

🆔 客户端ID管理

GoHub 提供了多种方式来识别和管理客户端，后续会添加自定义ID。

客户端ID获取方式

1. JWT认证获取

当启用JWT认证时，系统默认从JWT的sub(Subject)字段提取客户端ID：

srv, err := server.NewServer(&server.Options{
	EnableAuth:   true,
	JWTSecretKey: "your-secret-key",
	JWTIssuer:    "your-app-name",
	// 指定JWT中客户端ID的字段名（默认为"sub"）
	JWTSubjectClaim: "user_id", 
})

JWT示例：

{
  "sub": "user-123",
  "name": "张三",
  "iat": 1516239022
}

1. URL查询参数获取

也可以通过URL参数传递客户端ID：

srv, err := server.NewServer(&server.Options{
	// 允许通过URL查询参数获取客户端ID
	EnableQueryClientID: true,
	// 指定URL参数名（默认为"client_id"）
	QueryClientIDParam: "user", 
})

客户端连接示例：

const ws = new WebSocket('ws://localhost:8080/ws?client_id=user-456');

匿名客户端处理

对于匿名连接，系统会自动生成唯一客户端ID

生成的ID示例：guest-a1b2c3d4-e5f6

服务端获取客户端ID

处理连接和消息时，可以通过Client对象获取ID：

srv.RegisterHandler("echo", func(ctx context.Context, client *hub.Client, data json.RawMessage) error {
	// 获取客户端ID
	clientID := client.GetID()
	log.Printf("收到来自客户端 %s 的消息", clientID)
	
	// 使用客户端ID进行业务逻辑处理
	return client.Send(hub.Frame{
		MsgType: 1,
		Data:    data,
	})
})

📚 配置选项

type Options struct {
	// HTTP服务器地址，默认 ":8080"
	Address string

	// 集群配置
	EnableCluster bool   // 是否启用集群模式，默认 false
	BusType      string // 消息总线类型: "nats", "redis", "noop"

	// 认证配置
	EnableAuth     bool   // 是否启用认证，默认 false
	AllowAnonymous bool   // 是否允许匿名连接，默认 true
	JWTSecretKey   string // JWT密钥
	JWTIssuer      string // JWT签发者

	// WebSocket配置
	ReadTimeout      time.Duration // 读超时，默认 60s
	WriteTimeout     time.Duration // 写超时，默认 60s
	ReadBufferSize   int          // 读缓冲区大小，默认 4KB
	WriteBufferSize  int          // 写缓冲区大小，默认 4KB

	// 日志级别: "debug", "info", "warn", "error"
	LogLevel string
}

📊 内置端点

• /ws - WebSocket 连接端点
• /health - 健康检查
• /metrics - Prometheus 指标

🏗️ 架构设计

GoHub 采用模块化设计，主要组件包括：

• Server: 顶层封装，提供简单易用的 API
• Hub: 核心连接管理器
• Dispatcher: 消息分发器
• MessageBus: 集群通信总线（NATS/Redis）
• SDK: 服务端操作接口

📈 性能

• 单节点支持 10万+ 并发 WebSocket 连接
• 消息延迟 < 1ms（本地）
• 集群模式下支持水平扩展至百万级连接

🤝 贡献

欢迎贡献代码！请查看 贡献指南。

📄 许可证

MIT License - 详见 LICENSE 文件

🔗 链接

• 完整文档
• 示例代码
• 问题反馈