# net 常见问题

## net.listen 返回什么

按 type 返回不同句柄：

| type | 返回类型 | 公共字段 | 公共方法 |
|------|------|------|------|
| web | WebServer | addr、type | close() |
| tcp | TcpServer | addr、type | close() |
| udp | UdpSocket | addr、type | send()、close() |
| ws | WsServer | addr、type | close() |

`addr` 是实际监听地址，`type` 是服务类型字符串，`close()` 用于关闭服务或 socket。

## net.connect 返回什么

按 type 返回不同连接句柄：

| type | 返回类型 | 字段 | 常用方法 |
|------|------|------|------|
| tcp | TcpClient | addr、type | write()、send()、read()、close() |
| udp | UdpSocket | addr、type | send()、close() |
| ws | WsSocket | addr、type | send()、write()、close()、on_message()、on_close()、on_error() |

TCP 和 UDP 使用 `host`、`port` 配置连接目标；WebSocket 使用 `url` 配置完整连接地址。

## 回调字段名称

事件回调统一使用 snake_case：on_connect、on_message、on_close、on_error。

## 端口占用

bind 端口被占用时会抛出错误。开发测试可使用 127.0.0.1:0 让操作系统分配空闲端口。

## 队列满会怎样

TCP、UDP、WebSocket 后台事件队列有固定上限，默认 4096。队列满时不会无限占用内存：TCP 和 WebSocket 会关闭对应连接，UDP 会丢弃当前报文。可通过 `BT.stats().net.event_queue_rejected` 查看发生次数。

## 错误信息

TCP、UDP、WebSocket 的用户可见错误会尽量使用统一中文格式。常见类型包括端口已被占用、权限不足、地址不可用、连接被拒绝、连接被对端重置、握手失败、写队列已满和消息大小超过上限。

## 压测脚本

`examples/` 下提供 `net-stress-tcp-server.bt` / `net-stress-tcp-client.bt`、`net-stress-udp-server.bt` / `net-stress-udp-client.bt`、`net-stress-ws-server.bt` / `net-stress-ws-client.bt`。先启动对应 server，再启动 client。需要压低资源边界时，在启动进程前设置 `BT_NET_EVENT_QUEUE`、`BT_NET_WRITE_QUEUE` 或 `BT_NET_MESSAGE_LIMIT`。

## 二进制消息怎么接收

TCP、UDP、WebSocket 监听配置中设置 `binary: true` 后，`on_message` 回调的消息参数会返回 Bytes。TCP 客户端同步读取可以使用 `read_bytes()`。