TCP 编程

本章导读

TCP 提供可靠、有序、面向连接的字节流传输。与 HTTP 不同，TCP 没有"请求-响应"的语义——它只是一根双向管道，你发什么对方收什么，消息边界需要你自己定义（长度前缀、分隔符、固定长度等）。xlang 的 TCP API 封装在 tcp 命名空间和 TcpServer、TcpStream 两个类型中。

45.1 监听与接受连接

TCP 服务器的第一步是监听端口：

// 创建 TCP 服务器——端口 0 = 系统自动分配
TcpServer server = TcpServer(tcp.listen(0))
int port = int(server.port())
println("监听端口: " + port.toString())

// 接受连接（异步）
future<point> accepted = server.acceptAsync(8000)  // 超时 8 秒
point peerHandle = await accepted
TcpStream peer = TcpStream(peerHandle)
println("客户端已连接")

tcp.listen(port) 返回一个原始句柄（point），用 TcpServer() 包装后获得面向对象接口。acceptAsync(timeout) 异步等待一个客户端连接，返回 future<point>。

45.2 建立连接

客户端用 tcp.connect 连接服务器：

// 同步连接——阻塞直到连接建立或超时
TcpStream client = TcpStream(tcp.connect("127.0.0.1", port, 8000))
println("已连接到服务器")

// 异步连接——不阻塞当前线程
future<point> connectFuture = tcp.connectAsync("127.0.0.1", port, 8000)
TcpStream asyncClient = TcpStream(await connectFuture)

tcp.connect(host, port, timeout) 的三个参数：目标地址、目标端口、超时毫秒。连接失败（超时、拒绝）时返回 null 句柄。

45.3 文本收发：send/recv

最简单的数据交换——字符串形式：

// 客户端发送
bool sent = client.send("ping")
bool drained = client.drain(8000)   // 等待数据实际发出

// 服务端接收
string message = peer.recv(8000)    // 阻塞等待数据，超时 8 秒
println("收到: " + message)         // "ping"

// 服务端回复
peer.send("pong")
peer.drain(3000)

// 客户端接收回复
string reply = client.recv(8000)
println("回复: " + reply)           // "pong"

关键要点：

• send(s) 将字符串写入发送缓冲区，返回是否成功
• recv(timeout) 阻塞等待对端数据，返回收到的字符串
• TCP 是字节流——一次 send 的数据可能被对端分多次 recv 收到，也可能多次 send 被合并为一次 recv 收到（粘包/拆包）

45.4 二进制收发：sendBytes/recvBytes

传输非文本数据（图片、协议帧、序列化结构）时使用二进制接口：

// 构建二进制数据
Buffer data = Buffer()
data.appendByte(0)      // 消息类型
data.appendByte(1)      // 版本
data.appendByte(128)    // 载荷长度高位
data.appendByte(255)    // 载荷长度低位

// 发送二进制
bool sent = client.sendBytes(data.data(), c_size(data.len()))
client.drain(8000)

// 接收二进制
Buffer received = peer.recvBytes(8000)
println("收到 " + received.len().toString() + " 字节")
println("第一字节: " + received[0].toString())   // 0
println("最后字节: " + received[3].toString())   // 255

sendBytes(ptr, size) 接受原始指针和长度；recvBytes(timeout) 返回 Buffer 对象，可以按索引访问每个字节。

45.5 drain：确保数据发完

send 只是将数据写入操作系统的发送缓冲区，不保证数据已经到达对端。drain 等待缓冲区清空：

client.send("important data")
bool ok = client.drain(8000)   // 等待数据实际发送到网络
if not ok then
    println("发送超时或连接断开")
end

什么时候需要 drain？

• 发送后紧跟 close()——不 drain 可能丢数据
• 需要确认数据已发出（如协议握手的 ACK）
• 发送大量数据后检查是否阻塞

45.6 异步 TCP 操作

同步 API 会阻塞线程。高并发场景使用异步版本：

// 异步接受连接
TcpServer server = TcpServer(tcp.listen(0))
int port = int(server.port())
future<point> acceptFuture = server.acceptAsync(8000)

// 异步建立连接
future<point> connectFuture = tcp.connectAsync("127.0.0.1", port, 8000)

// 等待双方就绪
TcpStream client = TcpStream(await connectFuture)
TcpStream peer = TcpStream(await acceptFuture)

// 异步接收（先发起）
future<string> recvFuture = peer.recvAsync(8000)

// 异步发送
bool sent = await client.sendAsync("async hello")
bool drained = await client.drainAsync(8000)

// 等待接收完成
string message = await recvFuture
println("异步收到: " + message)   // "async hello"

client.close()
peer.close()

异步 API 对照表：

45.7 连接与监听配置

高级场景需要调整套接字选项：

// 连接配置
TcpConnectConfig connectCfg = tcp.connectConfig("127.0.0.1", 65535)
connectCfg.flags(tcp.connectNoDelay + tcp.connectKeepAlive)
// NoDelay：禁用 Nagle 算法，减少小包延迟
// KeepAlive：启用 TCP 保活探测

// 监听配置
TcpListenConfig listenCfg = tcp.listenConfig(0, "127.0.0.1")
listenCfg.flags(tcp.listenReuseAddr + tcp.listenReusePort + tcp.listenNoDelay + tcp.listenKeepAlive)
// ReuseAddr：允许绑定 TIME_WAIT 状态的地址
// ReusePort：允许多个进程/线程绑定同一端口（负载均衡）

45.8 域名解析与网络工具

net 命名空间提供网络辅助功能：

// 域名解析
NetAddress addr = net.resolve("localhost", 80)
println("解析结果: " + addr.text())   // "127.0.0.1"
println("端口: " + addr.port.toString())  // 80

// 本机网络信息
string ip = net.localIP()       // 本机 IP
string mac = net.localMAC()     // 本机 MAC 地址
string name = net.localName()   // 主机名

// 代理配置
NetProxy noProxy = net.proxy(net.proxyNone, "127.0.0.1", 0)
NetProxy socks = net.proxy(net.proxySocks5, "127.0.0.1", 1080)
NetProxy httpProxy = net.proxy(net.proxyHttpConnect, "127.0.0.1", 8080)

// 关闭标志
// net.closeAbort = 1     立即关闭（发 RST）
// net.closeGraceful = 2  优雅关闭（发 FIN）
// net.closeWaitPeer = 4  等待对端关闭

45.9 网络引擎 NetEngine

NetEngine 是底层网络事件循环，通常由标准库自动管理。高级用户可以显式控制：

// 创建网络引擎：1 个 I/O 线程，0 = 自动工作线程数
NetEngine engine = net.engine(1, net.engineAutoWorkers)

// 启动
assert engine.start()

// ... 执行网络操作 ...

// 停止
engine.stop()

大多数应用不需要手动管理 NetEngine——tcp.connect、tcp.listen 等 API 内部会自动使用全局引擎。只有在需要隔离网络资源或精确控制线程数时才显式创建。

45.10 实战：Echo 服务器

把前面的知识组合成一个完整的 Echo 服务器——收到什么就回什么：

// === Echo 服务器 ===
TcpServer server = TcpServer(tcp.listen(0))
int port = int(server.port())
println("Echo 服务器运行在端口 " + port.toString())

// 接受一个连接
future<point> acceptF = server.acceptAsync(30000)

// 客户端连接
TcpStream client = TcpStream(tcp.connect("127.0.0.1", port, 5000))
TcpStream peer = TcpStream(await acceptF)

// 客户端发送多条消息
client.send("Hello")
client.drain(3000)
string echo1 = client.recv(5000)
println("Echo: " + echo1)   // "Hello"

client.send("xlang TCP")
client.drain(3000)
string echo2 = client.recv(5000)
println("Echo: " + echo2)   // "xlang TCP"

// 二进制 echo
Buffer binData = Buffer()
binData.appendByte(0xDE)
binData.appendByte(0xAD)
client.sendBytes(binData.data(), c_size(binData.len()))
client.drain(3000)
Buffer binEcho = client.recvBytes(5000)
println("二进制 Echo 长度: " + binEcho.len().toString())

// 关闭
client.close()
peer.close()

深入细节

⚠️ 常见错误

本章小结

复习题

1. tcp.listen(0) 的 0 是什么含义？如何获取实际分配的端口？
2. send 和 drain 的区别是什么？什么情况下必须调用 drain？
3. TCP 的"粘包"是什么现象？xlang 中如何应对？
4. recv 返回空字符串有哪两种可能？如何区分？
5. tcp.connectAsync 和 tcp.connect 的使用场景有什么不同？
6. tcp.connectNoDelay 禁用了什么算法？什么场景下需要它？
7. tcp.listenReusePort 解决什么问题？
8. net.resolve("localhost", 80) 返回什么？如果域名无法解析会怎样？
9. sendBytes 的参数为什么是 (ptr, size) 而不是直接传 Buffer？
10. 为什么 acceptAsync 超时返回 null 不算错误？服务器应如何处理？

编程练习