From e81cefafb862312adde26f33737f32eea71fe046 Mon Sep 17 00:00:00 2001 From: barry Date: Sun, 5 Jul 2026 21:07:23 +0800 Subject: [PATCH] refactor: remove deprecated servers/grpcs package in v2 The package was a thin alias over gatewayserver with no in-repo callers. Update architecture docs and legacy-removal checklist accordingly. Co-authored-by: Cursor --- .github/copilot-instructions.md | 4 ++-- deploy/traefik/dynamic.yml | 4 ++-- docs/architecture-v2.md | 6 +----- docs/copilot-skills.md | 2 +- docs/design-v2.md | 2 +- docs/legacy-removal.md | 11 ++++++++--- docs/modules/servers.md | 34 +++++++++++++++++++-------------- servers/grpcs/doc.go | 5 ----- servers/grpcs/server.go | 34 --------------------------------- 9 files changed, 35 insertions(+), 67 deletions(-) delete mode 100644 servers/grpcs/doc.go delete mode 100644 servers/grpcs/server.go diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 44c07344..b6cf7dca 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -8,7 +8,7 @@ These instructions are project-wide defaults for this repository. Keep changes f - `lava/`: core public interfaces and contracts (`Middleware`, routers, request/response abstractions). - `core/`: runtime capabilities (supervisor, scheduler, tunnel, logging/metrics/tracing, debug, DI builder). -- `servers/`: service hosts (`https` on Fiber, `grpcs` with gateway integration). +- `servers/`: service hosts (`gatewayserver` multi-protocol gateway, `https` on Fiber, `zrpcs` on NATS). - `clients/`: outbound client implementations (`grpcc`, `resty`). - `pkg/`: reusable public utilities/components (including gateway and helpers). - `internal/`: repository-internal implementation details/examples; avoid exposing as public API. @@ -65,5 +65,5 @@ CI reference is `.github/workflows/lint-test.yml` (lint + gotestsum-based tests) - Service lifecycle and management: `core/supervisor/` - DI registration patterns: `core/lavabuilder/` - HTTP server composition: `servers/https/server.go` -- gRPC + gateway composition: `servers/gatewayserver/server.go`（`servers/grpcs` 为废弃别名） +- gRPC + gateway composition: `servers/gatewayserver/server.go` - Gateway behavior and routing: `pkg/gateway/` diff --git a/deploy/traefik/dynamic.yml b/deploy/traefik/dynamic.yml index 19ddb702..d8e031fa 100644 --- a/deploy/traefik/dynamic.yml +++ b/deploy/traefik/dynamic.yml @@ -14,7 +14,7 @@ http: routers: # ---- HTTP/REST + gRPC-Web ---- - # grpcs 默认把 REST 挂在 /api 前缀（StripPrefix("/api", mux.Handler)）； + # gatewayserver 默认把 REST 挂在 /api 前缀（StripPrefix("/api", mux.Handler)）； # gRPC-Web 走 /./ 形式的路径。 gw-http: rule: "Host(`api.example.com`)" @@ -60,7 +60,7 @@ http: - url: "h2c://gateway:50051" # 可选中间件示例：如果后端 REST 不想要 /api 前缀，可在边缘 strip。 - # 注意：不要和 grpcs 里的 StripPrefix("/api") 重复 strip，二选一。 + # 注意：不要和 gatewayserver 里的 StripPrefix("/api") 重复 strip，二选一。 middlewares: strip-api: stripPrefix: diff --git a/docs/architecture-v2.md b/docs/architecture-v2.md index bcbf9d79..36bd037a 100644 --- a/docs/architecture-v2.md +++ b/docs/architecture-v2.md @@ -18,7 +18,6 @@ flowchart TD subgraph Service[服务宿主 servers/*] GWS[servers/gatewayserver] - GRPCS[servers/grpcs 废弃别名] HTTPS[servers/https] ZRPCS[servers/zrpcs] end @@ -232,8 +231,6 @@ sequenceDiagram Handler-->>Client: 响应 ``` -`servers/grpcs` 是 **废弃别名**，内部调用 `gatewayserver.NewWithName(..., "grpc-server")`。 - ### 5.2 zrpc（`servers/zrpcs` + `clients/zrpcc`） ```mermaid @@ -341,7 +338,6 @@ lava/ ├── cmds/ # CLI 命令 ├── servers/ │ ├── gatewayserver/ # ★ 对外多协议网关 -│ ├── grpcs/ # 废弃别名 │ ├── https/ # 纯 HTTP │ └── zrpcs/ # NATS 微服务 ├── pkg/ @@ -362,7 +358,7 @@ lava/ | 之前 | 现在 | | --- | --- | -| `servers/grpcs` 同时承载网关与 zrpc | `gatewayserver` 纯网关；zrpc 外置 | +| `servers/grpcs` 包 | 已删除；使用 `gatewayserver` | | `Mux.RegisterZrpc` | `pkg/zrpcbridge.RegisterMux`（DI 显式调用） | | `grpc_server.zrpc_url` 配置 | 已移除 | | 原生 gRPC 空占位 `stream.grpc.go` | 已删除（直接用 `grpc.ServerStream`） | diff --git a/docs/copilot-skills.md b/docs/copilot-skills.md index c2284bb7..c7218a13 100644 --- a/docs/copilot-skills.md +++ b/docs/copilot-skills.md @@ -216,7 +216,7 @@ func NewUserConfig() *UserConfig { // Create a gRPC service for user management // Includes: // - UserService with GetUser and ListUsers methods -// - Service registration with grpcs server +// - Service registration with gatewayserver func NewUserGrpcService() lava.GrpcRouter { // Copilot 会生成完整的 gRPC 服务实现 } diff --git a/docs/design-v2.md b/docs/design-v2.md index 4c572fad..8530602c 100644 --- a/docs/design-v2.md +++ b/docs/design-v2.md @@ -11,7 +11,7 @@ Lava 在设计上聚焦三件事： 当前在传输层上，Lava 已覆盖： - HTTP（`servers/https` / `clients/resty`） -- gRPC Gateway（`servers/gatewayserver` / `pkg/gateway`；`servers/grpcs` 为废弃别名） +- gRPC Gateway（`servers/gatewayserver` / `pkg/gateway`） - zrpc（`servers/zrpcs` / `clients/zrpcc`，protobuf unary over NATS） ## 2. 核心抽象 diff --git a/docs/legacy-removal.md b/docs/legacy-removal.md index c680ce25..be9bceef 100644 --- a/docs/legacy-removal.md +++ b/docs/legacy-removal.md @@ -23,10 +23,15 @@ | 项 | 位置 | 替代方案 | |----|------|----------| -| `servers/grpcs` | 整个包 | `servers/gatewayserver` + `grpc_passthrough: true` | | `pkg/wsproxy` 废弃构造函数 | `pkg/wsproxy` | `pkg/gateway` WebSocket 前端 | | legacy gRPC 双注册 | `gatewayserver` `grpc_passthrough: false` | 默认 `true`，仅在 Mux 注册 | +### 已移除（v2） + +| 项 | 替代方案 | +|----|----------| +| `servers/grpcs` 包 | `servers/gatewayserver` + `grpc_passthrough: true` | + ### 配置键 | Legacy 键 | 替代键 | @@ -66,6 +71,6 @@ gateway_server: - [x] HTTP 中间件链统一到 `servers/serverhttp.HandlerMiddleware`（#107） - [x] `internal/configs/components/grpc_server.yaml` 已移除，统一 `gateway_server.yaml` - [x] `lavabuilder grpc` 通过 `gatewayserver.LoadConfig` 加载 YAML 并对 `grpc_server` 打废弃警告 -- [ ] 架构文档仅描述 `gateway_server` +- [x] 架构文档仅描述 `gateway_server` - [ ] `task test` 不依赖 legacy 路径（或单独 `task test:legacy`） -- [ ] v3 里程碑前开 PR 删除 `grpcs` 包 +- [x] 删除 `grpcs` 包（v2，不再等待 v3） diff --git a/docs/modules/servers.md b/docs/modules/servers.md index cdc6e465..2d62bc08 100644 --- a/docs/modules/servers.md +++ b/docs/modules/servers.md @@ -7,7 +7,6 @@ | 模块 | 说明 | 关键入口 | | --- | --- | --- | | `servers/gatewayserver` | 对外 Gateway：HTTP/REST、gRPC-Web、WebSocket、原生 gRPC | `gatewayserver.New` | -| `servers/grpcs` | **已废弃别名**，等同 `gatewayserver`（supervisor 名仍为 `grpc-server`） | `grpcs.New` | | `servers/https` | Fiber HTTP 服务，默认接入 debug 与基础中间件 | `https.New` | | `servers/zrpcs` | zrpc 服务宿主，基于 NATS 托管 protobuf unary/streaming RPC | `zrpcs.New` | @@ -19,28 +18,30 @@ | 协议 | 默认端口 | 配置项 | 实现 | | --- | --- | --- | --- | -| HTTP/REST + gRPC-Web | 8080 | `grpc_server.http_port` / `running.HttpPort` | Fiber，`/api` 前缀 | -| WebSocket | 8081（可选） | `websocket_port` | `net/http` | -| 原生 gRPC | 50051 | `grpc_server.grpc_port` / `running.GrpcPort` | `grpc.Server` 或 passthrough | +| HTTP/REST + gRPC-Web | 8080 | `gateway_server.http` / `running.HttpPort` | Fiber，`/api` 前缀 | +| WebSocket | 8081（可选） | `gateway_server.websocket_port` | `net/http` | +| 原生 gRPC | 50051 | `gateway_server.grpc` / `running.GrpcPort` | `grpc.Server` 或 passthrough | ### 装配流程 1. 收集 `GrpcRouter` / `GrpcHttpRouter` → 注册到 `gateway.Mux` 2. Fiber 挂 `/api` → `mux.Handler` -3. 可选 `WebSocketPort` → 独立 `http.Server` -4. gRPC：legacy 双注册，或 `grpc_passthrough` 仅在 Mux 注册 +3. 可选 `websocket_port` → 独立 `http.Server` +4. gRPC：默认 `grpc_passthrough: true`（仅在 Mux 注册）；`false` 为 legacy 双注册 5. 全局中间件：serviceinfo / metric / accesslog / recovery 6. `vars.Register` 路由信息（`gateway-server-info`，兼容 `grpc-server-info`） ### 配置 -YAML 键：`gateway_server`（推荐）或 legacy `grpc_server`。 +YAML 键：**`gateway_server`**（见 `internal/configs/components/gateway_server.yaml`）。 + +旧键 `grpc_server` 仍可解析，启动时会打废弃警告；详见 `docs/legacy-removal.md`。 ```yaml gateway_server: enable_print_router: true + grpc_passthrough: true websocket_port: 8081 - grpc_passthrough: false http: {} grpc: {} ``` @@ -52,12 +53,7 @@ gateway_server: ### 命令入口 -`lava grpc` → `cmds/grpcservercmd` → `gatewayserver.New` - -## `servers/grpcs`（废弃） - -类型别名 + `New()` 包装，supervisor 服务名仍为 `grpc-server`，便于老项目兼容。 -新代码请使用 `gatewayserver.New`。 +`lava grpc` → `cmds/grpcservercmd` → `gatewayserver.New` + `gatewayserver.LoadConfig` ## `servers/https` 要点 @@ -113,3 +109,13 @@ flowchart LR Bridge[pkg/zrpcbridge] -.->|可选| Mux Bridge -.-> NATS ``` + +## Legacy（v3 移除） + +| 项 | 替代 | +| --- | --- | +| YAML 键 `grpc_server` | `gateway_server` | +| `grpc_passthrough: false` | 默认 `true` | +| `servers/grpcs` 包 | 已在 v2 删除，请用 `servers/gatewayserver` | + +详见 `docs/legacy-removal.md`。 diff --git a/servers/grpcs/doc.go b/servers/grpcs/doc.go deleted file mode 100644 index c289d93d..00000000 --- a/servers/grpcs/doc.go +++ /dev/null @@ -1,5 +0,0 @@ -// Package grpcs is a deprecated alias for gatewayserver. -// -// Deprecated: import github.com/pubgo/lava/v2/servers/gatewayserver instead. -// This package will be removed in v3. -package grpcs diff --git a/servers/grpcs/server.go b/servers/grpcs/server.go deleted file mode 100644 index 003b6210..00000000 --- a/servers/grpcs/server.go +++ /dev/null @@ -1,34 +0,0 @@ -package grpcs - -import ( - "sync" - - "github.com/pubgo/funk/v2/log" - - "github.com/pubgo/lava/v2/core/supervisor" - "github.com/pubgo/lava/v2/servers/gatewayserver" -) - -var deprecateOnce sync.Once - -// Config is an alias of gatewayserver.Config (legacy grpc_server YAML key). -type Config = gatewayserver.Config - -// Params is an alias of gatewayserver.Params. -type Params = gatewayserver.Params - -// GrpcServerConfigLoader loads grpc_server YAML configuration (legacy). -type GrpcServerConfigLoader = gatewayserver.GrpcServerConfigLoader - -// CombinedConfigLoader is an alias of gatewayserver.CombinedConfigLoader. -type CombinedConfigLoader = gatewayserver.CombinedConfigLoader - -// New creates a grpc-server supervisor service (legacy name for gatewayserver). -// -// Deprecated: use gatewayserver.New for new code. -func New(params Params) supervisor.Service { - deprecateOnce.Do(func() { - log.Warn().Msg("servers/grpcs is deprecated; import servers/gatewayserver instead (removed in v3)") - }) - return gatewayserver.NewWithName(params, "grpc-server") -}