# @autonomys/rpc 中文文档

规范地址：https://npmcn.com/package/%40autonomys/rpc/

版本：1\.7\.0
npm 元数据更新时间：2026-11-04T13:57:43.305Z
中文译文更新时间：2026-11-07T07:08:49.567Z
软件包许可：未声明

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40autonomys/rpc
原文对照：https://npmcn.com/package/%40autonomys/rpc/?lang=original
项目主页：https://github.com/autonomys/auto-sdk#readme
源码仓库：https://github.com/autonomys/auto-sdk

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：78.1 kB，69 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：2 个
- 首次发布：2025-03-25T17:26:31.928Z
- 最新版本发布：2026-11-04T13:57:42.127Z
- 近 30 天下载量：2284（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：79（近 12 个月 24 个）

## 中文简介

本套件旨在通过下列功能来方便自定义的RPC协议的执行:

## 安装

```sh
npm install @autonomys/rpc
```

也可以使用：`pnpm add @autonomys/rpc`、`yarn add @autonomys/rpc`、`bun add @autonomys/rpc`

## README

# @ autonomys/ rpc

本套件旨在通过下列功能来方便自定义的RPC协议的执行:

-   强大的连接控制器(如重联手柄).
-   内建RPC协议.
-   创建类型安全的 api 定义 .

## 类型安全 RPC API

此软件包的目标之一是在实施RPC服务器时实现类型安全,并方便RPC客户端的创建.

为了解决这个问题,我们应该建立一个 `ApiDefinition` 基本上包括RPC方法的定义及其投入或输出.

示例

```ts
const apiDefinition = createApiDefinition({
  test: {
    params: z.object({ name: z.string() }),
    returns: z.object({ name: z.string() }),
  },
})
```

上面的对象定义了带有单个的 RPC 服务器 `test` 作为参数接收的方法 `{ name: string }` 并返回同样的.

通常,我们想要验证 输入和输出 正在正确构建 尊重定义的类型。 因此,类型定义接受任何 [标准Schema](https://standardschema.dev/) (如zod, Valibot 或 ArkType). 与zod的验证需要zod QQ 3.24:更古老的版本不执行标准Schema,因此他们的计数计划无法进行打字检查. 但是,如果出于某种原因,你不想执行验证器,你可以使用这种方法 `defineUnvalidatedType<T>()`数字 :

```ts
type TypeWithNoValidation = string // Any type could be used here

const apiDefinition = createApiDefinition({
  test: {
    params: z.object({ name: z.string() }),
    returns: defineUnvalidatedType<TypeWithNoValidation>(),
  },
})
```

参数和结果作为JSON发送并解析到另一边,所以一个有变换或默认的图案有两种. 客户端发送图解输入 `params` 和处理器获得解析输出,而处理器返回 `returns` 和客户端获得解析输出。 例如,与 `returns: z.string().transform((s) => new Date(s))` 处理器返回字符串,客户端得到一个 `Date`一些计划 `unknown` 作为输入,例如 `z.coerce.number()` 在 zod 4 中,或 `z.preprocess(...)`,所以客户端接受那里的任何值,只有服务器拒绝. 在Zod 4 中,我们没有在Zod 4中, `z.coerce.number<number>()` 再次设置输入类型.

### 定义服务器 RPC 处理器

一旦我们的API接口被定义,服务器RPC处理器应该被定义:

```ts
const apiDefinition = createApiDefinition({
  test: {
    params: z.object({ name: z.string() }),
    returns: defineUnvalidatedType<TypeWithNoValidation>(),
  },
})

const server = apiDefinition.createServer({
  test: (params) => {
    return {
      name: params.name,
    }
  },
})

server.listen(8080)
```

您也可以通过 HTTP 服务器、 Express 应用程序或端口 :

```ts
const server = apiDefinition.createServer(
  {
    test: (params) => ({ name: params.name }),
  },
  {
    httpServer: app, // Express app or http.Server instance
    port: 8080,
  },
)
```

### 使用类型安全 RPC 客户端

一旦服务器运行,使用相同的API定义,客户端可以简单地通过:

```ts
const apiDefinition = createApiDefinition({
  test: {
    params: z.object({ name: z.string() }),
    returns: defineUnvalidatedType<TypeWithNoValidation>(),
  },
})

const client = apiDefinition.createClient({
  endpoint: `<ws-server-endpoint>`,
  callbacks: {},
})

client
  .test({
    name: 'log',
  })
  .then((e) => console.log(e)) /// { name: "xyz" }
```

## 设置 RPC 服务器 (w/o 类型安全)

您可以使用 `createRpcServer` 函数带有初始处理器的可选列表。 您可以直接在端口上收听或附着到已有的 HTTP 服务器/ Express app:

```ts
import { createRpcServer } from '@autonomys/rpc'

const rpcServer = createRpcServer({
  initialHandlers: [
    {
      method: 'test',
      handler: () => ({
        jsonrpc: '2.0',
        result: 'success',
        id: 1,
      }),
    },
  ],
})

rpcServer.listen(8080)
```

或者通过 `port` 或快递 `app` 直接 :

```ts
const rpcServer = createRpcServer({
  httpServer: app, // optional: Express application or http.Server
  port: 8080,      // optional: auto-starts listening on port
  initialHandlers: [...],
})
```

## 设置 RPC 客户端( w/o 类型安全)

您可以通过使用 `createRpcClient` 函数。 此函数需要一个 WS( S) 端点, 并为某些事件设置回调 。 以下是如何设置的例子:

```ts
import { createRpcClient } from '../../src'

const setupRpcClient = async () => {
  const rpcClient = createRpcClient({
    endpoint: `ws://localhost:8080`,
    callbacks: {},
  })

  return rpcClient
}

// Example usage
const rpcClient = await setupRpcClient()

const response = await rpcClient.send({
  jsonrpc: '2.0',
  method: 'test',
  id: 1,
  params: {},
})

console.log(response)
```

## 常见问题

### @autonomys/rpc 是什么？

本套件旨在通过下列功能来方便自定义的RPC协议的执行:

### 如何安装 @autonomys/rpc？

在项目目录运行 npm install @autonomys/rpc，或使用 pnpm add / yarn add / bun add。

### @autonomys/rpc 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @autonomys/rpc 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @autonomys/rpc 可以商用吗？

@autonomys/rpc 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

### @autonomys/rpc 的下载量有多少？

根据 npm 官方下载统计，@autonomys/rpc 在 2026/10/07 – 2026/11/05 这 30 天内被下载 2,284 次，日均约 76 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @autonomys/rpc 还在维护吗？

最新版本 1\.7\.0 发布于 2026/11/04（3 天前）；至今共发布 79 个版本，其中过去 12 个月发布了 24 个；首次发布于 2025/03/26。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。