clawgo/docs/optimization/02-gateway-structure-split.md

02 Gateway 结构拆分

背景

cmd/cmd_gateway.go 当前同时承担 gateway 命令解析、服务注册、runtime 组装、热重载、API handler 注入、channel 生命周期、cron/heartbeat/sentinel 编排、bootstrap 初始化等职责。文件过大，后续修改容易产生回归。

目标

在不改变行为的前提下拆分 Gateway 代码结构，让每类职责有清晰文件边界。

建议改动范围

主要文件：

• cmd/cmd_gateway.go
• 新增 cmd/gateway_runtime.go
• 新增 cmd/gateway_reload.go
• 新增 cmd/gateway_services.go
• 新增 cmd/gateway_bootstrap.go

可选文件：

• cmd/reload_windows.go
• cmd/reload_unix.go
• cmd/signals_windows.go
• cmd/signals_unix.go

尽量避免修改：

• pkg/api/server.go
• pkg/agent/*
• pkg/providers/*
• pkg/channels/*

建议拆分

cmd/cmd_gateway.go

保留命令入口和高层流程：

• 参数分发。
• gateway run/start/stop/restart/status 分支。
• 前台 run 的主流程骨架。

cmd/gateway_runtime.go

放运行时组装：

• buildGatewayRuntime
• bindAgentLoopHandlers
• configureCronServiceRuntime
• buildHeartbeatService
• dispatchCronJob
• normalizeCronTargetChatID

cmd/gateway_reload.go

放热重载：

• config fingerprint。
• config watcher。
• reload trigger。
• runtimeSame 判断。
• reload 后重新绑定 API handler、channel、sentinel。

cmd/gateway_services.go

放系统服务注册/控制：

• Linux systemd。
• macOS launchd。
• Windows scheduled task。
• PID file stop。

cmd/gateway_bootstrap.go

放启动辅助任务：

• startup compaction check。
• bootstrap init。
• maximum permission policy。

验收标准

• 行为不变，命令仍可用：

  go run ./cmd gateway run --config ./config.json
  go run ./cmd gateway status --config ./config.json
  

• go test ./... 通过。

• cmd/cmd_gateway.go 明显变薄，职责聚焦于命令入口。

• 新文件命名和函数归属清晰。

• 没有引入循环依赖或跨 package 重构。

测试建议

go test ./cmd ./pkg/api ./pkg/channels ./pkg/agent
go test ./...

如果有本地配置，可额外手动验证：

go run ./cmd gateway run --config ./config.json

启动后修改配置文件，观察热重载日志是否仍正常。

并行注意

本任务应避免改 API 路由和 Provider 行为。若 API 文档任务并行进行，它只读 pkg/api/server.go，双方冲突较小。