我从去年到现在经手的Node.js后端项目里有四个都需要对外提供TCP服务两个是设备数据采集网关一个是内部服务之间的命令传输通道还有一个是跟外部系统做长连接消息交互。每个项目开工时我都要把net.createServer()的那套流程重新写一遍——监听端口、管理连接、解析数据、处理异常、关服务。代码量不大但散落各项目之后维护起来特别别扭有人忘了给server挂error监听进程崩了才知道有人连接断开后没清理句柄内存悄悄上涨。后来我干脆整理出一个公用方法把TCP服务创建、连接管理、数据分发、生命周期控制这些通用逻辑全部收敛进去业务侧只关心协议解析和数据处理。这篇文章就把这个公用方法的设计思路、完整实现和实测中踩过的坑完整记录下来适合已经写过一点Node.js TCP代码、想把手头逻辑沉淀成可复用模块的人参考。1. 为什么我会把TCP服务抽成公用模块1.1 重复代码到底重复在哪里用过Node.js写TCP服务的人都知道最小可用代码只需要几行const net require(net); const server net.createServer((socket) { socket.on(data, (data) { // 处理收到的数据 }); }); server.listen(8080, () { console.log(listening on 8080); });但真实项目不可能这么简单。我见过最常见的TCP服务代码膨胀路径是这样要记录当前有哪些客户端在线方便做连接统计和定向推送要给每个连接分配一个标识不然日志里分不清谁是谁要处理server的error事件否则监听失败直接抛异常要处理每个socket的error、close、timeout事件要应对粘包拆包得维护一个累积缓冲区要给空闲连接做超时清理防止半开连接占着资源不放要在服务退出时优雅关闭所有连接这些逻辑跟业务没有关系但每个TCP服务都躲不掉。问题是太多人选择每次重新写一遍写出来的细节还不一样。我见过一个项目用计数器在线人数另一个用Map还有一个压根不做超时清理。痛点就在这里公用方法不是让你少打字而是让所有TCP服务在非业务层面保持统一行为出问题时有相同的排查起点。1.2 公用方法的边界要划清楚封装最容易犯的错是把业务也包进来。参考我踩过的坑这个公用模块的正确职责应该是监听端口、绑定地址、启动服务维护在线连接集合提供连接级增删查改分发connection、data、close、error、timeout事件提供send、broadcast、closeConnection等基础操作支持空闲超时、连接上限、优雅关闭产生统一格式的日志和可观测指标业务侧则只负责三件事解析协议、处理消息、组装响应。如果你想连协议解析也做成通用能力那至少还要把消息边界定义设计成可注入接口我建议第一版先不做等第二个业务场景出来再抽象否则很容易抽象出一个没人能看懂的花架子。打个比方公用方法提供的是酒店的客房和前台入住人的身份核验、作息习惯、退房时要不要开发票这些是业务的事两者不该混在一起。2. 设计前先想清楚的四个问题2.1 接口形态回调组合还是事件订阅Node.js里两个人写公用TCP模块大概率给出两种API。一种是传统的回调注入createTcpServer({ onConnection(socket) {}, onMessage(socket, data) {}, onClose(socket) {} });另一种是基于EventEmitterconst server createTcpServer(options); server.events.on(connection, handler);我最后选的是两者结合核心逻辑内聚在一个模块里内部用EventEmitter管理事件对外既暴露事件订阅接口也保留回调参数。为什么要这样因为事件机制允许一个业务代码里同时挂多个监听者比如一个模块负责业务处理另一个模块专门采集监控指标各自on(data)互不干扰而回调参数适合90%的场景用起来代码更短。关键是别把API设计得两头都别扭。我的约定是构造时传入的handlers是快捷回调返回对象上的events是完整事件流事件和回调可以同时用不会互相屏蔽。2.2 连接集合用什么结构管理连接管理方案直接决定公用方法的上限。这里我不建议用对象{}因为键值对没法保证迭代顺序而且删除连接时如果忘了delete很快就会内存泄漏。用Map是更稳的选择它天然支持高频增删、按键查值、按插入顺序遍历。我给每个连接分配一个自增的数字ID这个ID同时作为后续日志追踪的关键字段。连接断开或出错时必须在close和error两个事件里都做清理因为Node.js里error之后通常也会触发close但我就见过只监听其中一个导致Map里残留死连接的情况。2.3 数据边界公用方法管到哪一层TCP是字节流没有消息边界。这意味着你收到的data可能是一个完整的业务消息可能是半条也可能是好几条拼在一起。这个问题的解决逻辑必须放在公用方法里因为它是所有TCP服务的共同需求但解析规则必须留给业务注入。我的做法是在公用方法里内置一个基础的包解析器入口业务侧通过onMessage拿到的是原始Buffer公用方法不做拆包但如果业务把自己的拆包函数传给公用模块模块会在数据到达时自动调用并把完整业务包回调出去。这样拆包能力是公用的但具体按长度字段还是按分隔符解析完全交给业务。2.4 生命周期启动、运行、退出的状态机一个生产级TCP服务至少要有三个状态starting、running、stopping。我见过最混乱的代码就是没有状态约束服务还没listen完成就去发消息关闭之后send也没报错所有行为都不可控。公用方法里我要保证三点start()返回一个Promise只有listen成功后才resolvestop()也返回Promise确保所有连接销毁完成后才结束在stopping状态下send和broadcast直接返回false不再尝试写入已关闭的socket。这样才能避免业务代码在完全随机的时间点发起操作。3. 核心实现一个可以直接复用的TCP服务模块先说好这个模块我刻意控制在一个文件内没有任何第三方依赖用的全是Node.js内置模块。你复制下来就能用也可以根据项目情况继续扩展。3.1 整体骨架与参数合并const net require(net); const { EventEmitter } require(events); const DEFAULT_OPTIONS { host: 0.0.0.0, port: 0, backlog: 511, maxConnections: 0, idleTimeout: 0, noDelay: true }; function createTcpServer(options {}, handlers {}) { const finalOptions { ...DEFAULT_OPTIONS, ...options }; const emitter new EventEmitter(); const sockets new Map(); let server null; let connectionIdCounter 1; // ...后续核心逻辑 }参数合并用的是浅拷贝。port默认设为0意味着如果调用方不指定系统会自动分配一个可用端口这在测试环境和容器环境下很方便。我把maxConnections和idleTimeout默认都设为0表示不限制、不超时保持最小意外。这里有个设计细节要解释为什么不用各种web框架而选原生net因为在公用方法这个定位上TCP服务的协议形态太杂了有的用长度头有的用特殊分隔符有的干脆裸流传输。框架帮你做掉的部分恰恰可能和业务协议冲突。原生net不越界适合作为底层公共件被不同的上层业务复用。3.2 连接注册与事件绑定function handleConnection(socket) { const connectionId connectionIdCounter; sockets.set(connectionId, socket); if (finalOptions.noDelay) { socket.setNoDelay(true); } if (finalOptions.idleTimeout 0) { socket.setTimeout(finalOptions.idleTimeout); } socket.on(data, (chunk) { emitter.emit(data, { connectionId, socket, chunk }); if (handlers.onMessage) { handlers.onMessage({ connectionId, socket, chunk }); } }); socket.on(timeout, () { emitter.emit(clientTimeout, { connectionId, socket }); socket.destroy(); }); socket.on(error, (err) { emitter.emit(clientError, { connectionId, socket, err }); }); socket.on(close, () { sockets.delete(connectionId); emitter.emit(clientClose, { connectionId }); if (handlers.onClose) { handlers.onClose({ connectionId }); } }); emitter.emit(connection, { connectionId, socket }); if (handlers.onConnection) { handlers.onConnection({ connectionId, socket }); } }几个容易忽略的地方socket.setTimeout必须要在监听data之前设置这样空闲超时计时器才能正确重置。connect的data事件里我给业务侧同时提供了connectionId和socket因为有些场景业务需要直接操作socket例如主动断开。超时处理我选择直接销毁连接而不是只发一个事件因为TCP空闲超时出现时对端的存活状态已经不可信留着连接只会积累垃圾。有读者可能会问socket.on(error)里面为什么没有sockets.delete因为规范里error之后必定跟随close删除操作放在close里做一次就够了重复删除反而可能掩盖连接状态Bug。3.3 启动、停止与基础操作APIfunction start() { return new Promise((resolve, reject) { server net.createServer(); server.on(connection, handleConnection); server.on(error, (err) { emitter.emit(serverError, { err }); if (handlers.onServerError) handlers.onServerError({ err }); }); const onError (err) reject(err); server.once(error, onError); server.listen(finalOptions.port, finalOptions.host, finalOptions.backlog, () { server.removeListener(error, onError); if (finalOptions.maxConnections 0) { server.maxConnections finalOptions.maxConnections; } const addr server.address(); resolve({ host: addr.address, port: addr.port }); }); }); } async function stop({ force true, waitTimeout 3000 } {}) { if (!server) return; const closePromise new Promise((resolve) { server.close(() resolve()); }); if (force) { for (const sock of sockets.values()) { sock.destroy(); } sockets.clear(); } else { await new Promise((resolve) setTimeout(resolve, waitTimeout)); for (const sock of sockets.values()) { sock.destroy(); } sockets.clear(); } await closePromise; server null; } function send(connectionId, data) { const socket sockets.get(connectionId); if (!socket || socket.destroyed) return false; return socket.write(data); } function broadcast(data, predicate () true) { let sentCount 0; for (const [id, socket] of sockets.entries()) { if (predicate(id, socket)) { socket.write(data); sentCount; } } return sentCount; } function getConnectionCount() { return sockets.size; } function getSocket(connectionId) { return sockets.get(connectionId) || null; } function closeConnection(connectionId) { const socket sockets.get(connectionId); if (socket) socket.destroy(); }stop()的force参数默认值我设为true这不是偷懒而是为了避免优雅关闭变成永不再关。真实项目里有些客户端连接会一直挂着你不强杀就永远关不掉服务。生产环境上线时我会加上系统信号处理器后面讲。3.4 模块导出和信息量完整的返回对象return { start, stop, send, broadcast, closeConnection, getConnectionCount, getSocket, events: emitter };我在返回对象里没有直接暴露server实例。为什么因为原生的server对象事件自由度太大业务侧一旦直接操作公用方法的状态管理就形同虚设。如果你想完全掌控服务比如需要主动调用server.getConnections()可以自己在业务层再包一层。4. 粘包、心跳、背压这三个细节决定公用方法靠不靠谱4.1 粘包与半包缓冲区累积解析方案公用方法里如果不考虑数据边界处理那它就没有真正解决TCP服务最普遍的痛点。这里给一个处理前4字节为长度协议的通用拆包器示例你直接可以挂在onMessage前面function createLengthPrefixParser() { let buffer Buffer.alloc(0); return function parser(chunk, onPacket) { buffer Buffer.concat([buffer, chunk]); while (buffer.length 4) { const payloadLength buffer.readUInt32BE(0); if (buffer.length 4 payloadLength) { break; } const packet Buffer.from(buffer.subarray(4, 4 payloadLength)); buffer buffer.subarray(4 payloadLength); onPacket(packet); } }; }这个解析器的原理不复杂TCP数据到达后先拼接进缓冲区然后循环尝试从缓冲区头部读取长度字段如果长度字段还没有对应数据就跳出等待下一块数据。这里有两个实验中的经验拆出来的业务包一定要用Buffer.from()拷贝一份因为subarray()返回的是原缓冲区视图后续对buffer的切片操作会影响你回调里的数据。while循环不能写成if因为一个data事件里可能包含多个完整包只解析一个就会漏数据。对于非二进制协议你可以把readUInt32BE换成indexOf(\n)之类的分隔符扫描。公用方法内部逻辑不动换一个解析器函数就行。4.2 心跳机制半开连接是隐形杀手TCP不会主动通知对端我死了。如果设备突然断电或者网络线路中断本端可能长时间不知道连接已失效这个状态叫半开连接。业务侧如果只知道这个连接在Map里就会一直给死连接发消息浪费资源还影响统计。常用的兜底方案有三种公用方法里我建议至少支持一种socket层空闲超时也就是上面代码里的idleTimeout适合大多数场景超过时间没有任何数据传输就销毁。业务心跳包客户端每隔N秒发一个心跳消息服务端收到任何数据都视为活跃。实现上记录每个连接最后活跃时间启动定时器周期性扫描。应用层心跳探测服务端主动发ping包对端必须在超时时间内回pong否则销毁。前两种在公用方法层面就能做到第三种需要业务协议配合我把主动探测做成一个可选扩展。这里有一个血的教训idleTimeout的值必须大于业务最大静默间隔。有一个项目里设备每120秒上报一次数据运维同学把超时配置设成60秒上线一小时所有连接全断光。TCP空闲超时和业务心跳是两回事前者是底层兜底后者是业务活跃性判断别混用。4.3 背压处理挂着的慢客户端会拖垮整机Node.js的socket写入并不保证立刻发到对端。如果客户端处理速度慢socket.write()返回false表示数据已经堆积在内核缓冲区此时继续写入会让内存持续增加。很多公用TCP模块不处理这个问题跑测试没问题一到生产遇到一个1万连接里有个慢消费者进程内存就失控。我的处理原则是公用方法统一做窗口管理和暂停/恢复但具体要不要丢弃数据由业务传入的策略决定function writeWithBackpressure(socket, data) { const canWrite socket.write(data); if (!canWrite) { socket.pause(); let resumed false; socket.once(drain, () { if (!resumed) { resumed true; socket.resume(); } }); } return canWrite; }注意这个方案有取舍。pause()暂停的是接收行为不是接收和业务处理都停丢失数据的风险还是存在。生产系统里我更倾向于在公用方法外层加一个发送队列把发送失败的重试机制留给业务避免公用方法越界。这里只展示这个思路不要把它当作银弹。5. 实测中踩到的高频坑端口占用、进程崩溃与连接误杀5.1 EADDRINUSE服务明明停了端口还是被占listen时报Error: listen EADDRINUSE: address already in use是我见过最多的启动失败原因。排查链路一般是三步用lsof -i :端口号macOS/Linux或netstat -ano | findstr 端口号Windows查是谁在占用。根据PID找到进程确认是不是残留的旧服务。杀掉残留进程后重启或者等一会儿再启动。但这里有个真正值得说的坑很多时候端口占用不是别的进程占着而是你上一个Node服务没有真正退出。原因通常是你调用了server.close()却没有等待所有连接销毁进程事件循环还被活着的socket挂着于是进程不退端口就持续被占用。公用方法里的stop()如果写完日志就process.exit()反而比stop()函数本身更可靠。我前面在stop()里用force true就是为这个场景兜底。改完公用模块之后启动失败率肉眼可见地下降。5.2 没挂server error监听一个报错拖垮整个进程纯手写TCP服务时最容易被忽略的是server.on(error)。net.createServer()产生的错误如果没有任何监听会成为未捕获异常Node进程直接退出。我不是在跟你开玩笑这个坑我在生产环境遇到过一次端口探测脚本跑太快服务还在重启过程中监控探针一次误触导致整个采集网关崩了。进程重启的那一刻恰好探针也来了它连上了然后探针的数据格式把服务打崩形成一个恶性循环。公用方法里我已经内置了server.on(error)并且通过handlers.onServerError暴露给业务侧。你不要在这个回调里什么都不干至少要打一条带上下文的结构化日志字段包含错误码、错误内容、当前连接数、启动参数这些信息在排障时比日志大小更重要。示例handlers.onServerError ({ err }) { logger.error({ topic: tcp_server_error, errorCode: err.code, errorMessage: err.message, activeConnections: serverState.getConnectionCount() }); };5.3 空闲超时把正常的闲时连接全杀了上一节提过超时值要大于业务最大静默间隔。这里我再补充一个反直觉的场景TCP空闲超时是在链路层没有任何数据包的前提下计时的如果网络栈上偶尔有TCP keepalive包空闲计时器不会触发。但应用层定义的心跳包是业务数据它确实会清零socket的setTimeout计时器。很多用户困惑的点在于设置了idleTimeout 30秒为什么客户端每40秒发一次业务心跳连接还是被断了这里的原因在Node.js的实现细节socket.setTimeout(ms)的超时阈值以毫秒为单位而且它默认开启的是底层TCP定时器只有当socket上没有任何读写活动达到该时长才会触发timeout事件。如果业务心跳每40秒一次你的阈值却设成30秒那必然误杀。我的建议很简单除非你明确知道业务对端静默周期的上限否则idleTimeout至少设置成业务心跳间隔的两倍以上。还有更偏门的场景设备端的TCP实现不完善不发RST也不发FIN断网后本端完全感知不到。这种情况下setTimeout根本不会触发因为链路上没有任何可超时的读活动需要的是业务心跳扫描。公用方法里建议同时启用最后活跃时间扫描作为兜底时间成本很低。5.4 maxConnections的限制其实很粗糙server.maxConnections N是Node.js原生提供的并发上限控制超过N的新连接会被直接拒绝对端表现为连接被重置。这个机制在简单场景够用但两个问题你心里要有数server.maxConnections拒绝连接时你收不到任何事件业务无法感知谁被拒了、为什么被拒。已经建立的连接不释放新连接照样被拒你可能看到连接数一直卡在N附近下不去。如果公用方法要做得更透明建议的办法是自己做连接数校验在handleConnection里先判断sockets.size是否达到阈值达到就直接记录日志并socket.destroy()。这样你可以把拒绝连接变成一条可观测的指标运营和分析数据集时比黑盒的maxConnections舒服得多。5.5 顺手填一个环境坑Windows下npm脚本跑不起来的连锁问题我知道这个话题跟TCP服务本身关系不大但实际遇到的人不少。开发机装完Node.js之后在PowerShell里执行npm run dev报错类似npm.ps1 无法加载文件因为在此系统上禁止运行脚本。这是PowerShell默认执行策略Restricted导致的。解决办法是打开PowerShell管理员执行Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser然后重新打开终端。这个问题会卡住整个开发流程连调试TCP公用方法都做不了属于环境准备必修课。6. 从工具模块到生产服务日志、监控与优雅退出6.1 结构化日志每条日志都要能追溯到一个连接公用方法一旦被多个服务复用日志格式就必须统一。我给模块定了一个日志约定所有模块内部的日志输出都走一个logger选项默认实现是console.log但字段结构固定为JSON方便后续接入任何日志系统。推荐的字段结构是{ time: 2025-01-01T12:00:00.000Z, level: info, scope: tcp-server, event: connection-established, connectionId: 123, activeConnections: 5, message: new client connected }这个结构不算复杂但connectionId就像分布式链路里的traceId它让业务日志和通用日志能对上号。我在实现中会在每次业务onMessage回调前追加一条日志钩子业务处理器返回后还能再记一条发送结果整个请求链路完整可查。6.2 可观测指标连接数、收发字节、错误分类公用方法里维护几个计数器的成本极低收益却很高。我在模块里增加如下统计当前连接数、累计连接数、峰值连接数累计接收字节数、累计发送字节数连接被拒绝次数、空闲超时断连次数、客户端错误次数服务启动时间、最后一次启动耗时这些指标我会暴露成一个getStats()方法业务侧可以定时采集也可以打进监控系统。实践中最有用的指标是当前连接数和空闲超时断连次数——前者帮你判断容量后者帮你判断超时配置是否合理。如果你的监控系统支持轨道图把这两条线放在一个面板里观察比看CPU和内存更有业务预测价值。6.3 优雅退出给线上服务留一条完整的后路前面说的stop()方法已经可以销毁所有连接并关闭服务但线上部署还需要考虑系统信号。我习惯在入口文件里这样写const tcpServer createTcpServer(options, handlers); async function shutdown(signal) { console.log(${signal} received, shutting down); await tcpServer.stop({ force: true, waitTimeout: 5000 }); process.exit(0); } process.on(SIGTERM, () shutdown(SIGTERM)); process.on(SIGINT, () shutdown(SIGINT));需要注意SIGTERM和SIGINT通常来自系统或运维脚本如果你在这段代码里做太多的异步清理系统等不及就会直接杀掉进程。更好的方案是两阶段退出先发一个业务侧的事件通知服务准备关闭给业务一个非常短的窗口去保存必要状态然后立刻调用stop()强制清理。这个窗口一般不要超过5秒理想情况越短越好。6.4 和微服务架构的衔接方式既然热搜词里有微服务相关的东西我在这里多说一句实际经验。TCP服务在微服务架构里通常是边缘接入层或堡垒节点它自身的生命周期管理可以和服务注册中心联动服务启动成功后注册停止前先反注册再关闭连接。公用方法里start()返回的{ host, port }正好可以充当注册信息的来源stop()前面可以挂一个onBeforeStop钩子做反注册。这个模式我用了挺久它能明显减少调用方因为服务拉起、缩容导致的连接中断报告。从实际使用体验讲这个公用模块我维护了大半年cover住了四个项目的TCP接入需求。它的实现不超过两百行但避掉的坑远不止两百行代码能覆盖的东西。对刚接触Node.js TCP服务的人来说我建议不要一上来就构思大而全的抽象框架而是先把这些基础能力——连接管理、数据边界、超时心跳、优雅退出——做扎实然后自然会发现公用方法是件水到渠成的事。如果你在封装时遇到什么奇怪的场景比如某个设备发的是半包导致你的解析器卡住欢迎直接按这个思路继续扩展协议解析这一层本来就该留口子给业务自由发挥。