# @antimetal/sdk 中文文档

规范地址：https://npmcn.com/package/%40antimetal/sdk/

版本：0\.2\.2
npm 元数据更新时间：2026-05-26T17:48:07.024Z
中文译文更新时间：2026-11-06T06:47:45.541Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：951 kB，462 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2026-03-02T16:24:03.803Z
- 最新版本发布：2026-03-17T22:05:25.216Z
- 近 30 天下载量：27457（2026-10-06 至 2026-11-04，npm 官方下载统计）
- 已发布版本数：3（近 12 个月 3 个）

## 中文简介

Antimetal API 的官方 TypeScript 库

## 安装

```sh
npm install @antimetal/sdk
```

也可以使用：`pnpm add @antimetal/sdk`、`yarn add @antimetal/sdk`、`bun add @antimetal/sdk`

## README

# 反金属类型Script API 库

[![NPM version](https://img.shields.io/npm/v/@antimetal/sdk.svg?label=npm%20\(stable\))](https://npmjs.org/package/@antimetal/sdk) ![npm bundle size](https://img.shields.io/bundlephobia/minzip/@antimetal/sdk)

这个库提供从服务器侧的TypeScript或JavaScript方便地访问Antimet REST API.

REST API 文档可见于 [文件: antimetal.com](https://docs.antimetal.com/)。此库的全部 API 可以在 [日记](https://npmcn.com/package/%40antimetal/sdk/api.md)。 。 。 .

它的产生与 [无污](https://www.stainless.com/)。 。 。 .

## 安装

```sh
npm install @antimetal/sdk
```

## 使用量

此库的全部 API 可在 [日记](https://npmcn.com/package/%40antimetal/sdk/api.md)。 。 。 .

```js
import Antimetal from '@antimetal/sdk';

const client = new Antimetal({
  apiKey: process.env['ANTIMETAL_API_KEY'], // This is the default and can be omitted
  environment: 'dev', // defaults to 'production'
});

const issue = await client.issues.create({
  description: 'x',
  environment: 'x',
  title: 'x',
});

console.log(issue.uuid);
```

### 请求响应类型( A)

这个库包括所有请求参数和响应字段的TypeScript定义. 你可以这样导入和使用它们:

```ts
import Antimetal from '@antimetal/sdk';

const client = new Antimetal({
  apiKey: process.env['ANTIMETAL_API_KEY'], // This is the default and can be omitted
  environment: 'dev', // defaults to 'production'
});

const params: Antimetal.IssueCreateParams = {
  description: 'x',
  environment: 'x',
  title: 'x',
};
const issue: Antimetal.IssueCreateResponse = await client.issues.create(params);
```

每种方法的文件、请求参数和响应字段都以道克字符串形式提供,并将出现在大多数现代编辑中.

## 处理错误

当库无法连接到API时, 或者如果API返回一个非成功状态代码(即4xx或5xx回复), 子类 `APIError` 将扔出 :

```ts
const issue = await client.issues
  .create({
    description: 'x',
    environment: 'x',
    title: 'x',
  })
  .catch(async (err) => {
    if (err instanceof Antimetal.APIError) {
      console.log(err.status); // 400
      console.log(err.name); // BadRequestError
      console.log(err.headers); // {server: 'nginx', ...}
    } else {
      throw err;
    }
  });
```

出错代码如下:

| 身份代码 | 错误类型 |
| --- | --- |
| 400个 | `BadRequestError` |
| 401 (中文(简体) ) | `AuthenticationError` |
| 403 (韩语) | `PermissionDeniedError` |
| 404 (韩语) | `NotFoundError` |
| 422个 | `UnprocessableEntityError` |
| 429个 | `RateLimitError` |
| \>=500 | `InternalServerError` |
| 不详 | `APIConnectionError` |

### 检索

某些出错默认会自动重试2次,并有短暂的指数后退. 连接出错(例如由于网络连接问题) 408 请求超时, 409 相冲突, 429 限制费率,和 QQ500 内部出错都会默认重审.

你可以用这个 `maxRetries` 选项以配置或禁用此选项:

```js
// Configure the default for all requests:
const client = new Antimetal({
  maxRetries: 0, // default is 2
});

// Or, configure per-request:
await client.issues.create({
  description: 'x',
  environment: 'x',
  title: 'x',
}, {
  maxRetries: 5,
});
```

### 超时

默认1分钟后请求暂停 。 您可以用一个 `timeout` 选项 :

```ts
// Configure the default for all requests:
const client = new Antimetal({
  timeout: 20 * 1000, // 20 seconds (default is 1 minute)
});

// Override per-request:
await client.issues.create({
  description: 'x',
  environment: 'x',
  title: 'x',
}, {
  timeout: 5 * 1000,
});
```

超时,一个 `APIConnectionTimeoutError` 被抛出.

请注意,哪些时间是 [默认重审两次](https://npmcn.com/package/%40antimetal/sdk/#readme-retries)。 。 。 .

## 自动涂鸦

Antimetal API中的列表方法被标出. 你可以用这个 `for await … of` 在所有页面中通过项目排列的语法 :

```ts
async function fetchAllIssueListResponses(params) {
  const allIssueListResponses = [];
  // Automatically fetches more pages as needed.
  for await (const issueListResponse of client.issues.list()) {
    allIssueListResponses.push(issueListResponse);
  }
  return allIssueListResponses;
}
```

或者,您可以一次请求一页:

```ts
let page = await client.issues.list();
for (const issueListResponse of page.data) {
  console.log(issueListResponse);
}

// Convenience methods are provided for manually paginating:
while (page.hasNextPage()) {
  page = await page.getNextPage();
  // ...
}
```

## 高级使用

### 获取原始响应数据(例如信头)

那个"行" `Response` 返回时间 `fetch()` 可通过 `.asResponse()` 方法 `APIPromise` 键入所有方法返回. 此方法一旦收到成功的响应信头即返回,而不消耗响应正文,所以您可以自由写入自定义解析或流出逻辑.

你也可以使用这个 `.withResponse()` 获取原始数据的方法 `Response` 与解析数据一起. 与 `.asResponse()` 这种方法消耗了身体,一旦解析就返回.

```ts
const client = new Antimetal();

const response = await client.issues
  .create({
    description: 'x',
    environment: 'x',
    title: 'x',
  })
  .asResponse();
console.log(response.headers.get('X-My-Header'));
console.log(response.statusText); // access the underlying Response object

const { data: issue, response: raw } = await client.issues
  .create({
    description: 'x',
    environment: 'x',
    title: 'x',
  })
  .withResponse();
console.log(raw.headers.get('X-My-Header'));
console.log(issue.uuid);
```

### 日志

> \[大 所有日志消息仅用于调试 。 日志信息的格式和内容 释放之间可能会有变化.

#### 日志级别

日志级别可以配置两种方式:

1.  通过 `ANTIMETAL_LOG` 环境变量
2.  使用 `logLevel` 客户端选项( 如果设置, 覆盖环境变量)

```ts
import Antimetal from '@antimetal/sdk';

const client = new Antimetal({
  logLevel: 'debug', // Show all log messages
});
```

可用的日志水平, 从大多数到最小动词 :

-   `'debug'` - 显示调试消息、信息、警告和错误
-   `'info'` - 显示信息信息、警告和错误
-   `'warn'` - 显示警告和错误(默认)
-   `'error'` - 只显示出错
-   `'off'` - 禁用所有记录

在那个 `'debug'` 级别、所有HTTP请求和答复都登录,包括信头和正文. 一些与认证相关的头被编辑,但在请求和响应机构中有敏感数据 可能仍然可见.

#### 自定义日志

默认情况下,此库日志将 `globalThis.console`。也可以提供自定义日志. 大多数伐木库都得到支持,包括: [皮诺](https://www.npmjs.com/package/pino), (中文(简体) ), [温通](https://www.npmjs.com/package/winston), (中文(简体) ), [包扬](https://www.npmjs.com/package/bunyan), (中文(简体) ), [康索拉语name](https://www.npmjs.com/package/consola), (中文(简体) ), [信号](https://www.npmjs.com/package/signale),以及 [@ std/ log (帮助)](https://jsr.io/@std/log)如果您的日志不工作,请打开一个问题.

当提供自定义日志时 `logLevel` 选项仍然控制哪些消息被发送,消息 在配置的关卡以下将不会发送到您的日志 .

```ts
import Antimetal from '@antimetal/sdk';
import pino from 'pino';

const logger = pino();

const client = new Antimetal({
  logger: logger.child({ name: 'Antimetal' }),
  logLevel: 'debug', // Send all messages to pino, allowing it to filter
});
```

### 提出自定义/无文件记录的请求

此库的打入是为了方便地访问有文献记载的API. 如果您需要访问无证 端点,参数,或响应属性,库仍然可以被使用.

#### 无记录的终点

要向无记录的端点提出请求, 您可以使用 `client.get`, (中文(简体) ), `client.post`,以及其他HTTP动词. 在提出这些请求时,将尊重客户端的选项,例如复试.

```ts
await client.post('/some/path', {
  body: { some_prop: 'foo' },
  query: { some_query_arg: 'bar' },
});
```

#### 无文件请求段落

要使用无证参数提出请求, 您可以使用 `// @ts-expect-error` 关于无证件者 参数。 此库不会在运行时验证请求是否与类型相匹配, 所以任何额外的值 发送将按.

```ts
client.issues.create({
  // ...
  // @ts-expect-error baz is not yet public
  baz: 'undocumented option',
});
```

申请与 `GET` 动词,任何额外的参数都会在查询中,所有其他请求都会发送 身体里有额外的参数.

如果你想明确发送一个额外的参数,你可以这样做与 `query`, (中文(简体) ), `body`,以及 `headers` 请求 选项.

#### 无文件回复属性

要访问无证响应属性, 您可以访问响应对象 `// @ts-expect-error` 打开 ,或者将响应对象投放到必要的类型。 像请求的段落,我们不 验证或从 API 的响应中脱去额外的属性.

### 自定义获取客户端

默认情况下, 此库需要全局 `fetch` 函数被定义.

如果你想用另一个 `fetch` 函数,可以同时填充全局 :

```ts
import fetch from 'my-fetch';

globalThis.fetch = fetch;
```

或传给客户:

```ts
import Antimetal from '@antimetal/sdk';
import fetch from 'my-fetch';

const client = new Antimetal({ fetch });
```

### 获取选项

如果你想设置自定义 `fetch` 选项,而不压倒 `fetch` 函数,您可以提供 `fetchOptions` 当即决客户端或提出请求时对象。 (请求特定选项压倒客户选项. )

```ts
import Antimetal from '@antimetal/sdk';

const client = new Antimetal({
  fetchOptions: {
    // `RequestInit` options
  },
});
```

#### 配置代理人

要修改代理行为, 您可以提供自定义 `fetchOptions` 添加运行时特定代理 请求的选项:

![](https://raw.githubusercontent.com/stainless-api/sdk-assets/refs/heads/main/node.svg) **节点** \[[文档](https://github.com/nodejs/undici/blob/main/docs/docs/api/ProxyAgent.md#example---proxyagent-with-fetch)\[ . \]

```ts
import Antimetal from '@antimetal/sdk';
import * as undici from 'undici';

const proxyAgent = new undici.ProxyAgent('http://localhost:8888');
const client = new Antimetal({
  fetchOptions: {
    dispatcher: proxyAgent,
  },
});
```

![](https://raw.githubusercontent.com/stainless-api/sdk-assets/refs/heads/main/bun.svg) **阿宝** \[[文档](https://bun.sh/guides/http/proxy)\[ . \]

```ts
import Antimetal from '@antimetal/sdk';

const client = new Antimetal({
  fetchOptions: {
    proxy: 'http://localhost:8888',
  },
});
```

![](https://raw.githubusercontent.com/stainless-api/sdk-assets/refs/heads/main/deno.svg) **德诺** \[[文档](https://docs.deno.com/api/deno/~/Deno.createHttpClient)\[ . \]

```ts
import Antimetal from 'npm:@antimetal/sdk';

const httpClient = Deno.createHttpClient({ proxy: { url: 'http://localhost:8888' } });
const client = new Antimetal({
  fetchOptions: {
    client: httpClient,
  },
});
```

## 经常被问到的问题

## 语义版本

这套套件一般沿用 [交换器](https://semver.org/spec/v2.0.0.html) 虽然某些向后兼容的修改可以作为小版本发布:

1.  仅影响静态类型的变化,而不突破运行时的行为.
2.  图书馆内部的改动,技术上是公开的,但并非打算或记录外部使用的. _(请打开一个 GitHub 问题让我们知道, 如果你依赖这样的内部。 )_
3.  我们预计不会在实践中影响到绝大多数用户的变化.

我们认真对待倒向相容性,并努力地确保你能够依靠平稳的升级经验.

我们很期待你的反馈,请打开 [问题](https://www.github.com/antimetal/antimetal-node/issues) 包括问题、错误或建议.

## 所需资源

TypeScript QQ 4.9 得到支持.

支持以下运行时间:

-   网页浏览器(最新Chrome、Firefox、Safari、Edge等)
-   节点.js 20 LTS 或以后([非欧洲](https://endoflife.date/nodejs))版本.
-   德诺v1.28.0以上.
-   1.0号或以后.
-   云浮活计.
-   Vercel Edge 运行时段.
-   28岁以上 `"node"` 环境`"jsdom"` 目前不支持).
-   Nitro v 2.6 或 更强.

注意React Industrial此时不支持.

如果您对其它运行时间环境感兴趣, 请在 GitHub 上打开或投票 .

## 捐款

见 [提供的文件](https://npmcn.com/package/%40antimetal/sdk/CONTRIBUTING.md)。 。 。 .

## 常见问题

### @antimetal/sdk 是什么？

Antimetal API 的官方 TypeScript 库

### 如何安装 @antimetal/sdk？

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

### @antimetal/sdk 支持 TypeScript 吗？

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

### @antimetal/sdk 支持 ESM 还是 CommonJS？

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

### @antimetal/sdk 可以商用吗？

@antimetal/sdk 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @antimetal/sdk 的下载量有多少？

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

### @antimetal/sdk 还在维护吗？

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