feat(ws): release generic WebSocket client and server v0.31.0-preview

2026-10-29 19:20:12 +08:00
parent 19ee9746e9
commit 3272974bc1
58 changed files with 7654 additions and 21 deletions
--- a/README.md
+++ b/README.md
@@ -2,6 +2,8 @@

 GoOmni 是面向多个项目复用的 Go 基础框架。通用工程使用 `project new` 生成配置、日志、依赖装配、生命周期和普通 Go 运行入口；需要 HTTP 接口时可选择 `.api` 工程生成，也可以在已有项目中按需引入独立模块。运行方式、业务类型和外部依赖由项目决定。

+**v0.31 改动：WebSocket**：新增通用 `ws.Client / Server / Session`，支持有界收发、心跳、重连、TLS、鉴权扩展和排空关闭；可选 `ws/hub` 分组广播、`ws/rpc` 双向调用与订阅恢复、`ws/observe` 日志指标。支持标准 nethttp HTTP/1.1 升级；native/实验 http2 暂不支持。见 [完整 API 与安全边界](ws/README.md)、[Go/浏览器示例](examples/websocket/README.md)、[RPC 示例](examples/websocketRPC/README.md)。
+
 **v0.29 改动**：通用签名读取新增 inline/attachment、中文显示文件名、可选 Content-Type 与实际到期时间；Local、S3/R2、OSS 使用同一接口，原下载接口兼容。本地支持 HEAD、Range、206/416，所有响应选项参与签名。见 [存储说明](storage/README.md#签名预览与下载)及[可运行 PDF 示例](examples/signedRead/README.md)。

 **v0.30 改动**：telemetry 新增配置化 `HeaderPropagator`，兼容网关传入的 Trace/Span/Request Header，同时保留 W3C `traceparent`；入站父链路、日志关联和出站传播统一处理。框架不绑定任何网关名称。见[可运行示例](examples/telemetryHeaders/README.md)和[观测说明](ADVANCED.md#熔断与观测)。
@@ -14,9 +16,9 @@ GoOmni 是面向多个项目复用的 Go 基础框架。通用工程使用 `proj

 **v0.27 改动**：统一三种内置服务实现的默认/路由/硬请求体限额，配置冲突在启动前报错；停机以处理函数实际退出为资源清理前提，超时仍有请求时保留共享依赖。见 [HTTP 策略](transport/README.md#统一请求体限额)、[停机规则](lifecycle/README.md#http-请求与依赖的关闭屏障)和[可运行示例](examples/httpSafety/README.md)。

-**v0.26 改动**：通用 [i18n](i18n/README.md)，提供独立词典、语言匹配、回退、命名参数/条件/复数、可选 HTTP 与错误适配、检查/导出 CLI 及前端运行时。文案由项目维护；[完整示例](examples/i18n/README.md)可直接运行。CLI 与框架使用同版 v0.30.0-preview。同时修复 Go 1.22 下请求体限额错误的识别。
+**v0.26 改动**：通用 [i18n](i18n/README.md)，提供独立词典、语言匹配、回退、命名参数/条件/复数、可选 HTTP 与错误适配、检查/导出 CLI 及前端运行时。文案由项目维护；[完整示例](examples/i18n/README.md)可直接运行。CLI 与框架使用同版 v0.31.0-preview。同时修复 Go 1.22 下请求体限额错误的识别。

-**从这份 README 开始接入。** 当前版本 **`v0.30.0-preview`**，通用工程采用根目录入口和 `config / svc / run`；API 工程使用 `config / svc / logic / handler`。可以固定版本开展业务接入；文件维护边界和已有服务迁移步骤见 [项目指南](PROJECT.md)，版本变化与验收见 [发布说明](RELEASE.md)。
+**从这份 README 开始接入。** 当前版本 **`v0.31.0-preview`**，通用工程采用根目录入口和 `config / svc / run`；API 工程使用 `config / svc / logic / handler`。可以固定版本开展业务接入；文件维护边界和已有服务迁移步骤见 [项目指南](PROJECT.md)，版本变化与验收见 [发布说明](RELEASE.md)。

 **v0.25 改动**：`database.InTx` 返回可识别的事务阶段与结果，保留业务/驱动及回滚错误链；提交报错保守标记为结果不确定，不等同于已回滚。[使用规则](database/README.md#事务阶段与结果)、[可运行故障示例](examples/transactions/README.md)。

@@ -69,6 +71,7 @@ Go **1.22+**。框架不依赖 Gin，默认使用标准库网络层，提供可
 | 认证与权限接口 | 注入 Authenticator / Policy；JWT 或 Session 只是可选实现 | [认证说明](auth/README.md)、[鉴权完整例子](examples/platform/README.md) |
 | 缓存 | `cache.NewMemory` 或 Redis 实现；业务面向 Store 的 Get/Set/Delete | [缓存配置/代码](MODULES.md)、[可运行模块服务](examples/modules/README.md) |
 | 出站 HTTP、熔断 | `httpc.New` 配置代理、连接池和阶段超时；JSON 支持单次成功状态限制/请求头/限额；`resilience.New` 隔离故障 | [HTTP 完整用法](httpc/README.md)、[可运行示例](examples/httpClient/README.md)、[熔断/观测](ADVANCED.md#熔断与观测) |
+| WebSocket 双向通信 | `ws.NewClient/NewServer`；`ws/omni.Mount`；可选 Hub、RPC、订阅恢复和观测 | [功能、配置与停机](ws/README.md)、[浏览器与 Go 示例](examples/websocket/README.md)、[RPC 示例](examples/websocketRPC/README.md) |
 | 请求追踪、访问日志、恢复、限流、幂等、超时 | `app.Use(...)` 按需组合 middleware；跨副本选择 Redis 实现 | [模块说明与限制](MODULES.md#请求追踪与基础指标)、[分布式实现](ADVANCED.md#分布式限流与幂等) |
 | 本地后台任务与调度 | `task.New`、Submit、Every；有界队列、排空关闭 | [task 示例与生命周期](MODULES.md#后台执行task) |
 | 持久队列 | 业务使用 Publisher / Consumer；Redis Streams 提供至少一次交付 | [队列初始化/消费示例](ADVANCED.md#可靠队列) |
@@ -81,7 +84,7 @@ Go **1.22+**。框架不依赖 Gin，默认使用标准库网络层，提供可
 ## 通用工程快速开始

 ```sh
-go install git.yuntuo.hk/k2safe/go-omni/cmd/go-omni@v0.30.0-preview
+go install git.yuntuo.hk/k2safe/go-omni/cmd/go-omni@v0.31.0-preview
 go-omni project new demo --module example.com/demo
 cd demo
 go mod tidy
@@ -186,7 +189,7 @@ module 地址是 `git.yuntuo.hk/k2safe/go-omni`。先确保本机 Go 和 Git 可

 ```sh
 export GOPRIVATE="$(go env GOPRIVATE),git.yuntuo.hk"
-go install git.yuntuo.hk/k2safe/go-omni/cmd/go-omni@v0.30.0-preview
+go install git.yuntuo.hk/k2safe/go-omni/cmd/go-omni@v0.31.0-preview
 export PATH="$(go env GOPATH)/bin:$PATH"
 go-omni --help
 ```
@@ -343,7 +346,7 @@ go-omni new --api catalog.api \
 在业务项目的 **go.mod 所在目录**执行：

 ```sh
-go get git.yuntuo.hk/k2safe/go-omni@v0.30.0-preview
+go get git.yuntuo.hk/k2safe/go-omni@v0.31.0-preview
 ```

 已有项目可直接复用现有目录、Service、Repository 和数据库连接，先选择一个接口接入。也可以只用 `logx`、`storage` 等包，暂时保留原来的 HTTP 框架。希望入口和 HTTP 接入都交给生成器的项目，按 [已有服务接入步骤](PROJECT.md#已有服务接入步骤) 在新目录生成后迁入业务代码。
@@ -674,7 +677,7 @@ go test ./...

 `main.go`、`Gen.go`、`docs/openapi.json` 和 manifest 由生成器管理，手动修改会报告冲突。Logic、Repository、中间件实现、配置和依赖装配属于项目，重复生成保留手写内容。契约变化会提示受影响的 Logic 文件和 DTO 字段，明确的签名错误会给出原签名与期望签名；生成后 `--check` 仍能检出未修复的问题。将 `.api`、`omni.gen.json`、生成文件和 `.goOmni/apiManifest.json` 一起提交，CI 同时运行 `generate --check` 与 `go test ./...`。详见 [契约变更提示与检查边界](PROJECT.md#契约变更提示)。

-CLI 与业务 module 固定使用 `v0.30.0-preview`。v0.21 及更早项目先按 [配置迁移](CONFIG.md#v022-迁移旧模式已移除) 整理旧标签、文件与 Load，再升级依赖与 CLI 并重新生成，框架维护的 main/runtimeGen 自动更新；v0.13 及更早项目按 [升级预览](DEVELOPMENT.md#v013-项目升级) 处理，不直接覆盖手写入口或业务文件。使用过旧 mapping 的项目必须先完成 [移除迁移](COPY.md#从旧-mapping-迁移)，旧配置或旧生成文件会阻止生成。升级后执行生成检查与业务回归。版本变化、迁移边界和验收记录见 [发布说明](RELEASE.md)。
+CLI 与业务 module 固定使用 `v0.31.0-preview`。v0.21 及更早项目先按 [配置迁移](CONFIG.md#v022-迁移旧模式已移除) 整理旧标签、文件与 Load，再升级依赖与 CLI 并重新生成，框架维护的 main/runtimeGen 自动更新；v0.13 及更早项目按 [升级预览](DEVELOPMENT.md#v013-项目升级) 处理，不直接覆盖手写入口或业务文件。使用过旧 mapping 的项目必须先完成 [移除迁移](COPY.md#从旧-mapping-迁移)，旧配置或旧生成文件会阻止生成。升级后执行生成检查与业务回归。版本变化、迁移边界和验收记录见 [发布说明](RELEASE.md)。

 ## 按需深入