# websocket-module

**Repository Path**: dreamwithouttrace/websocket-module

## Basic Information

- **Project Name**: websocket-module
- **Description**: 嘻嘻嘻嘻嘻嘻嘻嘻嘻嘻
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-08-03
- **Last Updated**: 2025-12-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# WebSocket 模块

这是一个可复用的WebSocket服务器模块，提供了完整的WebSocket连接管理、消息处理、用户认证等功能。

## 特性

- 🚀 **高性能**: 使用分片连接池管理大量并发连接
- 🔐 **安全认证**: 支持多种认证方式（Token、假用户、测试用户）
- 📊 **实时统计**: 提供在线用户统计和监控
- 🔄 **消息确认**: 支持消息ACK机制，确保消息可靠传递
- 🛡️ **限流保护**: 内置请求限流机制
- 🎯 **模块化设计**: 清晰的模块分离，易于扩展和定制
- 📝 **完整API**: 提供RESTful API进行服务器管理

## 目录结构

```
websocket-module/
├── core/           # 核心接口和类型定义
├── transport/      # 传输层管理
├── handlers/       # 处理器（握手、API）
├── middleware/     # 中间件（认证、限流）
├── examples/       # 使用示例
├── server.go       # 主服务器
└── README.md       # 文档
```

## 快速开始

### 1. 基本使用

```go
package main

import (
    "log"
    "websocket-module/core"
    "websocket-module/websocket"
)

func main() {
    // 创建配置
    config := core.DefaultConfig()
    config.Host = "127.0.0.1"
    config.Port = 8080

    // 创建Redis和数据库客户端（这里使用模拟实现）
    redis := &MockRedis{}
    db := &MockDB{}

    // 创建WebSocket服务器
    server := websocket.NewServer(config, redis, db)

    // 设置回调函数
    server.SetCallbacks(
        // 断开连接回调
        func(conn core.Connection) {
            log.Printf("用户断开连接: %s", conn.GetUserID())
        },
        // 消息回调
        func(conn core.Connection, message []byte) {
            log.Printf("收到消息: %s", string(message))
        },
        // 连接回调
        func(conn core.Connection) error {
            log.Printf("用户连接: %s", conn.GetUserID())
            return nil
        },
    )

    // 运行服务器
    log.Println("启动WebSocket服务器...")
    if err := server.Run(); err != nil {
        log.Fatalf("服务器运行失败: %v", err)
    }
}
```

### 2. 自定义配置

```go
config := &core.Config{
    Host:             "0.0.0.0",
    Port:             8080,
    ReadTimeout:      5 * time.Second,
    WriteTimeout:     5 * time.Second,
    MaxHeaderBytes:   1 << 20,
    SharedCount:      1000,
    EnableCompression: true,
    ReadBufferSize:   4096,
    WriteBufferSize:  4096,
}
```

## API 接口

### WebSocket 连接

- `GET /ws` - 标准WebSocket连接（需要认证）
- `GET /test-ws` - 测试WebSocket连接
- `GET /faker` - 假用户WebSocket连接

### 管理API

- `GET /kick?userId=123` - 踢出指定用户
- `GET /online/lists` - 获取在线用户列表
- `GET /get/online?id=123` - 获取指定用户信息
- `GET /check/content?keyword=xxx` - 检查内容
- `POST /check/content` - POST方式检查内容
- `GET /statistics` - 获取统计信息

## 核心接口

### User 接口

```go
type User interface {
    GetID() int64
    GetUniqueID() string
    GetNickname() string
    GetAvatar() string
    GetSex() string
    GetIsOnline() string
    GetSocketID() string
    SetIsOnline(status string)
    SetSocketID(socketID string)
    GetLastLoginTime() int64
    SetLastLoginTime(time int64)
    GetLastInnerIP() string
    SetLastInnerIP(ip string)
    GetScore() int
    SetScore(score int)
    GetBirthday() string
    SetBirthday(birthday string)
    GetDisabledEndTime() int64
    GetAppID() int64
    GetIsFaker() string
}
```

### Connection 接口

```go
type Connection interface {
    GetUser() User
    GetChannelID() string
    GetUserID() string
    GetIP() string
    WriteMessage(data []byte) error
    Close() error
    IsConnected() bool
    SetConnected(connected bool)
    GetWaits() *Waits
    SetWaits(waits *Waits)
    GetSendNo() int64
    IncrementSendNo()
    Push(msg string)
    Kick()
    Ping()
    Pong()
    GetUniqueID() string
    SetReadDeadline(second int) error
}
```

## 中间件

### 认证中间件

```go
auth := middleware.NewAuthMiddleware(redis, db)
user, err := auth.Process(w, r)
if err != nil {
    http.Error(w, err.Error(), http.StatusUnauthorized)
    return
}
```

### 限流中间件

```go
rateLimit := middleware.NewRateLimitMiddleware(redis, 100, time.Minute)
user, err := rateLimit.Process(w, r)
if err != nil {
    http.Error(w, err.Error(), http.StatusTooManyRequests)
    return
}
```

## 消息格式

### 客户端发送消息

```json
{
    "event": "chat",
    "sendId": "user123",
    "data": {
        "message": "Hello World",
        "roomId": "room1"
    },
    "channelId": "channel123",
    "eventName": "chat"
}
```

### 服务器推送消息

```json
{
    "event": "message",
    "sendId": "server",
    "data": {
        "content": "Hello from server",
        "timestamp": 1640995200
    },
    "ack": 12345
}
```

## 配置说明

| 配置项 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
| Host | string | "127.0.0.1" | 服务器监听地址 |
| Port | int | 14101 | 服务器监听端口 |
| ReadTimeout | time.Duration | 2s | 读取超时时间 |
| WriteTimeout | time.Duration | 2s | 写入超时时间 |
| MaxHeaderBytes | int | 1MB | 最大请求头大小 |
| SharedCount | int64 | 1000 | 连接分片数量 |
| EnableCompression | bool | true | 是否启用压缩 |
| ReadBufferSize | int | 4096 | 读取缓冲区大小 |
| WriteBufferSize | int | 4096 | 写入缓冲区大小 |

## 扩展开发

### 自定义用户实现

```go
type CustomUser struct {
    ID       int64  `json:"id"`
    Nickname string `json:"nickname"`
    // ... 其他字段
}

func (u *CustomUser) GetID() int64 {
    return u.ID
}

func (u *CustomUser) GetNickname() string {
    return u.Nickname
}

// 实现其他接口方法...
```

### 自定义中间件

```go
type CustomMiddleware struct {
    // 自定义字段
}

func (m *CustomMiddleware) Process(w http.ResponseWriter, r *http.Request) (core.User, error) {
    // 自定义处理逻辑
    return user, nil
}
```

## 性能优化

1. **连接分片**: 使用SharedCount参数调整分片数量
2. **缓冲区大小**: 根据消息大小调整ReadBufferSize和WriteBufferSize
3. **超时设置**: 根据网络环境调整ReadTimeout和WriteTimeout
4. **压缩**: 对于文本消息，启用EnableCompression可以提高传输效率

## 监控和调试

### 统计信息

```go
boy, girl, noSex := transport.OnlineUserInformationStatistics()
total := boy + girl + noSex
log.Printf("在线用户: %d, 男性: %d, 女性: %d, 无性别: %d", total, boy, girl, noSex)
```

### 连接管理

```go
// 获取在线用户列表
lists := transport.GetClientLists()

// 检查用户是否在线
exists := transport.Exists(userID)

// 获取用户连接
conn := transport.Get(userID)
```

## 注意事项

1. **Redis依赖**: 模块依赖Redis进行连接限制和缓存，请确保Redis服务可用
2. **数据库接口**: 需要实现数据库接口来获取用户信息
3. **错误处理**: 建议在生产环境中添加完善的错误处理和日志记录
4. **安全考虑**: 在生产环境中，请确保认证逻辑的安全性

## 许可证

MIT License