编辑“︁Gin WebSocket基础”︁

= Gin WebSocket基础 =

== 介绍 ==  
'''WebSocket'''是一种在单个TCP连接上提供全双工通信的协议，允许服务器和客户端实时交换数据。在Gin框架中，可以通过集成第三方库（如<code>gorilla/websocket</code>）实现WebSocket功能。本章将介绍如何在Gin中建立WebSocket连接，并展示基础用法和实际案例。

== 核心概念 ==  
=== WebSocket协议 ===  
WebSocket通过HTTP/HTTPS协议升级握手建立连接，之后转为持久化的双向通信。其特点包括：  
* 低延迟  
* 支持文本和二进制数据传输  
* 无需重复握手  

=== Gin中的实现 ===  
Gin本身不直接支持WebSocket，但可通过以下步骤集成：  
1. 使用<code>gorilla/websocket</code>库处理协议升级。  
2. 在Gin路由中定义WebSocket端点。  
3. 管理连接的生命周期。

== 代码示例 ==  
=== 基础实现 ===  
以下示例展示如何在Gin中创建WebSocket服务端：  

<syntaxhighlight lang="go">  
package main  

import (
    "github.com/gin-gonic/gin"
    "github.com/gorilla/websocket"
    "net/http"
)

var upgrader = websocket.Upgrader{
    CheckOrigin: func(r *http.Request) bool { return true }, // 允许跨域
}

func handleWebSocket(c *gin.Context) {
    conn, err := upgrader.Upgrade(c.Writer, c.Request, nil)
    if err != nil {
        c.AbortWithError(http.StatusInternalServerError, err)
        return
    }
    defer conn.Close()

    for {
        // 读取客户端消息
        messageType, p, err := conn.ReadMessage()
        if err != nil {
            break
        }
        // 回显消息
        if err := conn.WriteMessage(messageType, p); err != nil {
            break
        }
    }
}

func main() {
    r := gin.Default()
    r.GET("/ws", handleWebSocket)
    r.Run(":8080")
}
</syntaxhighlight>  

'''输入/输出说明'''：  
- 客户端连接到<code>ws://localhost:8080/ws</code>后，发送的任何消息会被服务端原样返回。  
- 使用<code>websocket.Upgrader</code>将HTTP连接升级为WebSocket连接。

=== 客户端示例 ===  
使用JavaScript的WebSocket API测试上述服务：  

<syntaxhighlight lang="javascript">  
const socket = new WebSocket('ws://localhost:8080/ws');  

socket.onopen = () => {  
    socket.send("Hello Gin!");  
};  

socket.onmessage = (event) => {  
    console.log("Received:", event.data); // 输出: "Hello Gin!"  
};  
</syntaxhighlight>  

== 实际应用场景 ==  
=== 实时聊天系统 ===  
WebSocket适用于需要实时双向通信的场景，如：  
1. 用户A发送消息 → 服务端 → 实时推送给用户B  
2. 在线协作编辑工具  

<mermaid>  
sequenceDiagram  
    participant ClientA  
    participant Server  
    participant ClientB  
    ClientA->>Server: 发送消息 "Hi"  
    Server->>ClientB: 转发消息 "Hi"  
</mermaid>  

=== 实时数据监控 ===  
服务端持续推送数据更新（如股票价格、传感器数据）：  

<syntaxhighlight lang="go">  
func handleDataStream(c *gin.Context) {  
    conn, _ := upgrader.Upgrade(c.Writer, c.Request, nil)  
    defer conn.Close()  

    ticker := time.NewTicker(1 * time.Second)  
    for range ticker.C {  
        data := fetchLiveData() // 模拟获取数据  
        conn.WriteJSON(data)    // 以JSON格式发送  
    }  
}  
</syntaxhighlight>  

== 高级主题 ==  
=== 连接管理 ===  
* 使用<code>sync.Map</code>存储活跃连接  
* 实现心跳机制检测连接存活  

=== 错误处理 ===  
WebSocket常见错误包括：  
* 连接意外关闭  
* 消息格式错误  
* 网络延迟  

处理示例：  
<syntaxhighlight lang="go">  
if err := conn.WriteMessage(...); err != nil {  
    if websocket.IsUnexpectedCloseError(err) {  
        log.Println("Client disconnected")  
    }  
}  
</syntaxhighlight>  

== 数学基础（可选） ==  
WebSocket帧协议头部长度计算：  
<math>  
HeaderSize = 2 + (payload\_length \geq 126 \ ?\ (payload\_length \leq 65535 \ ?\ 2 : 8) : 0)  
</math>  

== 总结 ==  
Gin通过集成<code>gorilla/websocket</code>可快速实现WebSocket服务，适用于实时通信场景。关键步骤包括：  
1. 协议升级  
2. 消息读写循环  
3. 连接生命周期管理

[[Category:后端框架]]
[[Category:Gin]]
[[Category:Gin Websocket]]