wu-lazy-cloud-network/开发指南.md

# Wu-Lazy-Cloud-Network 开发指南

## 🛠️ 开发环境搭建

### 环境要求

#### 基础环境
- **操作系统**: Windows 10+ / macOS 10.15+ / Linux (Ubuntu 18.04+)
- **Java**: JDK 24 (推荐) 或 JDK 17+
- **Maven**: 3.6+ 
- **IDE**: IntelliJ IDEA 2023.1+ (推荐) 或 Eclipse 2023-03+
- **Git**: 2.30+

#### 数据库环境
- **MySQL**: 8.0+ (生产环境)
- **H2**: 2.1+ (开发环境)

#### 可选工具
- **Docker**: 20.10+ (容器化部署)
- **Docker Compose**: 2.0+ (多容器编排)
- **Postman**: API 测试工具

### 环境配置

#### 1. Java 环境配置

```bash
# 下载并安装 JDK 24
# 设置 JAVA_HOME 环境变量
export JAVA_HOME=/path/to/jdk-24
export PATH=$JAVA_HOME/bin:$PATH

# 验证安装
java -version
javac -version
```

#### 2. Maven 环境配置

```bash
# 下载并安装 Maven
# 设置 MAVEN_HOME 环境变量
export MAVEN_HOME=/path/to/maven
export PATH=$MAVEN_HOME/bin:$PATH

# 验证安装
mvn -version
```

#### 3. IDE 配置

**IntelliJ IDEA 配置**:
1. 安装 JDK 24
2. 配置 Maven 设置
3. 导入项目为 Maven 项目
4. 配置代码风格和格式化规则

**Eclipse 配置**:
1. 安装 Eclipse IDE for Enterprise Java Developers
2. 配置 JDK 24
3. 导入 Maven 项目
4. 配置代码格式化规则

### 项目克隆

```bash
# 克隆项目
git clone https://gitee.com/wujiawei1207537021/wu-lazy-cloud-network.git
cd wu-lazy-cloud-network

# 切换到开发分支
git checkout develop
```

## 📁 项目结构

### 目录结构

```
wu-lazy-cloud-network/
├── pom.xml                                    # 父模块 POM
├── README.md                                  # 项目说明
├── 项目说明文档.md                              # 详细项目说明
├── 使用文档.md                                 # 使用指南
├── 架构说明.md                                 # 架构文档
├── 开发指南.md                                 # 本文档
├── install.md                                 # 安装指南
├── Proxy.md                                   # 代理使用指南
├── version.md                                 # 版本更新记录
├── LICENSE                                    # 许可证
├── .gitignore                                 # Git 忽略文件
├── wu-lazy-cloud-heartbeat-common/           # 公共模块
│   ├── pom.xml
│   └── src/main/java/org/framework/lazy/cloud/network/heartbeat/common/
│       ├── adapter/                          # 适配器
│       ├── advanced/                         # 高级功能
│       ├── allocator/                        # 分配器
│       ├── constant/                         # 常量定义
│       ├── context/                          # 上下文
│       ├── decoder/                          # 解码器
│       ├── encoder/                          # 编码器
│       ├── enums/                            # 枚举
│       ├── factory/                          # 工厂类
│       ├── filter/                           # 过滤器
│       ├── pool/                             # 连接池
│       ├── socket/                           # Socket 相关
│       ├── state/                            # 状态管理
│       └── utils/                            # 工具类
├── wu-lazy-cloud-heartbeat-server/           # 服务端模块
│   ├── pom.xml
│   └── src/main/java/org/framework/lazy/cloud/network/heartbeat/server/
│       ├── cluster/                          # 集群功能
│       ├── config/                           # 配置类
│       ├── context/                          # 上下文
│       ├── init/                             # 初始化
│       ├── netty/                            # Netty 相关
│       ├── properties/                       # 属性配置
│       ├── standalone/                       # 单机模式
│       └── ui/                               # 用户界面
├── wu-lazy-cloud-heartbeat-client/           # 客户端模块
│   ├── pom.xml
│   └── src/main/java/org/framework/lazy/cloud/network/heartbeat/client/
│       ├── application/                      # 应用层
│       ├── config/                           # 配置类
│       ├── context/                          # 上下文
│       ├── controller/                       # 控制器
│       ├── domain/                           # 领域层
│       ├── infrastructure/                   # 基础设施层
│       ├── netty/                            # Netty 相关
│       ├── rpc/                              # RPC 相关
│       └── ui/                               # 用户界面
├── wu-lazy-cloud-heartbeat-dns/              # DNS 模块
│   ├── pom.xml
│   └── src/main/java/org/framework/lazy/cloud/network/heartbeat/protocol/
├── wu-lazy-cloud-heartbeat-protocol-proxy/   # 代理协议模块
│   ├── pom.xml
│   └── src/main/java/org/framework/lazy/cloud/network/heartbeat/protocol/
│       ├── actuator/                         # 执行器
│       ├── advanced/                         # 高级功能
│       ├── auth/                             # 认证
│       ├── config/                           # 配置
│       ├── context/                          # 上下文
│       ├── demo/                             # 示例
│       ├── filter/                           # 过滤器
│       ├── handler/                          # 处理器
│       ├── init/                             # 初始化
│       ├── log/                              # 日志
│       ├── properties/                       # 属性
│       ├── route/                            # 路由
│       ├── socket5/                          # SOCKS5
│       ├── token/                            # Token
│       └── utils/                            # 工具类
└── wu-lazy-cloud-heartbeat-start/            # 启动模块
    ├── pom.xml
    ├── wu-lazy-cloud-heartbeat-server-start/     # 服务端启动
    ├── wu-lazy-cloud-heartbeat-client-start/     # 客户端启动
    └── wu-lazy-cloud-heartbeat-server-cluster-start/  # 集群启动
```

### 核心包结构

#### 1. Common 模块 (wu-lazy-cloud-heartbeat-common)

**核心类**:
- `NettyMsg`: 网络消息基类
- `ChannelContext`: 通道上下文基类
- `NettyTransferChannelContext`: 传输通道上下文
- `NettyVisitorPortContext`: 访客端口上下文
- `NettyRealIdContext`: 真实连接上下文

**适配器**:
- `NettyAdapter`: 网络适配器接口
- `ProtocolAdapter`: 协议适配器接口

**工具类**:
- `NettyUtils`: Netty 工具类
- `ChannelUtils`: 通道工具类
- `ProtocolUtils`: 协议工具类

#### 2. Server 模块 (wu-lazy-cloud-heartbeat-server)

**核心类**:
- `NettyTcpServerSocketApplicationListener`: TCP 服务监听器
- `LazyServerPermeateServerMappingApplication`: 服务端渗透应用
- `NettyServerVirtualRouteApplication`: 虚拟路由应用

**配置类**:
- `ServerAutoConfiguration`: 服务端自动配置
- `ServerFlowConfiguration`: 流量控制配置

**初始化类**:
- `InitServerSocket`: 服务端 Socket 初始化
- `InitServerPermeateSocket`: 渗透 Socket 初始化
- `InitServerProxySocket`: 代理 Socket 初始化

#### 3. Client 模块 (wu-lazy-cloud-heartbeat-client)

**核心类**:
- `NettyClientSocketApplicationListener`: 客户端连接监听器
- `LazyClientPermeateClientMappingApplication`: 客户端渗透应用
- `NettyClientVirtualRouteApplication`: 客户端虚拟路由

**应用层**:
- `LazyNettyClientApplication`: 客户端应用服务
- `LazyNettyClientPermeateApplication`: 客户端渗透服务

**领域层**:
- `LazyNettyClient`: 客户端实体
- `LazyNettyClientPermeateMapping`: 客户端渗透映射

#### 4. Protocol Proxy 模块 (wu-lazy-cloud-heartbeat-protocol-proxy)

**核心类**:
- `NettyHttpProxySocketApplicationListener`: HTTP 代理监听器
- `NettySocketProxySocketApplicationListener`: SOCKS 代理监听器
- `NettyTcpProxyFilter`: TCP 代理过滤器

**协议处理**:
- `HttpProxyHandler`: HTTP 代理处理器
- `SocksProxyHandler`: SOCKS 代理处理器
- `ProxyAuthenticationHandler`: 代理认证处理器

## 🔧 开发规范

### 代码规范

#### 1. 命名规范

**类命名**:
- 使用 PascalCase
- 类名应该清晰表达其功能
- 接口以 `I` 开头，抽象类以 `Abstract` 开头

```java
// 正确示例
public class NettyTcpServerSocketApplicationListener
public interface INettyAdapter
public abstract class AbstractNettyHandler

// 错误示例
public class nettyServer
public class NettyServer
```

**方法命名**:
- 使用 camelCase
- 方法名应该清晰表达其功能
- 布尔方法以 `is`、`has`、`can` 开头

```java
// 正确示例
public void startServer()
public boolean isConnected()
public boolean hasPermission()

// 错误示例
public void start_server()
public boolean connected()
```

**变量命名**:
- 使用 camelCase
- 常量使用 UPPER_SNAKE_CASE
- 避免使用单字母变量名

```java
// 正确示例
private String serverHost;
private static final String DEFAULT_PORT = "8080";

// 错误示例
private String host;
private static final String port = "8080";
```

#### 2. 代码结构

**包结构**:
```
org.framework.lazy.cloud.network.heartbeat.{module}
├── application/          # 应用层
├── domain/              # 领域层
├── infrastructure/       # 基础设施层
├── config/              # 配置类
├── context/             # 上下文
├── handler/             # 处理器
├── filter/              # 过滤器
└── utils/               # 工具类
```

**类结构**:
```java
// 1. 包声明
package org.framework.lazy.cloud.network.heartbeat.server;

// 2. 导入语句
import lombok.extern.slf4j.Slf4j;
import org.springframework.stereotype.Component;

// 3. 类注释
/**
 * 服务端 TCP Socket 应用监听器
 * 
 * @author 吴佳伟
 * @date 2024-01-01
 */
@Slf4j
@Component
public class NettyTcpServerSocketApplicationListener {
    
    // 4. 常量定义
    private static final int DEFAULT_PORT = 7001;
    
    // 5. 成员变量
    private final EventLoopGroup bossGroup;
    private final EventLoopGroup workerGroup;
    
    // 6. 构造函数
    public NettyTcpServerSocketApplicationListener() {
        this.bossGroup = new NioEventLoopGroup();
        this.workerGroup = new NioEventLoopGroup();
    }
    
    // 7. 公共方法
    public void start() {
        // 实现逻辑
    }
    
    // 8. 私有方法
    private void initChannel() {
        // 实现逻辑
    }
}
```

#### 3. 注释规范

**类注释**:
```java
/**
 * 服务端 TCP Socket 应用监听器
 * 
 * 负责启动和管理服务端 TCP Socket 连接，处理客户端连接请求，
 * 并提供内网穿透和代理功能。
 * 
 * @author 吴佳伟
 * @date 2024-01-01
 * @version 1.3.1
 */
```

**方法注释**:
```java
/**
 * 启动 TCP 服务器
 * 
 * 初始化 Netty 服务器，绑定指定端口，开始监听客户端连接。
 * 如果启动失败，会抛出 RuntimeException。
 * 
 * @param port 监听端口
 * @throws RuntimeException 启动失败时抛出
 */
public void startTcpServer(int port) {
    // 实现逻辑
}
```

**变量注释**:
```java
/** 服务端端口 */
private int serverPort;

/** 客户端连接池 */
private final ConnectionPool connectionPool;
```

### 设计模式

#### 1. 工厂模式

```java
/**
 * Netty 处理器工厂
 */
@Component
public class NettyHandlerFactory {
    
    /**
     * 创建 HTTP 代理处理器
     */
    public NettyHttpProxyHandler createHttpProxyHandler() {
        return new NettyHttpProxyHandler();
    }
    
    /**
     * 创建 SOCKS 代理处理器
     */
    public NettySocksProxyHandler createSocksProxyHandler() {
        return new NettySocksProxyHandler();
    }
}
```

#### 2. 策略模式

```java
/**
 * 协议处理策略接口
 */
public interface ProtocolStrategy {
    void handle(Channel channel, Object message);
}

/**
 * HTTP 协议处理策略
 */
@Component
public class HttpProtocolStrategy implements ProtocolStrategy {
    @Override
    public void handle(Channel channel, Object message) {
        // HTTP 协议处理逻辑
    }
}

/**
 * SOCKS 协议处理策略
 */
@Component
public class SocksProtocolStrategy implements ProtocolStrategy {
    @Override
    public void handle(Channel channel, Object message) {
        // SOCKS 协议处理逻辑
    }
}
```

#### 3. 观察者模式

```java
/**
 * 连接事件监听器
 */
public interface ConnectionEventListener {
    void onConnect(Channel channel);
    void onDisconnect(Channel channel);
    void onError(Channel channel, Throwable cause);
}

/**
 * 连接事件管理器
 */
@Component
public class ConnectionEventManager {
    private final List<ConnectionEventListener> listeners = new ArrayList<>();
    
    public void addListener(ConnectionEventListener listener) {
        listeners.add(listener);
    }
    
    public void notifyConnect(Channel channel) {
        listeners.forEach(listener -> listener.onConnect(channel));
    }
}
```

### 异常处理

#### 1. 自定义异常

```java
/**
 * 网络连接异常
 */
public class NetworkConnectionException extends RuntimeException {
    
    public NetworkConnectionException(String message) {
        super(message);
    }
    
    public NetworkConnectionException(String message, Throwable cause) {
        super(message, cause);
    }
}

/**
 * 协议解析异常
 */
public class ProtocolParseException extends RuntimeException {
    
    public ProtocolParseException(String message) {
        super(message);
    }
    
    public ProtocolParseException(String message, Throwable cause) {
        super(message, cause);
    }
}
```

#### 2. 异常处理规范

```java
/**
 * 网络连接管理器
 */
@Component
public class NetworkConnectionManager {
    
    /**
     * 建立连接
     */
    public Channel connect(String host, int port) {
        try {
            // 连接逻辑
            return establishConnection(host, port);
        } catch (ConnectException e) {
            log.error("连接失败: {}:{}", host, port, e);
            throw new NetworkConnectionException("无法连接到服务器: " + host + ":" + port, e);
        } catch (Exception e) {
            log.error("连接过程中发生未知错误: {}:{}", host, port, e);
            throw new NetworkConnectionException("连接过程中发生未知错误", e);
        }
    }
    
    /**
     * 安全关闭连接
     */
    public void safeClose(Channel channel) {
        if (channel != null && channel.isActive()) {
            try {
                channel.close().sync();
            } catch (Exception e) {
                log.warn("关闭连接时发生错误", e);
            }
        }
    }
}
```

## 🧪 测试规范

### 单元测试

#### 1. 测试框架

```xml
<!-- 测试依赖 -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-test</artifactId>
    <scope>test</scope>
</dependency>
<dependency>
    <groupId>org.mockito</groupId>
    <artifactId>mockito-core</artifactId>
    <scope>test</scope>
</dependency>
<dependency>
    <groupId>org.mockito</groupId>
    <artifactId>mockito-junit-jupiter</artifactId>
    <scope>test</scope>
</dependency>
```

#### 2. 测试类结构

```java
/**
 * Netty 客户端连接测试
 */
@ExtendWith(MockitoExtension.class)
class NettyClientConnectionTest {
    
    @Mock
    private NettyClientProperties properties;
    
    @Mock
    private LazyLambdaStream lazyLambdaStream;
    
    @InjectMocks
    private NettyClientSocketApplicationListener listener;
    
    @Test
    @DisplayName("客户端连接成功")
    void testClientConnectionSuccess() {
        // Given
        when(properties.getInetHost()).thenReturn("127.0.0.1");
        when(properties.getInetPort()).thenReturn(7001);
        
        // When
        listener.doRunning();
        
        // Then
        verify(lazyLambdaStream, times(1)).findList(any());
    }
    
    @Test
    @DisplayName("客户端连接失败")
    void testClientConnectionFailure() {
        // Given
        when(properties.getInetHost()).thenReturn("invalid-host");
        
        // When & Then
        assertThrows(NetworkConnectionException.class, () -> {
            listener.doRunning();
        });
    }
}
```

#### 3. 集成测试

```java
/**
 * 服务端集成测试
 */
@SpringBootTest
@TestPropertySource(properties = {
    "spring.lazy.netty.server.mode=standalone",
    "spring.lazy.netty.server.node-port=7001"
})
class ServerIntegrationTest {
    
    @Autowired
    private NettyTcpServerSocketApplicationListener serverListener;
    
    @Test
    @DisplayName("服务端启动成功")
    void testServerStartup() {
        // Given & When
        serverListener.doRunning();
        
        // Then
        assertTrue(serverListener.isRunning());
    }
}
```

### 性能测试

#### 1. JMH 基准测试

```java
/**
 * 网络传输性能测试
 */
@BenchmarkMode(Mode.Throughput)
@OutputTimeUnit(TimeUnit.SECONDS)
@State(Scope.Benchmark)
public class NetworkTransferBenchmark {
    
    private NettyTransferChannelContext transferContext;
    
    @Setup
    public void setup() {
        transferContext = new NettyTransferChannelContext();
    }
    
    @Benchmark
    public void testDataTransfer() {
        // 数据传输测试逻辑
        transferContext.transfer(createTestData());
    }
    
    private byte[] createTestData() {
        return "test data".getBytes();
    }
}
```

## 📦 构建和部署

### Maven 构建

#### 1. 编译项目

```bash
# 清理并编译
mvn clean compile

# 运行测试
mvn test

# 打包
mvn package -DskipTests

# 安装到本地仓库
mvn install
```

#### 2. 多模块构建

```bash
# 构建所有模块
mvn clean install -DskipTests

# 构建特定模块
mvn clean install -pl wu-lazy-cloud-heartbeat-server -am

# 跳过测试构建
mvn clean package -DskipTests
```

### Docker 构建

#### 1. 服务端 Dockerfile

```dockerfile
FROM registry.cn-hangzhou.aliyuncs.com/wu-lazy/wu-framework-parent:jdk-24-x64
MAINTAINER wujiawei <1207537021@qq.com>

RUN echo "Asia/Shanghai" > /etc/timezone

ENV APP_JAR_NAME=$APP_NAME \
    JAVA_OPTS="-Xms512m -Xmx1024m -XX:+UseContainerSupport -XX:InitialRAMPercentage=50.0 -XX:MaxRAMPercentage=80.0 -Djdk.management.jfr.VmFlagRepository.useCgroups=false -Djava.security.egd=file:/dev/./urandom" \
    PARAMS=""

COPY target/*.jar /app.jar

ENTRYPOINT exec java -server $JAVA_OPTS -jar /app.jar $PARAMS
```

#### 2. 客户端 Dockerfile

```dockerfile
FROM registry.cn-hangzhou.aliyuncs.com/wu-lazy/wu-framework-parent:jdk-24-x64
MAINTAINER wujiawei <1207537021@qq.com>

RUN echo "Asia/Shanghai" > /etc/timezone

ENV APP_JAR_NAME=$APP_NAME \
    JAVA_OPTS="-Xms512m -Xmx1024m -XX:+UseContainerSupport -XX:InitialRAMPercentage=50.0 -XX:MaxRAMPercentage=80.0 -Djdk.management.jfr.VmFlagRepository.useCgroups=false -Djava.security.egd=file:/dev/./urandom" \
    PARAMS=""

COPY target/*.jar /app.jar

ENTRYPOINT exec java -server $JAVA_OPTS -jar /app.jar $PARAMS
```

### 部署脚本

#### 1. 开发环境部署

```bash
#!/bin/bash
# deploy-dev.sh

echo "开始部署开发环境..."

# 编译项目
mvn clean package -DskipTests

# 启动服务端
cd wu-lazy-cloud-heartbeat-start/wu-lazy-cloud-heartbeat-server-start
nohup java -jar target/wu-lazy-cloud-heartbeat-server-start-1.3.1-JDK24.jar > server.log 2>&1 &

# 启动客户端
cd ../wu-lazy-cloud-heartbeat-client-start
nohup java -jar target/wu-lazy-cloud-heartbeat-client-start-1.3.1-JDK24.jar > client.log 2>&1 &

echo "部署完成！"
```

#### 2. 生产环境部署

```bash
#!/bin/bash
# deploy-prod.sh

echo "开始部署生产环境..."

# 构建 Docker 镜像
docker build -t wlcn-server:latest wu-lazy-cloud-heartbeat-start/wu-lazy-cloud-heartbeat-server-start/
docker build -t wlcn-client:latest wu-lazy-cloud-heartbeat-start/wu-lazy-cloud-heartbeat-client-start/

# 停止旧容器
docker stop wlcn-server wlcn-client || true
docker rm wlcn-server wlcn-client || true

# 启动新容器
docker run -d --name wlcn-server -p 6001:6001 -p 7001:7001 -p 8001:8001 -p 9001:9001 wlcn-server:latest
docker run -d --name wlcn-client --privileged -p 6004:6004 wlcn-client:latest

echo "部署完成！"
```

## 🔍 调试技巧

### 日志配置

#### 1. 开发环境日志

```yaml
# application-dev.yml
logging:
  level:
    org.framework.lazy.cloud.network.heartbeat: DEBUG
    io.netty: DEBUG
    root: INFO
  pattern:
    console: "%d{yyyy-MM-dd HH:mm:ss} [%thread] %-5level %logger{36} - %msg%n"
    file: "%d{yyyy-MM-dd HH:mm:ss} [%thread] %-5level %logger{36} - %msg%n"
  file:
    name: logs/wlcn-dev.log
```

#### 2. 生产环境日志

```yaml
# application-prod.yml
logging:
  level:
    org.framework.lazy.cloud.network.heartbeat: INFO
    io.netty: WARN
    root: WARN
  pattern:
    console: "%d{yyyy-MM-dd HH:mm:ss} [%thread] %-5level %logger{36} - %msg%n"
    file: "%d{yyyy-MM-dd HH:mm:ss} [%thread] %-5level %logger{36} - %msg%n"
  file:
    name: logs/wlcn-prod.log
    max-size: 100MB
    max-history: 30
```

### 远程调试

#### 1. JVM 调试参数

```bash
# 服务端调试
java -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=5005 \
     -jar wu-lazy-cloud-heartbeat-server-start-1.3.1-JDK24.jar

# 客户端调试
java -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=5006 \
     -jar wu-lazy-cloud-heartbeat-client-start-1.3.1-JDK24.jar
```

#### 2. Docker 调试

```bash
# 启动带调试端口的容器
docker run -d -p 6001:6001 -p 7001:7001 -p 5005:5005 \
  -e JAVA_OPTS="-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5005" \
  --name wlcn-server-debug wlcn-server:latest
```

### 性能分析

#### 1. JProfiler 集成

```xml
<!-- 添加 JProfiler 依赖 -->
<dependency>
    <groupId>com.jprofiler</groupId>
    <artifactId>jprofiler</artifactId>
    <version>13.0</version>
    <scope>provided</scope>
</dependency>
```

#### 2. 内存分析

```bash
# 生成堆转储
jmap -dump:format=b,file=heap.hprof <pid>

# 分析堆转储
jhat heap.hprof
```

## 📚 学习资源

### 官方文档
- [Spring Boot 官方文档](https://spring.io/projects/spring-boot)
- [Netty 官方文档](https://netty.io/)
- [Lazy ORM 文档](https://gitee.com/wujiawei1207537021/wu-framework-parent)

### 推荐书籍
- 《Spring Boot 实战》
- 《Netty 实战》
- 《Java 并发编程实战》

### 在线资源
- [Spring Boot 教程](https://spring.io/guides)
- [Netty 教程](https://netty.io/wiki/)
- [Java 并发编程](https://docs.oracle.com/javase/tutorial/essential/concurrency/)

---

**版本**: 1.3.1-JDK24  
**更新时间**: 2024年  
**维护者**: 吴佳伟