mirror of
https://gitee.com/wujiawei1207537021/wu-lazy-cloud-network.git
synced 2026-02-04 15:05:54 +08:00
23 KiB
23 KiB
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 环境配置
# 下载并安装 JDK 24
# 设置 JAVA_HOME 环境变量
export JAVA_HOME=/path/to/jdk-24
export PATH=$JAVA_HOME/bin:$PATH
# 验证安装
java -version
javac -version
2. Maven 环境配置
# 下载并安装 Maven
# 设置 MAVEN_HOME 环境变量
export MAVEN_HOME=/path/to/maven
export PATH=$MAVEN_HOME/bin:$PATH
# 验证安装
mvn -version
3. IDE 配置
IntelliJ IDEA 配置:
- 安装 JDK 24
- 配置 Maven 设置
- 导入项目为 Maven 项目
- 配置代码风格和格式化规则
Eclipse 配置:
- 安装 Eclipse IDE for Enterprise Java Developers
- 配置 JDK 24
- 导入 Maven 项目
- 配置代码格式化规则
项目克隆
# 克隆项目
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开头
// 正确示例
public class NettyTcpServerSocketApplicationListener
public interface INettyAdapter
public abstract class AbstractNettyHandler
// 错误示例
public class nettyServer
public class NettyServer
方法命名:
- 使用 camelCase
- 方法名应该清晰表达其功能
- 布尔方法以
is、has、can开头
// 正确示例
public void startServer()
public boolean isConnected()
public boolean hasPermission()
// 错误示例
public void start_server()
public boolean connected()
变量命名:
- 使用 camelCase
- 常量使用 UPPER_SNAKE_CASE
- 避免使用单字母变量名
// 正确示例
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/ # 工具类
类结构:
// 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. 注释规范
类注释:
/**
* 服务端 TCP Socket 应用监听器
*
* 负责启动和管理服务端 TCP Socket 连接，处理客户端连接请求，
* 并提供内网穿透和代理功能。
*
* @author 吴佳伟
* @date 2024-01-01
* @version 1.3.1
*/
方法注释:
/**
* 启动 TCP 服务器
*
* 初始化 Netty 服务器，绑定指定端口，开始监听客户端连接。
* 如果启动失败，会抛出 RuntimeException。
*
* @param port 监听端口
* @throws RuntimeException 启动失败时抛出
*/
public void startTcpServer(int port) {
// 实现逻辑
}
变量注释:
/** 服务端端口 */
private int serverPort;
/** 客户端连接池 */
private final ConnectionPool connectionPool;
设计模式
1. 工厂模式
/**
* Netty 处理器工厂
*/
@Component
public class NettyHandlerFactory {
/**
* 创建 HTTP 代理处理器
*/
public NettyHttpProxyHandler createHttpProxyHandler() {
return new NettyHttpProxyHandler();
}
/**
* 创建 SOCKS 代理处理器
*/
public NettySocksProxyHandler createSocksProxyHandler() {
return new NettySocksProxyHandler();
}
}
2. 策略模式
/**
* 协议处理策略接口
*/
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. 观察者模式
/**
* 连接事件监听器
*/
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. 自定义异常
/**
* 网络连接异常
*/
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. 异常处理规范
/**
* 网络连接管理器
*/
@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. 测试框架
<!-- 测试依赖 -->
<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. 测试类结构
/**
* 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. 集成测试
/**
* 服务端集成测试
*/
@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 基准测试
/**
* 网络传输性能测试
*/
@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. 编译项目
# 清理并编译
mvn clean compile
# 运行测试
mvn test
# 打包
mvn package -DskipTests
# 安装到本地仓库
mvn install
2. 多模块构建
# 构建所有模块
mvn clean install -DskipTests
# 构建特定模块
mvn clean install -pl wu-lazy-cloud-heartbeat-server -am
# 跳过测试构建
mvn clean package -DskipTests
Docker 构建
1. 服务端 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
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. 开发环境部署
#!/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. 生产环境部署
#!/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. 开发环境日志
# 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. 生产环境日志
# 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 调试参数
# 服务端调试
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 调试
# 启动带调试端口的容器
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 集成
<!-- 添加 JProfiler 依赖 -->
<dependency>
<groupId>com.jprofiler</groupId>
<artifactId>jprofiler</artifactId>
<version>13.0</version>
<scope>provided</scope>
</dependency>
2. 内存分析
# 生成堆转储
jmap -dump:format=b,file=heap.hprof <pid>
# 分析堆转储
jhat heap.hprof
📚 学习资源
官方文档
推荐书籍
- 《Spring Boot 实战》
- 《Netty 实战》
- 《Java 并发编程实战》
在线资源
版本: 1.3.1-JDK24
更新时间: 2024年
维护者: 吴佳伟