fastrpc-js

fastrpc-js 是一个轻量级、类型感知的 JavaScript/Node.js 远程过程调用（RPC）框架，兼容 fastrpc-py。它允许你在服务端暴露函数，并在客户端像调用本地函数一样远程调用它们，同时自动处理类型转换、文件上传与返回、本地/远程模式切换等复杂逻辑。

特性

• 类型兼容：使用 Python 类型名（如 str, int, bytes, datetime）进行接口定义，服务端和客户端自动映射为对应的 JavaScript 类型。
• 混合参数支持：支持位置参数 + 命名参数混合调用。
• 文件传输：无缝支持上传和下载二进制数据（bytes/file 类型），本地模式下自动使用临时文件路径优化性能。
• 本地/远程智能模式：
  • 当客户端与服务端在同一主机（localhost、127.0.0.1 等）时，大文件通过临时路径传递，避免内存拷贝。
  • 远程调用时使用标准 HTTP 流式传输。
• 自动元数据发现：客户端启动时自动从 /funcs 端点拉取可用函数及其类型签名。
• 简单易用：服务端使用装饰器风格注册函数，客户端自动挂载为方法。

安装

npm install fastrpc-js

依赖项已包含在包中：express, multer, axios, form-data, uuid。

服务端示例

必须要填写参数信息{ params: { a: 'number', b: 'number' }, returns: 'number', doc: 'Adds two numbers' }

import { rpc } from 'fastrpc-js';

const server = new rpc();

@server.method('add', {
  params: { a: 'number', b: 'number' },
  returns: 'number',
  doc: 'Adds two numbers'
})
function add({ a, b }) {
  return a + b;
}

@server.method('upload_image', {
  params: { image: 'file', caption: 'string' },
  returns: 'str'
})
async function uploadImage({ image, caption }) {
  // image is a Buffer
  console.log('Received image of', image.length, 'bytes');
  return `Image saved with caption: ${caption}`;
}

server.listen(8080);

启动后，访问 http://localhost:8080/funcs 可查看所有注册函数的元数据。

客户端示例

import { rpc_client } from 'fastrpc-js';

const client = new rpc_client('http://localhost:8080');

// 等待函数加载完成（构造函数已自动加载）
await new Promise(resolve => setTimeout(resolve, 100));

// 调用远程函数
const sum = await client.add(3, 5);
console.log(sum); // 8

// 或使用命名参数
const sum2 = await client.add({ a: 10, b: 20 });

// 上传文件
const result = await client.upload_image(
  fs.readFileSync('./photo.jpg'),
  'My Photo'
);
// 或
const result2 = await client.upload_image({
  image: './photo.jpg', // 本地路径（仅本地模式有效）
  caption: 'My Photo'
});

支持的类型映射

| Python 类型 | JavaScript 类型 | 说明 | |--------------|----------------|------| | str | string | 字符串 | | int / float | number | 数字 | | bool | boolean | 布尔值 | | dict | object | 对象（JSON） | | list | array | 数组（JSON） | | bytes / file | Buffer 或文件路径 | 二进制数据或文件 | | datetime | Date | 日期时间 |

注：服务端注册时使用 JavaScript 类型名（如 'number'），但元数据 /funcs 返回 Python 类型名（如 'int'），以兼容 Python 客户端。

本地模式优化

当客户端通过 localhost、127.0.0.1 等地址连接服务端时，系统自动启用“本地模式”：

• 上传文件：若传入本地文件路径（字符串），服务端直接读取文件内容，避免传输。
• 返回文件：服务端将结果写入临时文件并返回路径，客户端读取后自动删除临时文件。

这极大提升了大文件处理的效率，同时保持远程调用的 API 一致性。

错误处理

• 服务端函数抛出异常 → 客户端捕获为 Error。
• 参数缺失、类型错误、函数不存在等 → 返回 400/404 错误。
• 服务端内部错误 → 返回 500 错误。

限制

• 所有服务端函数必须是 异步 或返回 Promise（即使逻辑是同步的）。
• 函数参数必须通过单个对象传入（{ a, b }），不支持多个独立参数。
• 不支持嵌套复杂类型（如 list[dict]），需自行序列化为 str 或 bytes。

适用场景

• 微服务间简单函数调用
• 前后端分离中的后端逻辑封装
• 脚本与服务端工具集成（如自动化测试、数据处理）
• 本地开发时快速暴露工具函数供 CLI 或 GUI 调用

FastRPC.js 让远程调用像本地函数一样简单，同时不失类型安全与性能优化。