# @gravity-ui/sdk 中文文档

规范地址：https://npmcn.com/package/%40gravity-ui/sdk/

版本：2\.2\.0
npm 元数据更新时间：2026-11-09T09:46:19.385Z
中文译文更新时间：2026-11-16T23:46:40.199Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：150 kB，41 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：5 个
- peer 依赖：@gravity-ui/gateway \>=1\.0\.4
- 首次发布：2023-08-25T16:14:22.445Z
- 最新版本发布：2026-11-09T09:46:19.213Z
- 近 30 天下载量：32763（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：15（近 12 个月 3 个）

## 中文简介

SDK 与 REST/GRPC API 合作实施

## 安装

```sh
npm install @gravity-ui/sdk
```

也可以使用：`pnpm add @gravity-ui/sdk`、`yarn add @gravity-ui/sdk`、`bun add @gravity-ui/sdk`

## README

# @gravity-ui/sdk ! (简体中文) [![npm package](https://img.shields.io/npm/v/@gravity-ui/sdk)](https://www.npmjs.com/package/@gravity-ui/sdk) [![CI](https://img.shields.io/github/actions/workflow/status/gravity-ui/sdk/.github/workflows/ci.yml?label=CI&logo=github)](https://github.com/gravity-ui/sdk/actions/workflows/ci.yml?query=branch:main)

SDK 与 REST/GRPC API 合作实施

## 安装

```shell
npm install --save-dev @gravity-ui/sdk
```

## 使用量

您需要导入 `sdkFactory` 财务报告和审定财务报表 `Schema`,并创建一个类的例子.

如果计划不分为范围:

```typescript
import sdkFactory from '@gravity-ui/sdk';
import type Schema from '<schemas package>';

const config = {
  csrfToken: 'secret-token',
  endpoint: '/gateway',
};

const sdk = sdkFactory<{root: typeof Schema}>(config);
```

如果计划被分成了范围:

```typescript
import sdkFactory from '@gravity-ui/sdk';
import type Schema from '<schemas package>';
import type LocalSchema from '../../shared/schemas';

const config = {
  csrfToken: 'secret-token',
  endpoint: '/gateway',
};

const sdk = sdkFactory<{root: typeof Schema; local: typeof LocalSchema}>(config);
```

结构 `config`数字 :

```typescript
import {AxiosRequestConfig} from 'axios';

interface SdkConfig {
  // Custom Axios settings
  axiosConfig?: AxiosRequestConfig;
  // CSRF-token
  csrfToken?: string;
  // The endpoint to which the request from the client will be sent. By default, "/api" is used
  endpoint?: string;
  // Custom error handler. If the configuration is not specified, the default one is used
  handleRequestError?: (error: unknown) => any;
}
```

在代码中,SDK方法的引用看起来是这样:

```javascript
sdk.<scope>.<service>.<action>(data, options); // => returns a CancelablePromise
```

如果默认终点值 `/api` 指定,完整的请求路径将像这样 :

`/api/:scope/:service/:action`

有一个特殊的范围叫 `root`其方法在不明确规定范围的情况下可以使用.

以下电话等同:

`sdk.root.<service>.<action>(data, options);`

`sdk.<service>.<action>(data, options);`

但完整的请求路径总是包括范围:

`/api/root/:service/:action`

结构 `options`数字 :

```typescript
interface SdkOptions {
  // Request identifier. The previous request with the same identifier will be canceled
  concurrentId?: string;
  // Ability to specify a specific number of retries for certain endpoints. By default, the number of retries is 0
  retries?: number;
  // Ability to specify a specific timeout for certain endpoints.
  // By default, the configuration is taken from axiosConfig or set to 60 seconds
  timeout?: number;
  // Ability to specify specific headers when making a call
  headers?: Record<string, unknown>;
  // Abort the request, including a response stream that is being read
  signal?: AbortSignal;
}
```

## 简化答复

与 `stream: true` 请求通过轴取适配器,承诺与反应机构作为一个 `ReadableStream<Uint8Array>` 头头一到 网关行动必须源源不断地作出反应,例如,REST行动必须与 `responseType: 'stream'`。 。 。 .

```typescript
const stream = await sdk.<scope>.<service>.<action>(data, {stream: true, signal});
const reader = stream.pipeThrough(new TextDecoderStream()).getReader();

for (let chunk = await reader.read(); !chunk.done; chunk = await reader.read()) {
  console.log(chunk.value);
}
```

超时一直运行到流结束, 所以流请求没有超时, 除非 `timeout` 通过。 一旦反应信头到达, `cancel()` 财务报告和审定财务报表 `concurrentId` 不再影响请求 : `signal` 或者说 `reader.cancel()`。从正文读出网关错误,并照常予以拒绝 `signal` 中止读取出错的正文.

## 援引外部方法

通过 `sdk`,您有能力调用外部方法,这些方法在计划中没有定义。 这样的电话看起来是这样的:

`sdk(config, options);`

论点 `config` 有类型 `AxiosRequestConfig`,参数选项有类型 `SdkOptions` 说明.

## 可撤销的承诺

为了创造可以取消的承诺,套件输出一个叫做 `CancellablePromise(promise: Promise, cancel: () => void)`。 。 。 .

## 其他方法

### sdk.setLang () (中文(简体) )

允许设置用户语言, 语言将通过特殊方式传递到所有引用的端点 `accept-language` 头曰.

### sdk.set 默认页眉 ()

允许设置将传递到所有引用的端点的基头 .

## 常见问题

### @gravity-ui/sdk 是什么？

SDK 与 REST/GRPC API 合作实施

### 如何安装 @gravity-ui/sdk？

在项目目录运行 npm install @gravity-ui/sdk，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@gravity-ui/gateway（\>=1\.0\.4）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @gravity-ui/sdk 支持 TypeScript 吗？

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

### @gravity-ui/sdk 支持 ESM 还是 CommonJS？

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

### @gravity-ui/sdk 可以商用吗？

@gravity-ui/sdk 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @gravity-ui/sdk 的下载量有多少？

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

### @gravity-ui/sdk 还在维护吗？

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

