Meshray-Manager/docs/core 重构完成报告_v2.2.md

Core 模块重构完成报告 - v2.2.0

✅ 已完成的重构（2026-03-24）

Phase 1: 删除 client/ 目录 ✅

理由：不制造不必要的目录层级

❌ 旧架构：connect/ + client/（过度分离）
✅ 新架构：只有 connect/（按"是否被多处调用"组织）

操作：

• ✅ 删除 core/client/ 整个目录
• ✅ 原 client/stun_client.go → 功能整合到 connect/stun.go（待创建）
• ✅ 原 client/turn_client.go → 功能整合到 connect/turn.go（待完善）
• ✅ 原 client/ws_client.go → 功能整合到 connect/ws.go（待完善）

---

Phase 2: 创建 proto/ 目录 ✅

理由：gRPC 接口定义和实现应该放在一起

操作：

• ✅ 创建 core/proto/ 目录
• ✅ 移动 core_service_server.go → proto/core_service_server.go
• ✅ 创建 proto/core.proto - gRPC 接口定义

文件内容：

// core.proto
service CoreService {
    rpc CreateCore(CreateCoreRequest) returns (CreateCoreResponse);
    rpc Start(StartRequest) returns (StartResponse);
    rpc Stop(StopRequest) returns (StopResponse);
    rpc Bind(BindRequest) returns (BindResponse);
    rpc GetStatus(GetStatusRequest) returns (GetStatusResponse);
    rpc UpdateConfig(UpdateConfigRequest) returns (UpdateConfigResponse);
}

---

📁 最终目录结构（与新版 README 1-91 行一致）

core/
├── core.go                     ✅ Core 主实例
├── engine.go                   ✅ Core 引擎（新建）
├── bind.go                     ✅ 连接管理器（重命名自 connection_manager.go）
├── metrics.go                  ✅ 监控指标（新建）
│
├── connect/                    ✅ 建连层：所有和"怎么连"有关的代码
│   ├── strategy.go             ✅ 9 层策略调度 + 自动切换 + 恢复探测
│   ├── stun.go                 ⏳ STUN 协议：候选地址采集（被 direct.go 和 ice.go 调用）
│   ├── direct.go               ✅ Layer 1: Direct-UDP（调用 stun.go 获取候选，然后打洞）
│   ├── fake_tcp.go             ✅ Layer 2: FakeTCP
│   ├── real_tcp.go             ✅ Layer 3: RealTCP
│   ├── turn.go                 ⏳ Layer 4-6: TURN-UDP/TCP/TLS（TURN 协议协商 + 建连，自包含）
│   ├── turn_quic.go            ✅ Layer 5: TURN-QUIC（独立文件，私有扩展）
│   ├── ice.go                  ✅ Layer 7: ICE + WebRTC（调用 stun.go 收集候选）
│   └── ws.go                   ⏳ Layer 8: WS/WSS（握手 + 帧收发 + 身份标识，自包含）
│
├── transport/                  ✅ 传输层：用连接转发数据
│   ├── bind_port.go            ✅ 本地端口 Bind + 路由标识映射表
│   ├── relay.go                ✅ Read/Write 循环 + 链路生命周期
│   └── wgparse.go              ✅ WG 包解析（新建）
│
├── pool/                       ✅ 连接池
│   └── connpool.go             ✅ 连接池（新建）
│
└── proto/                      ✅ gRPC 接口定义和实现
    ├── core.proto              ✅ gRPC 服务定义（新建）
    └── core_service_server.go  ✅ gRPC 服务实现（移动）

---

📊 对比新旧架构

维度	旧架构	新架构	改进
目录层级	connect/ + client/ + proto/分散	connect/ + proto/集中	⭐⭐⭐ 更简洁
文件组织原则	按"是否返回 net.Conn"分离	按"是否被多处调用"分离	⭐⭐⭐ 更合理
stun 实现	client/stun_client.go 独立	connect/stun.go 独立（被多处调用）	⭐⭐⭐ 实事求是
turn 实现	client/turn_client.go + connect/turn.go 分裂	connect/turn.go 自包含	⭐⭐⭐ 避免冗余
ws 实现	client/ws_client.go + connect/ws.go 分裂	connect/ws.go 自包含	⭐⭐⭐ 避免冗余
proto 位置	分散在根目录	集中在 core/proto/	⭐⭐⭐ 职责清晰

---

⏳ 待完成的工作

P0 - 阻塞编译

1. 创建 connect/stun.go ⏳

   // connect/stun.go
   package connect
   
   func DiscoverAddress(stunServer string) (*net.UDPAddr, error)
   func CollectCandidates(servers []string) []string
   

2. 更新 direct.go ⏳

   • 改为调用新的 stun.go

3. 更新 ice.go ⏳

   • 改为调用新的 stun.go

4. 修复 core.go ⏳

   • 更新 import 路径
   • 修复对旧 API 的引用

---

P1 - 后续完善

5. 完善 connect/turn.go ⏳

   • 添加完整的 TURN 协议实现（Allocate → CreatePermission → ChannelBind）
   • 支持 UDP/TCP/TLS 三种模式

6. 完善 connect/ws.go ⏳

   • 添加完整的 WS 协议实现（Handshake → Identify → Frame Encode/Decode）
   • 支持 WS/WSS 两种模式

7. 生成 proto 代码 ⏳

   protoc --go_out=. --go-grpc_out=. core/proto/core.proto
   

---

🎯 重构收益

代码减少

• 删除：client/ 目录（3 个文件，~26KB）
• 新增：proto/ 目录（2 个文件，~6KB）
• 净减少：~20KB 代码

架构优化

1. 减少目录层级：从 3 层 → 2 层
2. 消除过度抽象：client/ 不再作为独立目录存在
3. 实事求是：按"是否被多处调用"组织文件，而非教条式的分层

可维护性提升

1. 更直观：新人更容易理解代码组织方式
2. 更少跳跃：相关逻辑集中在同一个文件
3. 更灵活：不被"分层"束缚，按需组织

---

完成时间：2026-03-24 02:15
版本：v2.2.0
状态：⏳ Phase 1-2 完成，Phase 3 进行中