# 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 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 org.springframework.boot spring-boot-starter-test test org.mockito mockito-core test org.mockito mockito-junit-jupiter test ``` #### 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 com.jprofiler jprofiler 13.0 provided ``` #### 2. 内存分析 ```bash # 生成堆转储 jmap -dump:format=b,file=heap.hprof # 分析堆转储 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年 **维护者**: 吴佳伟