Initial commit
This commit is contained in:
@@ -0,0 +1,182 @@
|
||||
# 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: 清理空文件
|
||||
```bash
|
||||
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: 验证编译
|
||||
```bash
|
||||
go build ./cmd/meshray
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
*创建时间：2026-03-20*
|
||||
*版本：v2.1.0*
|
||||
*架构原则：connect 管建连，transport 管传输*
|
||||
Reference in New Issue
Block a user