# @nilejs/client 中文文档

规范地址：https://npmcn.com/package/%40nilejs/client/

版本：1\.0\.1
npm 元数据更新时间：2026-11-01T22:48:59.950Z
中文译文更新时间：2026-11-02T00:36:51.808Z
软件包许可：未声明

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

原始 npm 页面：https://www.npmjs.com/package/%40nilejs/client
原文对照：https://npmcn.com/package/%40nilejs/client/?lang=original

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

- 包体积（解压后）：102 kB，8 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- 首次发布：2026-02-28T20:56:22.573Z
- 最新版本发布：2026-11-01T22:48:59.788Z
- 已发布版本数：5（近 12 个月 5 个）

## 中文简介

用于Nile后端框架的独立、类型安全的客户端

## 安装

```sh
npm install @nilejs/client
```

也可以使用：`pnpm add @nilejs/client`、`yarn add @nilejs/client`、`bun add @nilejs/client`

## README

# @nilejs /客户端

类型安全的前端客户端 [尼罗河Js](https://nile-js.github.io/nile/) 后端。

## 功能

-   **类型安全的:** 为服务、操作和有效负载检查使用共享或cli生成的后端类型。
-   **优雅的错误处理：** 返回与Nile Js后端相同的Result模式(`isOk`， `isErr`， `value`， `error`)，而不是抛出异常。
-   **小:** HTTP调用使用平台 `fetch`． 唯一的运行时依赖项是 `socket.io-client`，用于套接字客户端。
-   **灵活:** 支持每个请求的自定义标头、凭据和超时。

## 安装

```bash
# Using npm
npm install @nilejs/client

# Using pnpm
pnpm add @nilejs/client

# Using bun
bun add @nilejs/client
```

## 使用

### 1\. 创建客户端

```typescript
import { createNileClient } from "@nilejs/client";

const nile = createNileClient({
  baseUrl: "http://localhost:8000/api",
  credentials: "include",
});
```

### 2\. 调用动作

```typescript
const result = await nile.invoke({
  service: "tasks",
  action: "create",
  payload: { title: "Buy milk" },
});

if (result.isErr) {
  console.error("Action failed:", result.error);
} else {
  console.log("Success:", result.value);
}
```

### 3\. 全型安全（推荐）

使用Nile CLI生成类型： `nile generate schema --output ./src/generated`

然后使用生成的 `ServicePayloads` 地图:

```typescript
import { createNileClient } from "@nilejs/client";
import type { ServicePayloads } from "./generated/types";

const nile = createNileClient<ServicePayloads>({ 
  baseUrl: "/api" 
});

// Full autocomplete and type-checking for service, action, and payload
await nile.invoke({
  service: "tasks",
  action: "create",
  payload: { title: "Buy milk" }
});
```

### 4\. 发现与反思

```typescript
// Explore services and actions
const services = await nile.explore({ service: "*", action: "*" });

if (services.isOk) {
  console.log(services.value);
}

// Fetch action schemas
const schemas = await nile.schema({ service: "tasks", action: "*" });

if (schemas.isOk) {
  console.log(schemas.value);
}
```

## API

### `createNileClient<T>(config)`

返回一个Nile客户端实例。

-   `config.baseUrl`：你的Nile API的基础URL(例如： `http://localhost:8000/api`）。
-   `config.credentials`：请求凭证(`include`， `omit`， `same-origin`）。
-   `config.headers`：每个请求中包含的全局标头。
-   `config.timeout`：默认请求超时时间，单位为毫秒（默认：30000）。

### 方法

所有方法都返回 `Promise<ClientResult<T>>`． 调用从不抛出：

-   成功: `{ isOk: true, isErr: false, value: T, error: null, message? }`,在那里 `message` HTTP调用的服务器成功消息是什么
-   失败: `{ isOk: false, isErr: true, value: null, error: string, details }`,在那里 `details` 保存服务器附加的任何数据，例如验证问题。网络故障和超时也是故障。

检查 `isErr` 首先，然后阅读 `error` 或者 `value`． 年长的 `data` 字段仍然作为弃用别名存在(成功时的值， `null` （当失败时），现有的代码继续工作。

-   `invoke(params)`：执行特定的服务动作。
-   `explore(params)`：使用通配符发现服务/操作。
-   `schema(params)`：以JSON模式获取动作模式。

传入每个呼叫设置 `fetchOptions`． 报头与客户端配置的报头合并；无论大小写如何，每次调用的值都会覆盖相同的标头。两个 `Headers` 支持实例和头元组。超时包括读取响应体和连接；一个可选的 `signal` 可以取消通话。

```ts
const controller = new AbortController();
const result = await nile.invoke({
  service: "tasks",
  action: "create",
  payload: { title: "Ship the next feature" },
  fetchOptions: {
    headers: { Authorization: "Bearer your-session-token" },
    timeout: 5000,
    signal: controller.signal,
  },
});
```

## 尼罗河1.0.3响应

HTTP响应包含 `status`， `message` 和 `data`． 客户端将这些映射到其现有的Result API；它保留自定义消息、Zod的美化验证消息和生成的诊断引用。默认的成功消息为 `Action completed.`

对于验证失败， `result.error` 消息是否可读 `result.details` 包含 `{ errorCode, issues }`. `ValidationFailureData` 为缩小此未知故障数据的应用程序导出。其他的失败可能会带来不同的细节，所以在使用它之前检查它的形状。诊断故障可能包括 `Error Code: <unique-code> - <message>` 在留言中。将代码视为与后端日志共享的引用；不要将其作为固定的错误类别。

## 套接字。IO操作和主题

创建一个单独的套接字客户端。它拥有连接；您不需要在每次调用中传递套接字。使用共享类型、生成的操作类型，或者显式地定义你的前端契约。还必须在后端配置主题定义和授权策略。

```ts
import { createNileSocketClient } from "@nilejs/client";
import type { ServicePayloads } from "./generated/types";

type Topics = {
  "tasks.changed": {
    data: { taskId: string; status: string };
  };
};

const socket = createNileSocketClient<ServicePayloads, Topics>({
  baseUrl: "http://localhost:8000",
  auth: () => {
    return { token: "your-session-token" };
  },
});

const subscription = await socket.receive({
  topic: "tasks.changed",
  onMessage: (message) => {
    console.log(message.data.taskId, message.data.status);
  },
});

const result = await socket.invoke({
  service: "tasks",
  action: "create",
  payload: { title: "Ship the next feature" },
});

const publication = await socket.send({
  topic: "tasks.changed",
  data: { taskId: "task-123", status: "done" },
});

if (subscription.isOk) {
  await subscription.value.unsubscribe();
}
socket.close();
```

只要应用程序需要实时更新，就保持客户端打开。连接是惰性的，订阅在重新连接后重新加入，并且不自动缓冲或重试断开的写操作。从提供的类型中检查主题名称、数据和任何所需的范围；Nile对它们进行验证，并在后端执行策略。服务器可以同时公开HTTP和套接字。看到 [尚](https://nile-js.github.io/nile/guide/features/websockets/) 用于服务器设置。

## 上传

```ts
const result = await nile.upload({
  service: "documents",
  action: "upload",
  files: { document: file },
  fields: { title: "Invoice" },
  fetchOptions: { timeout: 60000 },
});
```

多部分调用与JSON调用共享相同的取消、截止日期和结果行为。Content-Type由运行时设置，因此多部分边界是正确的。

## 兼容性

版本1.0.1支持Nile 1.0.3和1.0.4，同时保留现有的HTTP和套接字客户端api。它修复了标头合并、取消和超时清理；它不会在Nile的有线合同中增加油田。

## 许可证

麻省理工学院

## 常见问题

### @nilejs/client 是什么？

用于Nile后端框架的独立、类型安全的客户端

### 如何安装 @nilejs/client？

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

### @nilejs/client 支持 TypeScript 吗？

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

### @nilejs/client 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @nilejs/client 可以商用吗？

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

### @nilejs/client 还在维护吗？

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