@k3000/service

这是一个为 Node.js 设计的轻量级、多协议 RPC（远程过程调用）库，支持 TCP、IPC 和 UDP，并采用自定义二进制协议。

特性

• 多协议支持：支持 TCP、IPC（Unix 域套接字 / Windows 命名管道）和 UDP 服务端和客户端协议须相同。
• 自定义二进制协议：针对常见类型（布尔值、数字、字符串、对象、Buffer 等）的高效数据序列化。
• 基于 Proxy 的 API：使用 ES6 Proxy，像调用本地函数一样调用远程方法。
• 异步处理：基于 Node.js 原生网络模块构建，完全支持 Promise。
• 自动序列化：开箱即用地处理 JSON 对象、Buffer 和原始类型。
• 自行实现加解密：encode、decode 服务端和客户端都要实现。

安装

npm install @k3000/service

(注意：此包需要 @k3000/tools 作为依赖项。)

快速上手

TCP 服务

服务端：

import createService from '@k3000/service';

const encode = data => Buffer.concat([data, Buffer.alloc(8)])
const decode = data => data.slice(0, data.length - 8)

const server = createService({
  type: 'tcp',
  port: 9000,
  address: 'localhost',
  encode, // 非必须
  decode, // 非必须
  map: {
    add(a, b) {
      return a + b;
    },
    async greet(name) {
      return `你好, ${name}!`;
    }
  }
});

客户端：

import createService from '@k3000/service';

const client = createService({
  type: 'tcp',
  port: 9001, // 客户端服务监听的本地端口
  encode,
  decode,
}, {
  remote: 'localhost:9000' // 目标服务端地址
});

// 调用远程方法
const sum = await client.remote.add(10, 20);
console.log(sum); // 30

const message = await client.remote.greet('世界');
console.log(message); // 你好, 世界!

IPC 服务

服务端：

const server = createService({
  type: 'ipc',
  name: 'my-service', // 管道名称
  map: {
    getData() {
      return { success: true, data: [1, 2, 3] };
    }
  }
});

客户端：

const client = createService({
  type: 'ipc',
  name: 'my-client'
}, {
  srv: 'my-service' // 目标管道名称
});

const result = await client.srv.getData();

API 参考

createService(options, pools)

options 对象

| 属性 | 类型 | 默认值 | 描述 | | :--- | :--- | :--- | :--- | | type | String | 'udp' | 协议类型：'tcp'、'ipc' 或 'udp'。 | | port | String/Number | '9000' | 监听端口 (TCP/UDP)。 | | address | String | 'localhost' | 绑定的接口地址。 | | name | String | '' | IPC 管道名称或错误标识符。 | | timeout | Number | 5000 | RPC 调用超时时间（毫秒）。 | | map | Object | {} | 暴露的方法键值对。 | | listener | Function | undefined | 用于处理 map 中未定义请求的通用函数。 |

pools 对象

一个可选对象，用于定义远程服务绑定。键是本地属性名，值是连接字符串（例如 'host:port' 或 'pipe-name'）。

返回值

扩展后的 pools 对象，包含：

• 绑定的远程服务代理。
• close() 函数，用于关闭服务及其连接。

协议规范

该库使用自定义二进制包格式：

1. 长度 (4 字节)：总报文大小 (Big Endian)。
2. ID (2 字节)：用于匹配的请求/响应 ID。
3. 方法名长度 (1 字节)：方法名字符串的长度。
4. 类型/数据类型 (1 字节)：高 4 位表示消息类型（Request/Resolve/Reject/System），低 4 位表示数据类型。
5. 方法名：UTF-8 编码的字符串。
6. 载荷：基于数据类型的序列化数据。

开发

运行测试

node --test test.mjs

许可证

MIT