Net Client Endpoint

Net Client Endpoint 主动连接远程 TCP/UDP 服务器，接收服务端推送的数据并路由到规则链处理。支持多协议、智能数据包分割、自动重连和心跳保活。适用于 IoT 设备对接上游服务器、数据采集客户端、网络协议代理客户端等场景。

# Type

endpoint/net_client

# 核心特性

# 🌐 多协议支持

TCP/UDP: 标准网络协议
TCP4/TCP6: 仅 IPv4/IPv6 的 TCP
UDP4/UDP6: 仅 IPv4/IPv6 的 UDP
Unix Socket: unix, unixpacket 本地通信

# 📦 智能数据包分割

line: 按行分割（\n 或 \r\n）- 默认模式
fixed: 固定长度分割
delimiter: 自定义分隔符（支持十六进制格式）
length_prefix: 长度前缀模式（支持大小端序、包含/不包含前缀长度）

# 🔄 自动重连

连接断开后，按配置的重连间隔自动尝试重新连接服务器，确保连接可靠性。

# 💓 心跳保活

支持定时发送心跳包，防止连接因空闲被断开。支持自定义心跳内容和十六进制格式。

# 启动配置

字段	类型	是否必填	说明	默认值
protocol	string	否	网络协议: tcp/tcp4/tcp6/udp/udp4/udp6/unix/unixpacket	tcp
server	string	是	远程服务器地址，格式为 host:port，如 "192.168.1.100:8080"	-
connectTimeout	int	否	连接超时时间（秒）	5
readTimeout	int	否	读取超时时间（秒），0 表示无超时	0
reconnectInterval	int	否	断线重连间隔（秒），0 表示不重连	5
encode	string	否	编码方式：hex/base64/none	none
packetMode	string	否	数据包分割模式	line
packetSize	int	否	数据包大小（根据模式含义不同）	0
delimiter	string	否	自定义分隔符（支持 0x0A 十六进制格式）	-
maxPacketSize	int	否	最大数据包大小，防止恶意攻击	64KB
heartbeatInterval	int	否	心跳发送间隔（秒），0 表示不发送心跳	0
heartbeatData	string	否	心跳包内容，支持十六进制格式如 "0x0D0A"，默认 "ping\n"	ping\n

# 数据包分割模式详解

# Line 模式（默认）

{
  "packetMode": "line"
}

1
2
3

适用于文本协议，按 \n 或 \r\n 分割消息。

# Fixed 模式

{
  "packetMode": "fixed",
  "packetSize": 16
}

1
2
3
4

固定长度数据包，适用于二进制协议。

# Delimiter 模式

{
  "packetMode": "delimiter",
  "delimiter": "0x0D0A"
}

1
2
3
4

自定义分隔符，支持十六进制格式。

# Length Prefix 模式

{
  "packetMode": "length_prefix_be",
  "packetSize": 2,
  "maxPacketSize": 4096
}

1
2
3
4
5

长度前缀协议，支持：

length_prefix_le: 小端序，长度不含前缀
length_prefix_be: 大端序，长度不含前缀
length_prefix_le_inc: 小端序，长度含前缀
length_prefix_be_inc: 大端序，长度含前缀

# 路由配置

通过路由的 From 表达式作为正则表达式匹配接收到的数据，匹配的数据将被路由到规则链处理。

// 简单配置：匹配所有数据
router := impl.NewRouter().From("").To("chain:main").End()
client.AddRouter(router)

// 带正则匹配
router := impl.NewRouter().From("^sensor.*").To("chain:sensor").End()
client.AddRouter(router)

1
2
3
4
5
6
7

# 完整配置示例

# 连接 TCP 服务器

{
  "id": "tcp_client",
  "type": "endpoint/net_client",
  "configuration": {
    "protocol": "tcp",
    "server": "192.168.1.100:8080",
    "connectTimeout": 5,
    "reconnectInterval": 5,
    "packetMode": "line"
  },
  "routers": [
    {
      "from": {
        "path": ".*"
      },
      "to": {
        "path": "chain:processData"
      }
    }
  ]
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

# 连接 UDP 服务器（带心跳）

{
  "id": "udp_client",
  "type": "endpoint/net_client",
  "configuration": {
    "protocol": "udp",
    "server": "192.168.1.100:9090",
    "reconnectInterval": 10,
    "heartbeatInterval": 30,
    "heartbeatData": "ping\n"
  },
  "routers": [
    {
      "from": {
        "path": ".*"
      },
      "to": {
        "path": "chain:udpHandler"
      }
    }
  ]
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

# 长度前缀协议客户端

{
  "id": "protocol_client",
  "type": "endpoint/net_client",
  "configuration": {
    "protocol": "tcp",
    "server": "192.168.1.100:8888",
    "packetMode": "length_prefix_be",
    "packetSize": 2,
    "maxPacketSize": 4096,
    "reconnectInterval": 3
  },
  "routers": [
    {
      "from": {
        "path": ".*"
      },
      "to": {
        "path": "chain:protocolHandler"
      }
    }
  ]
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

# Go 代码示例

config := engine.NewConfig()
client := &net.NetClient{}
client.Init(config, types.Configuration{
    "server":            "192.168.1.100:8080",
    "protocol":          "tcp",
    "packetMode":        "line",
    "reconnectInterval": 5,
})

router := impl.NewRouter().From("").Process(func(router endpoint.Router, exchange *endpoint.Exchange) bool {
    // 处理接收到的数据
    return true
}).End()
client.AddRouter(router)
client.Start()

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

# 应用场景

# 🏭 工业物联网

对接上游数据采集平台
PLC 设备数据上报
Modbus TCP 客户端

# 🌐 网络服务

TCP/UDP 代理客户端
协议转换网关下游
实时数据订阅

# 📡 设备接入

MQTT 客户端网关
心跳保活的长连接客户端
数据转发客户端

# 示例代码

参考完整示例：

Net Client 测试用例 (opens new window)

在 GitHub 上编辑此页

上次更新: 2026/05/13, 04:03:23

← Pulsar Endpoint Websocket Client Endpoint→