Meshray-Manager/docs/core 分层架构与文件组织.md

Core 模块分层架构与文件组织规范

🎯 职责分工

connect/ - 连接工厂层（对外建立连接）

职责：对外与 Peer 建立各种类型的网络连接，返回标准的 net.Conn 接口。

关键特性：

• 实现 9 层降级传输策略
• 每层独立的连接工厂（Factory）
• 所有工厂实现统一的 TransportFactory 接口
• 通过 StrategyScheduler 管理优先级和自动降级

文件组织（9 个独立工厂）：

connect/
├── strategy.go           # 策略调度器（核心）
│   ├── StrategyScheduler    # 管理 9 层工厂的优先级
│   ├── TransportFactory     # 统一接口：Dial() net.Conn
│   └── Layer                # 9 层枚举
│
├── ice.go                # ICE 协商（辅助功能）
│
├── direct_udp.go         # Direct-UDP 工厂 ⏳ 待从 fake_tcp.go 拆分
├── fake_tcp.go           # Direct-FakeTCP 工厂 ✅
├── real_tcp.go           # Direct-RealTCP 工厂 ✅
│
├── turn_udp.go           # TURN-UDP 工厂 ✅ (已重命名)
├── turn_tcp.go           # TURN-TCP 工厂 ⏳ 待从 turn_udp.go 拆分
├── turn_tls.go           # TURN-TLS 工厂 ⏳ 待从 turn_udp.go 拆分
├── turn_quic.go          # TURN-QUIC 工厂 ✅
│
├── webrtc.go             # WebRTC 工厂 ⏳ 待创建
└── ws.go                 # WS/WSS 工厂 ✅ (已重命名)

为什么叫 connect：

• 词源：Connect to peer（连接到对端）
• 职责：建立网络连接
• 抽象层次：网络层（Network Layer）+ 传输层（Transport Layer）

---

transport/ - 传输绑定层（对内对接 WireGuard）

职责：对内将建立的连接暴露给 WireGuard 使用，实现 conn.Bind 接口。

关键特性：

• 不关心具体的建连方式（UDP/TCP/TURN）
• 只使用 net.Conn 接口
• 负责 WireGuard 数据包的 Read/Write
• 管理 Peer 连接的生命周期

文件组织（2 个核心组件）：

transport/
├── core_bind.go          # WireGuard Bind 实现
│   └── CoreBind             # 实现 conn.Bind 接口
│       ├── Write(buffers)     # 写入 WireGuard 数据包
│       ├── Read(buffer)       # 读取 WireGuard 数据包
│       └── Dial(peerID)       # 使用 connect.Scheduler 建连
│
└── relay.go              # 数据中继器
    └── Relay                # 基于 net.Conn 的透明转发
        ├── RegisterFactory()  # 注册传输工厂
        ├── GetConnection()    # 获取已建立的连接
        └── Forward()          # 透明读写转发

为什么叫 transport：

• 词源：Transport WireGuard packets（传输 WireGuard 数据包）
• 职责：传输应用层数据（WireGuard 密文）
• 抽象层次：绑定层（Bind Layer）- WireGuard 专有概念

---

📊 完整数据流

[WireGuard 内核态]
    ↓ Write(buffers, size, offset)
    ↓ "发送加密数据包"
    
[transport/CoreBind]
    ↓ 检查是否有 Peer 的连接
    ↓ 如果没有 → 调用 Scheduler.Dial()
    ↓ 如果有 → 直接使用现有 net.Conn
    ↓ conn.Write(packet)
    
[connect/StrategyScheduler]
    ↓ 按优先级尝试 9 层工厂
    ↓ Layer1: Direct-UDP.Dial()
    ↓ 失败 → Layer2: FakeTCP.Dial()
    ↓ 失败 → Layer3: RealTCP.Dial()
    ↓ ...
    ↓ 成功 → 返回 net.Conn
    
[底层网络 Socket]
    ↓ UDP Socket.Send()
    ↓ TCP Socket.Connect() + Send()
    ↓ TURN Server.Allocate() + Send()

---

🔧 当前状态 vs 目标状态

Connect 目录（连接工厂层）

当前文件	目标文件名	状态	说明
strategy.go	strategy.go	✅	策略调度器
ice.go	ice.go	✅	ICE 协商
fake_tcp.go	direct_udp.go	🔄	需要拆分出 Direct-UDP
fake_tcp_factory.go	合并到 fake_tcp.go	🔄	空文件，可删除
real_tcp.go	real_tcp.go	✅	RealTCP
real_tcp_factory.go	合并到 real_tcp.go	🔄	空文件，可删除
turn_udp.go	turn_udp.go	✅	已重命名
turn_tcp.go	turn_tcp.go	⏳	待从 turn_udp.go 拆分
turn_tls.go	turn_tls.go	⏳	待从 turn_udp.go 拆分
turn_quic.go	turn_quic.go	✅	QUIC 扩展
webrtc.go	webrtc.go	⏳	待创建
ws.go	ws.go	✅	已重命名
stun.go	stun.go	✅	STUN 探测（辅助）

Transport 目录（传输绑定层）

当前文件	目标文件名	状态	说明
core_bind.go	core_bind.go	✅	WireGuard Bind
relay.go	relay.go	✅	数据中继
intercept.go	❌ 已删除	✅	废弃（被 CoreBind 替代）

---

✅ 重构原则

1. 保持 9 层独立性

• ❌ 不要合并不同层的工厂（如 P2P 工厂）
• ✅ 每层对应一个文件（如 turn_udp.go, turn_tcp.go）
• ✅ 每层实现统一的接口（TransportFactory）

2. 文件名语义化

• ✅ {layer}.go - 直接体现传输层类型
• ✅ {layer}_factory.go - 强调工厂模式（可选）
• ❌ 避免模糊的名称（如 p2p_factory.go 包含 3 层）

3. 职责分离

• ✅ connect/ 负责建立连接（Dial）
• ✅ transport/ 负责使用连接（Read/Write）
• ❌ 不要混淆两者的边界

---

📝 下一步行动

Phase 1: 清理空文件

rm core/connect/fake_tcp_factory.go
rm core/connect/real_tcp_factory.go

Phase 2: 拆分 TURN 工厂

• 从 turn_udp.go 中拆分出：
  • turn_tcp.go - TURN-TCP 工厂
  • turn_tls.go - TURN-TLS 工厂

Phase 3: 补充缺失的层

• 创建 direct_udp.go - Direct-UDP 工厂
• 创建 webrtc.go - WebRTC 工厂

Phase 4: 验证编译

go build ./cmd/meshray

---

创建时间：2026-03-20
版本：v2.1.0
架构原则：connect 管建连，transport 管传输