一个调用第三方接口的脚本,用 http.get 发了请求,加了一行超时处理:
req.setTimeout(50, () => {
console.log('timeout fired');
req.destroy();
});
超时确实触发了,打印出了 timeout fired,紧接着进程崩溃:
Error: socket hang up
at Socket.socketCloseListener (node:_http_client:739:27)
code: 'ECONNRESET'
原因是 destroy() 之后,请求对象上抛出了一个 error 事件,而代码没有监听它。Node 对没有监听的 error 事件的处理方式是直接抛出,于是整个进程退出。这个坑不是网络特有的,但它在网络代码里出现得特别频繁,因为「取消请求」和「连接被对端关掉」都会产生错误。
这篇讲 Node 里三种常见的网络写法:http 模块做服务端和客户端、fetch 做请求、net 的 socket 直接处理 TCP。重点不是 API 列表,是每种写法的边界和容易踩的取消、超时、错误处理。TCP 和 HTTP 本身的原理在TCP 与 UDP和HTTP两篇里,这里不重复。
http 模块:一个进程里的服务端和客户端
http.createServer 创建一个服务端,每来一个请求,回调收到 req(可读流)和 res(可写流)。请求的方法、路径、头在 req.method、req.url、req.headers 里;响应用 res.writeHead 设状态码和头,用 res.end 结束。
const server = http.createServer((req, res) => {
res.writeHead(200, { 'content-type': 'text/plain; charset=utf-8' });
res.end('hello 你好');
});
server.listen(0, '127.0.0.1');
listen(0) 表示让操作系统分配一个空闲端口,测试时非常有用,不会和本机别的服务撞端口。启动后打印 server.address().port 能拿到真实端口,我这次是 18623。生产环境通常固定端口,但测试和并行任务里用 0 是更好的习惯。
客户端用 http.get 或 http.request。get 是 request 的快捷方式,自动把方法设成 GET 并调用 end();需要 POST、要写请求体、要精细控制头时用 request。两者都返回一个 ClientRequest,响应在回调里拿到,响应体也是流。
http 模块不做 JSON 解析、不自动跟随重定向、不检查状态码。它只负责把 HTTP 报文发出去、收回来。这些「方便」的能力是 fetch 提供的,用 http 就要自己补。反过来说,需要控制连接、代理、底层头、流式上传时,http 更直接。
服务端的 req 是流,POST 的请求体不会自动变成对象。要自己监听 data 收集、end 时处理,同时限制大小,否则一个超大请求会把内存吃光。我实测 POST 一段 23 字节的 JSON,服务端收集到 {"a":1,"text":"中文"},字节数正好 23。生产中还要处理 Content-Type 不是 JSON、请求体为空、客户端中途断开这些情况。
超过限制时要返回 413 并停止读取。只 res.end 不销毁请求,客户端可能继续发,连接也一直占着。示例里先 writeHead(413) 再 req.destroy(),就是这个顺序。注意销毁会触发 error,服务端也要监听 req.on('error'),否则同样是进程崩溃。
res.write 之后头就不能再改。想设状态码和响应头,必须在第一次 write 或 end 之前调用 writeHead。忘了设 content-type,客户端可能按默认类型解析,中文就成乱码。上面的示例统一写了 charset=utf-8,就是为了避免这个。
HTTP 报文长什么样:用 socket 看一眼
要理解 http 模块在做什么,最直接的办法是用 net.connect 建一个 TCP 连接,手写一段 HTTP 请求文本发过去,再把原始响应读回来。我实测发送:
GET /json HTTP/1.1\r\nHost: 127.0.0.1\r\nConnection: close\r\n\r\n
收到的第一行是 "HTTP/1.1 200 OK",接下来几行是头:content-type: application/json、Date: ...、Connection: close。空行之后才是响应体。HTTP/1.1 的报文结构就是「起始行、头、空行、体」,http 模块帮你拼和拆的就是这一段。
响应体什么时候结束,HTTP/1.1 有三种约定:Content-Length 给定长度、Transfer-Encoding: chunked 分块传输、或者连接关闭作为结束。用 http 模块时这些由库处理;自己读 socket 时就要按约定判断,否则会把「连接还没关」误当成「响应还没完」,一直等下去。
HTTP 是无状态协议,每个请求自带全部信息(方法、路径、头、体),服务端不默认记住上一个请求。所谓「登录状态」是靠 Cookie 或 Token 在每次请求里重复携带。理解这一点,就不会问「服务端为什么不知道我刚登录过」——它本来就不该知道,除非你把状态带过去。这也是 fetch 不自动带 cookie 的原因:要不要带、带哪些,是应用层决定,不是协议自动完成。
fetch 的边界:它不拒绝 4xx
Node 24 自带 fetch,不用装依赖。await fetch(url) 返回 Response,用 res.status 看状态码,res.text() 或 res.json() 读体。我实测请求本地服务,得到 200 和 {"ok":true,"method":"GET","ua":"node"},再请求根路径得到 "hello 你好"。
第一个边界:HTTP 错误状态不会让 fetch 拒绝。服务端返回 404、500,fetch 仍然正常 resolve,只是 res.ok 是 false。只有网络层失败(连不上、DNS 解析失败、连接被重置)才会 reject。所以每次都要检查 res.ok 或 res.status,不能只 try/catch。
第二个边界:fetch 要求绝对 URL,传 /api 这种相对路径会直接报错。它也不会自动带 cookie,Node 里没有浏览器的 cookie 仓库,需要手动加 Cookie 头。第三,fetch 默认跟随重定向,最多 20 次,某些场景要显式设 redirect: 'manual'。这些差异在和浏览器代码共用时最容易出问题。
第四,fetch 的错误信息比较「薄」。连不上时抛的是 TypeError: fetch failed,具体原因在 err.cause 里。我请求一个没监听的端口,得到 cause ECONNREFUSED connect ECONNREFUSED 127.0.0.1:65000。排查时不能只看 err.message,要把 cause 打出来。
用 fetch 发 POST,方法、头、体都要显式给:method: 'POST'、content-type: application/json、body: JSON.stringify(data)。fetch 不会根据 body 自动推断 JSON。响应头用 res.headers.get('content-type') 读,has 判断存在性。我实测服务端回 application/json,get 拿到原值,has('x-missing') 返回 false。
响应体也可以流式读。res.body 是 Web 标准的 ReadableStream,可以用 getReader() 逐块读,也可以 Readable.fromWeb(res.body) 转成 Node 流再 pipeline 到文件。下载大文件时不要 await res.arrayBuffer(),那等于把整个响应装进内存,和上一篇的 readFile 是同一类问题。
fetch 的 Response 还带 url、redirected、statusText。跟随重定向后,res.url 是最终地址,res.redirected 是 true;排查「请求打到了哪」时看这两个字段,比猜快。statusText 只是原因短语,业务判断看 status。
fetch 的响应体只能读一次。res.text() 之后不能再 res.json(),会报 Body is unusable。需要同时拿文本和解析结果,先 text() 再 JSON.parse,或者 clone() 一份。超时与取消:AbortController 是统一入口
网络请求必须能取消,否则一个卡住的请求会一直占着连接和内存。Node 里统一的取消机制是 AbortController:创建一个控制器,把 controller.signal 传给请求,到点调用 controller.abort()。
const ac = new AbortController();
setTimeout(() => ac.abort(), 100);
try {
await fetch(url, { signal: ac.signal });
} catch (e) {
console.log(e.name, e.message);
}
我实测对一慢接口 100 毫秒后取消,得到 AbortError 和 This operation was aborted。这个错误要单独判断:它是「主动取消」,不是「请求失败」,日志里不该按失败统计。Node 24 还有 AbortSignal.timeout(ms),一行就能造出「到点自动取消」的信号,比手动 setTimeout 简洁。
用 http 模块时,取消分两层。req.setTimeout(ms, cb) 只是「连接空闲超过 ms 就调回调」,它不会自动中止请求,回调里要自己处理。直接 req.destroy() 会中止,但如上文所说,会触发 error 事件;必须同时监听 req.on('error', ...),否则进程崩溃。正确写法是设置一个标志,在 error 回调里判断「是不是我主动取消的」,再做清理。
req.setTimeout(50, () => {
timedOut = true;
req.destroy();
});
req.on('error', (err) => {
if (timedOut) return console.log('aborted by timeout');
console.error('real error', err.code);
});
setTimeout 的语义也要注意:它计的是 socket 空闲时间,不是「从发出请求到收到完整响应」的总时间。响应体传到一半卡住,也会触发。想要总时限,得自己记开始时间,或者用 AbortSignal.timeout 配合 fetch。
http 的超时要分三层看:连接建立超时、socket 空闲超时、整个请求的总时限。req.setTimeout 只管第二层,连接还没建立时它不一定生效;总时限要自己用 AbortSignal.timeout 或记开始时间。排查「请求卡住」时先说清卡在哪一层,否则调参数只是碰运气。
AbortSignal.any([a, b]) 可以把多个信号合成一个,任意一个触发就取消。适合「用户取消」和「超时」同时生效的场景。Node 24 支持这个 API,用之前确认目标运行时版本。
socket:TCP 是流,不是消息
net.connect(port, host) 建立一个 TCP 连接,拿到一个双工 socket:可以 write 发数据,监听 data 收数据,end 表示对端关了写端,close 表示连接彻底结束。我实测连接后打印 sock.remoteAddress 是 127.0.0.1,sock.remotePort 是 18623。
TCP 最重要的性质是「它只保证字节顺序,不保证消息边界」。你 write 两次,对端可能一次 data 收到两段内容,也可能分三次收到。这叫粘包和半包。HTTP 用 Content-Length 和 chunked 编码解决这个问题,自定义协议要自己设计分隔符或长度字段。
所以 socket 的 data 回调里,不能假设「一次 data 就是一条完整消息」。正确做法是把收到的字节追加到缓冲区,再按协议规则切分,切出完整消息才处理,剩下的留着等下一批。按行协议还要处理 \r\n 和 \n 两种换行,以及最后一条没有换行符的消息。data 给的是 Buffer,按文本处理要先解码;一块里可能包含完整字符,也可能只有半个,和文件流一样要小心。
自定义协议最简单的分帧方式是「一行一条 JSON」,也就是常说的 NDJSON。每写一条就补一个换行,读端按行切分,切不出来的部分留在缓冲区。这样既不需要长度字段,也方便人眼调试。缺点是消息里不能有裸换行,JSON 序列化默认会转义,正好满足。
error 事件必须监听。对端强制关闭、网络中断、写入已关闭的连接,都会触发 error。不监听就是进程崩溃。常见错误码有 ECONNRESET(连接被重置)和 EPIPE(往已关闭的管道写)。还有一个容易忽略的点:socket.write() 也有背压,返回 false 时应该等 drain。写大量数据时不管返回值,数据会堆在内存里。这和上一篇文件流的机制完全一样,因为 socket 本身就是流。
socket.end() 是「我这边没有数据要发了」,destroy() 是「直接断掉」。默认 allowHalfOpen: false,收到对端的结束信号后,本地写端也会自动结束。我实测客户端 end('hi') 后仍能收到服务端的 bye,然后依次触发 end 和 close。需要「发完还能继续收」的半关闭语义时,才设 allowHalfOpen: true,并且要自己管理关闭时机。
连接复用与 Agent
每次 http.get 都新建 TCP 连接,代价是三次握手和慢启动。HTTP/1.1 支持 keep-alive,让同一个连接处理多个请求。Node 的 http.globalAgent 在较新版本里默认开启 keep-alive,我打印 keepAlive 是 true,keepAliveMsecs 是 1000。
复用的代价是状态残留。连接被对端悄悄关掉后,客户端可能还拿着它发下一个请求,得到 ECONNRESET。这也是为什么「偶发一次请求失败、重试就成功」在 HTTP 客户端里很常见。遇到这种模式,先怀疑空闲连接被回收,而不是业务逻辑。
需要控制并发连接数、超时、代理时,可以自己创建 new http.Agent({ keepAlive: true, maxSockets: 10 }),传给请求的 agent 选项。默认的全局 Agent 是进程共享的,改它的配置会影响所有请求,测试里尤其要小心。
fetch 在 Node 里底层也走连接池,但可配置项比 http.Agent 少。需要精细控制连接时就退回 http 模块。两者不要混着用同一个服务端点,否则连接池各管各的,实际并发数可能翻倍。
http.request 里的主机名要先做 DNS 解析,解析失败会报 ENOTFOUND。本机测试常用 127.0.0.1 绕过这一步,所以「本地能连、线上报 ENOTFOUND」很常见。排查时先 nslookup 或 dns.lookup 确认域名能解析,再看连接。DNS 解析不在 req.setTimeout 的计时范围内,这也是「设置了超时却等了很久」的原因之一。
我做过一个小实验:同一个 Agent 设 keepAlive: true、maxSockets: 1,连续发 3 个 GET,服务端只看到 1 次 connection 事件。把 keepAlive 关掉再跑,连接数就变成 3。复用省掉的是握手和慢启动,不是「少发请求」。并发高、请求小、服务端支持 keep-alive 时收益明显;服务端明确返回 Connection: close 时,复用没有意义。
现象对照
| 现象 | 真实原因 | 第一步查什么 |
|---|---|---|
| 超时后进程直接退出 | destroy() 触发 error,没人监听 | 给请求加 error 监听,区分主动取消 |
fetch 返回 500 但没进 catch | HTTP 错误状态不会 reject | 检查 res.ok 或 res.status |
TypeError: fetch failed | 网络层失败,具体原因在 cause | 打印 err.cause.code |
| 取消被记成请求失败 | AbortError 和真实错误混在一起 | 按 e.name 区分,单独统计 |
| 响应体读第二次报错 | 响应体只能消费一次 | 先 text() 再解析,或 clone() |
| socket 收到半条消息 | TCP 只保证字节顺序,不保证边界 | 缓冲数据,按协议切分完整消息 |
| 写 socket 后内存上涨 | write 返回 false 没等 drain | 按返回值暂停,等 drain 再写 |
偶发 ECONNRESET | 复用的空闲连接被对端关闭 | 关闭 keep-alive 或加重试 |
EPIPE | 往已经关闭的连接写数据 | 监听 error,停止写入并清理 |
| 相对路径请求直接报错 | fetch 要求绝对 URL | 拼上协议和主机,或改用 http |
| 服务端收到空 body | Content-Type 与实际不符,或没读 data | 打印原始头和字节长度 |
ENOTFOUND | 域名解析失败 | 用 dns.lookup 验证域名 |
返回 431 | 请求头超过默认上限 | 看 Cookie 和自定义头大小 |
边界与代价
网络代码的第一个代价是「失败是常态」。磁盘读写的失败通常是确定的,网络失败是随机的:超时、连接重置、DNS 抖动、对端限流。每一条请求都要考虑重试、超时、幂等。没有超时的请求等于把进程交给对端控制,对方不响应,你就永远等。
第二个代价是「错误分类」。同一个 error 事件,可能是主动取消、可能是对端关闭、可能是网络中断。不区分就无法决定「该重试还是该放弃」。实践里至少分三类:可重试(超时、连接重置)、不可重试(4xx 参数错误)、需要人工(5xx 连续出现)。
第三个代价是「资源和生命周期的管理」。连接、socket、请求对象都要显式关闭;流式请求体要消费完或销毁,否则连接不能复用。一个忘记 res.resume() 的响应,能让连接一直挂在那里。用 pipeline 和 AbortSignal 把这些交给标准库,比手写可靠。
最后是「观测困难」。网络问题往往跨进程、跨机器,日志里只有一个错误码。要在本地复现,得能控制服务端的行为:延迟、断连、返回错误状态、返回半截响应。自己写一个小服务端做这些实验,比在生产上猜快得多。
需要 HTTPS 时换成 https.request,或者继续用 fetch。https 模块多一层 TLS 握手,证书校验失败会报 UNABLE_TO_VERIFY_LEAF_SIGNATURE 或 SELF_SIGNED_CERT_IN_CHAIN。本地自签证书要显式传 ca,不要为了跑通关掉校验;关掉校验等于把中间人攻击的门打开。TLS 细节属于传输层,这里只需知道它比 HTTP 多一次握手和证书检查。
还有一个现实约束:Node 的 HTTP 解析器对头部大小有上限,默认约 16 KB。超长 Cookie 或自定义头会被拒,返回 431 Request Header Fields Too Large。这不是业务 bug,是保护机制;需要更大可以调 maxHeaderSize,但先想想是不是设计本身有问题。
小结
http.createServer 用 req/res 两个流处理请求和响应,listen(0) 让系统分配端口;http.get 是客户端快捷方式,不做 JSON 解析和重定向;HTTP 报文是「起始行、头、空行、体」,体结束靠长度或分块或关连接;fetch 不拒绝 4xx/5xx,失败原因在看 cause;取消统一用 AbortController,req.destroy() 必须配 error 监听;TCP socket 只保证字节顺序,消息边界要自己切;连接复用默认开启,偶发 ECONNRESET 多半是空闲连接被回收。
当天可以自己验证的练习:
- 用
http.createServer起一个listen(0)的服务,打印真实端口,用fetch请求它并打印状态和响应体。 - 让服务端返回 404,观察
fetch是否 reject,打印res.ok和res.status。 - 用
AbortSignal.timeout(100)请求一个慢接口,打印错误的name和message。 - 用
net.connect手写一段 HTTP 请求,打印响应的第一行和头。 - 写一个 socket 服务端,一次
write两条消息,观察客户端收到几次data。
下一篇讲多进程:child_process、cluster、进程间通信。单个 Node 进程只能用一个 CPU 核,网络服务要压满多核就得开多个进程。多进程会带来新问题:怎么启动、怎么通信、怎么共享端口、子进程挂了怎么办。这些是下一篇的内容,系统层面的进程模型可以回看操作系统里的进程。