net.connect

net.connect

功能

建立 TCP、UDP 或 WebSocket 客户端连接。

语法

参数

参数	类型	必填	默认值	说明
config	Object	是	无	连接配置对象。公共字段和协议字段见下方。

连接配置字段

字段	类型	适用 type	必填	默认值	说明
type	String	全部	是	无	连接协议类型。可选值为 `tcp`、`udp`、`ws`。
host	String	tcp/udp	是	无	远端主机名或 IP 地址，例如 `127.0.0.1`、`example.com`。
port	Int	tcp/udp	是	无	远端端口号，范围为 0 到 65535。
timeout	Int	tcp	否	`0`	TCP 连接、读写超时时间，单位毫秒；小于等于 0 表示不设置超时。
url	String	ws	是	无	WebSocket 完整连接地址，例如 `ws://127.0.0.1:9002/ws`。

返回值

类型	说明
TcpClient/UdpSocket/WsSocket	按 `type` 返回对应连接句柄。

连接句柄字段

字段	类型	说明
addr	String	连接目标或本地 socket 地址，格式通常为 `host:port`。
type	String	连接类型。TCP 返回 `tcp`，UDP 返回 `udp`，WebSocket 返回 `ws`。

连接句柄方法

类型	方法	返回值	说明
TcpClient	write(data) / send(data)	Int	写入 TCP String、字节数组或 Bytes，返回写入字节数。
TcpClient	read()	String	同步读取一段 TCP 数据，按 UTF-8 lossy 转为字符串。
TcpClient	read_bytes()	Bytes	同步读取一段 TCP 原始字节。
TcpClient	close()	Bool	关闭 TCP 连接。
UdpSocket	send(data)	Int	向 connect 配置中的默认远端地址发送 UDP 数据，返回发送字节数。
UdpSocket	send(data, addr)	Int	向指定 `host:port` 发送 UDP 数据，返回发送字节数。
UdpSocket	close()	Bool	关闭 UDP socket。
WsSocket	send(data) / write(data)	Bool	发送 WebSocket 消息；String 为文本帧，Bytes 或字节数组为二进制帧。
WsSocket	close()	Bool	关闭 WebSocket 连接。
WsSocket	on_message(fn(message) {}, binary)	WsSocket	注册 WebSocket 客户端消息回调；第二个参数为 true 时 message 为 Bytes。
WsSocket	on_close(fn() {})	WsSocket	注册 WebSocket 客户端关闭回调。
WsSocket	on_error(fn(message) {})	WsSocket	注册 WebSocket 客户端错误回调。

示例

注意事项

TCP 和 UDP 使用 host、port 字段；WebSocket 使用完整 url 字段。
WebSocket 不支持同步 read()；请通过 on_message() 接收消息。
需要接收二进制消息时，TCP 可使用 read_bytes()，监听回调可在 net.listen 配置中设置 binary: true。