Skip to content

Commit 967538e

Browse files
JoshuahokyJoshuahoky
authored
chore: update websocket docs (#1479)
1 parent 9585944 commit 967538e

File tree

3 files changed

+209
-7
lines changed

3 files changed

+209
-7
lines changed

‎content/en/docs/hertz/tutorials/third-party/protocol/websocket.md‎

Lines changed: 104 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,9 @@
11
---
22
title: "Websocket"
3-
date: 2022-09-13
3+
date: 2025-12-12
44
weight: 4
55
keywords: ["WebSocket", "HTTP", "hijack", "TCP"]
6-
description: "Hertz implements support for WebSocket based on hijack."
6+
description: "Hertz implements support for Gorilla WebSocket based on hijack."
77
---
88

99
WebSocket is a type of full-duplex communication that can be performed on a single TCP connection and is located at the application layer of the OSI model.
@@ -13,7 +13,108 @@ In the WebSocket API, the browser and the server only need to complete a handsha
1313
Hertz provides support for WebSocket and adapts it in Hertz by referring to [gorilla/websocket](https://github.com/gorilla/websocket) using `hijack`.
1414
The usage and parameters are basically the same.
1515

16-
## Install
16+
> **⚠️ Deprecated**
17+
>
18+
> The `hertz-contrib/websocket` middleware is now deprecated.
19+
> Hertz recommends all users to migrate to the official `gorilla/websocket` toolchain using the [Hertz HTTP Adaptor](../../basic-feature/http-adaptor/).
20+
>
21+
> See the migration guide below.
22+
23+
## Migration Guide
24+
25+
1. Remove deprecated dependencies
26+
27+
```sh
28+
github.com/hertz-contrib/websocket
29+
```
30+
31+
2. Use hertz adaptor
32+
33+
```go
34+
// Before (using hertz-contrib/websocket)
35+
import "github.com/hertz-contrib/websocket"
36+
var upgrader = websocket.HertzUpgrader{}
37+
func echo(_ context.Context, c *app.RequestContext) {
38+
err := upgrader.Upgrade(c, func(conn *websocket.Conn) {
39+
// Implementation
40+
})
41+
}
42+
h.GET("/echo", echo)
43+
44+
// After (using hertz adaptor)
45+
import "github.com/gorilla/websocket"
46+
var upgrader = websocket.Upgrader{}
47+
func echo(w http.ResponseWriter, r *http.Request) {
48+
c, err := upgrader.Upgrade(w, r, nil)
49+
// Implementation
50+
}
51+
52+
h.GET("/echo", adaptor.HertzHandler(http.HandlerFunc(echo)))
53+
```
54+
55+
## Example Usage
56+
57+
The following example demonstrates how to modify the `server.go` code in the hertz-contrib/echo [example](https://github.com/hertz-contrib/websocket/tree/main/examples/echo) to directly use the adaptor with gorilla/websocket. There is no change to `client.go`
58+
59+
```go
60+
package main
61+
62+
import (
63+
"flag"
64+
"html/template"
65+
"log"
66+
"net/http"
67+
68+
"github.com/cloudwego/hertz/pkg/app/server"
69+
"github.com/cloudwego/hertz/pkg/common/adaptor"
70+
"github.com/gorilla/websocket"
71+
)
72+
73+
var addr = flag.String("addr", "localhost:8080", "http service address")
74+
75+
var upgrader = websocket.Upgrader{} // use default options
76+
77+
func echo(w http.ResponseWriter, r *http.Request) {
78+
c, err := upgrader.Upgrade(w, r, nil)
79+
if err != nil {
80+
log.Print("upgrade:", err)
81+
return
82+
}
83+
defer c.Close()
84+
for {
85+
mt, message, err := c.ReadMessage()
86+
if err != nil {
87+
log.Println("read:", err)
88+
break
89+
}
90+
log.Printf("recv: %s", message)
91+
err = c.WriteMessage(mt, message)
92+
if err != nil {
93+
log.Println("write:", err)
94+
break
95+
}
96+
}
97+
}
98+
99+
func home(w http.ResponseWriter, r *http.Request) {
100+
w.Header().Set("Content-Type", "text/html; charset=utf-8")
101+
homeTemplate.Execute(w, "ws://"+r.Host+"/echo")
102+
}
103+
104+
func main() {
105+
h := server.New(server.WithHostPorts(":8080"))
106+
107+
h.GET("/", adaptor.HertzHandler(http.HandlerFunc(home)))
108+
h.GET("/echo", adaptor.HertzHandler(http.HandlerFunc(echo)))
109+
110+
h.Spin()
111+
}
112+
113+
// Web client code details are available at: https://github.com/hertz-contrib/websocket/blob/main/examples/echo/server.go#L64
114+
var homeTemplate = ""
115+
```
116+
117+
## Install (Deprecated)
17118

18119
```shell
19120
go get github.com/hertz-contrib/websocket

‎content/zh/docs/hertz/tutorials/third-party/middleware/swagger.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ description: "用 Swagger 2.0 来自动生成 RESTful API 文档的 Hertz 中间
88

99
> **⚠️ 已废弃**
1010
>
11-
> `hertz-contrib.swagger` 中间件已被废弃。
11+
> `hertz-contrib/swagger` 中间件已被废弃。
1212
> Hertz 推荐所有用户迁移到官方 `swaggo/swag` 工具链，使用 [Hertz HTTP Adaptor](../../basic-feature/http-adaptor/)。
1313
>
1414
> 迁移指南如下。

‎content/zh/docs/hertz/tutorials/third-party/protocol/websocket.md‎

Lines changed: 104 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,117 @@
11
---
22
title: "Websocket"
3-
date: 2022-09-13
3+
date: 2025-12-12
44
weight: 4
55
keywords: ["WebSocket", "HTTP", "hijack", "TCP"]
66
description: "Hertz 基于 hijack 的方式实现了对 WebSocket 的支持。"
77
---
88

99
WebSocket 是一种可以在单个 TCP 连接上进行全双工通信，位于 OSI 模型的应用层。WebSocket 使得客户端和服务器之间的数据交换变得更加简单，允许服务端主动向客户端推送数据。在 WebSocket API 中，浏览器和服务器只需要完成一次握手，两者之间就可以创建持久性的连接，并进行双向数据传输。
1010

11-
Hertz 提供了 WebSocket 的支持，参考 [gorilla/websocket](http://github.com/gorilla/websocket) 库使用 `hijack` 的方式在 Hertz 进行了适配，用法和参数基本保持一致。
11+
Hertz 提供了 WebSocket 的支持，参考 [gorilla/websocket](http://github.com/gorilla/websocket) 库使用 `hijack` 的方式在 Hertz 进行了适配，用法和参数基本保持一致
1212

13-
## 安装
13+
> **⚠️ 已废弃**
14+
>
15+
> `hertz-contrib/websocket` 中间件已被废弃。
16+
> Hertz 推荐所有用户迁移到官方 `gorilla/websocket` 工具链，使用 [Hertz HTTP Adaptor](../../basic-feature/http-adaptor/)。
17+
>
18+
> 迁移指南如下。
19+
20+
## 迁移指南
21+
22+
1. 移除已废弃的依赖项
23+
24+
```sh
25+
github.com/hertz-contrib/websocket
26+
```
27+
28+
2. 利用 hertz adaptor
29+
30+
```go
31+
// 旧版本（使用 hertz-contrib/websocket)
32+
import "github.com/hertz-contrib/websocket"
33+
var upgrader = websocket.HertzUpgrader{}
34+
func echo(_ context.Context, c *app.RequestContext) {
35+
err := upgrader.Upgrade(c, func(conn *websocket.Conn) {
36+
// 具体实现
37+
})
38+
}
39+
h.GET("/echo", echo)
40+
41+
// 新版本（使用 hertz adaptor)
42+
import "github.com/gorilla/websocket"
43+
var upgrader = websocket.Upgrader{}
44+
func echo(w http.ResponseWriter, r *http.Request) {
45+
c, err := upgrader.Upgrade(w, r, nil)
46+
// 具体实现
47+
}
48+
49+
h.GET("/echo", adaptor.HertzHandler(http.HandlerFunc(echo)))
50+
```
51+
52+
## 示例用法
53+
54+
下面的示例展示了如何修改 hertz-contrib/echo [示例](https://github.com/hertz-contrib/websocket/tree/main/examples/echo) 中的 `server.go` 代码，以便直接使用适配器与 gorilla/websocket 一起工作。`client.go` 无需做任何修改。
55+
56+
```go
57+
package main
58+
59+
import (
60+
"flag"
61+
"html/template"
62+
"log"
63+
"net/http"
64+
65+
"github.com/cloudwego/hertz/pkg/app/server"
66+
"github.com/cloudwego/hertz/pkg/common/adaptor"
67+
"github.com/gorilla/websocket"
68+
)
69+
70+
var addr = flag.String("addr", "localhost:8080", "http service address")
71+
72+
var upgrader = websocket.Upgrader{} // use default options
73+
74+
func echo(w http.ResponseWriter, r *http.Request) {
75+
c, err := upgrader.Upgrade(w, r, nil)
76+
if err != nil {
77+
log.Print("upgrade:", err)
78+
return
79+
}
80+
defer c.Close()
81+
for {
82+
mt, message, err := c.ReadMessage()
83+
if err != nil {
84+
log.Println("read:", err)
85+
break
86+
}
87+
log.Printf("recv: %s", message)
88+
err = c.WriteMessage(mt, message)
89+
if err != nil {
90+
log.Println("write:", err)
91+
break
92+
}
93+
}
94+
}
95+
96+
func home(w http.ResponseWriter, r *http.Request) {
97+
w.Header().Set("Content-Type", "text/html; charset=utf-8")
98+
homeTemplate.Execute(w, "ws://"+r.Host+"/echo")
99+
}
100+
101+
func main() {
102+
h := server.New(server.WithHostPorts(":8080"))
103+
104+
h.GET("/", adaptor.HertzHandler(http.HandlerFunc(home)))
105+
h.GET("/echo", adaptor.HertzHandler(http.HandlerFunc(echo)))
106+
107+
h.Spin()
108+
}
109+
110+
// 网络客户端代码详见：https://github.com/hertz-contrib/websocket/blob/main/examples/echo/server.go#L64，此处省略
111+
var homeTemplate = ""
112+
```
113+
114+
## 安装（已废弃）
14115

15116
```shell
16117
go get github.com/hertz-contrib/websocket

0 commit comments

Comments
 (0)