调用协议

基本参数

参数名	类型	描述
id	string	调用唯一标识符（推荐 ULID）
code	number	调用类型码

0. 请求

发起一个请求

定义

参数名	类型	描述
code	0	请求码
name	string	请求调用的方法名
data?	请求方法提供	请求的参数

示例

{
  id: "01JSRMV07VY3B4H227FYWEMKM9",
  code: 0,
  name: "getUserInfo",
  data: {
    id: "1234567890"
  }
}

1. 响应

请求处理响应（请求完成）

定义

参数名	类型	描述
code	1	响应码
data?	请求方法提供	响应的结果

示例

{
  id: "01JSRMV07VY3B4H227FYWEMKM9",
  code: 1,
  data: {
    id: "1234567890",
    name: "匿名用户"
  }
}

2. 正在执行

已收到请求，正在执行（请求未完成）

定义

参数名	类型	描述
code	2	正在执行码
time?	number	请求超时

示例

{
  id: "01JSRMV07VY3B4H227FYWEMKM9",
  code: 2
}

3. 错误

请求处理错误（请求完成）

定义

参数名	类型	描述
code	3	错误码
data	object	错误对象
data.name	string	错误名称
data.message	string	错误信息
data.error?	string	错误堆栈

示例

{
  id: "01JSRMV07VY3B4H227FYWEMKM9",
  code: 3,
  data: {
    name: "NotFoundError",
    message: "用户不存在",
    error: "NotFoundError: 用户不存在\n    at makeError (/root/Philia/src/util/common.ts:12:24)"
  }
}

⏰ 超时处理

默认定义的超时值

参数名	默认值	描述
send	5秒	发送
wait	1分钟	等待
idle	5分钟	空闲
retry	3次	重试

请求发起5秒(send)内，必须收到响应，若收到 2. 正在执行 则按其超时时间处理，默认1分钟(wait)。

所以为避免超时，不能立即处理完成的方法，必须先发送 2. 正在执行 再执行。

在 TypeScript 实现中：

• 请求同步方法 → 1. 响应
• 请求异步方法 → 2. 正在执行 → 1. 响应

超时会触发重试机制，客户端会缓存请求的结果5分钟(idle)，遇到请求重试，则返回缓存结果。

💓 心跳

心跳包，用于检测连接是否正常，默认5分钟(idle)请求一次 heartbeat 方法，该方法无响应结果。

📝 获取可用方法

方法名	返回值	描述
getHandleList	string[]	获取所有方法名