反金属类型Script API 库
)
这个库提供从服务器侧的TypeScript或JavaScript方便地访问Antimet REST API.
REST API 文档可见于 文件: antimetal.com。此库的全部 API 可以在 日记。 。 。 .
它的产生与 无污。 。 。 .
安装
npm install @antimetal/sdk
使用量
此库的全部 API 可在 日记。 。 。 .
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定义. 你可以这样导入和使用它们:
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 将扔出 :
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 选项以配置或禁用此选项:
// 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 选项 :
// 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 被抛出.
请注意,哪些时间是 默认重审两次。 。 。 .
自动涂鸦
Antimetal API中的列表方法被标出.
你可以用这个 for await … of 在所有页面中通过项目排列的语法 :
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;
}
或者,您可以一次请求一页:
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() 这种方法消耗了身体,一旦解析就返回.
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);
日志
[大 所有日志消息仅用于调试 。 日志信息的格式和内容 释放之间可能会有变化.
日志级别
日志级别可以配置两种方式:
- 通过
ANTIMETAL_LOG环境变量 - 使用
logLevel客户端选项( 如果设置, 覆盖环境变量)
import Antimetal from '@antimetal/sdk';
const client = new Antimetal({
logLevel: 'debug', // Show all log messages
});
可用的日志水平, 从大多数到最小动词 :
'debug'- 显示调试消息、信息、警告和错误'info'- 显示信息信息、警告和错误'warn'- 显示警告和错误(默认)'error'- 只显示出错'off'- 禁用所有记录
在那个 'debug' 级别、所有HTTP请求和答复都登录,包括信头和正文.
一些与认证相关的头被编辑,但在请求和响应机构中有敏感数据
可能仍然可见.
自定义日志
默认情况下,此库日志将 globalThis.console。也可以提供自定义日志.
大多数伐木库都得到支持,包括: 皮诺, (中文(简体) ), 温通, (中文(简体) ), 包扬, (中文(简体) ), 康索拉语name, (中文(简体) ), 信号,以及 @ std/ log (帮助)如果您的日志不工作,请打开一个问题.
当提供自定义日志时 logLevel 选项仍然控制哪些消息被发送,消息
在配置的关卡以下将不会发送到您的日志 .
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动词.
在提出这些请求时,将尊重客户端的选项,例如复试.
await client.post('/some/path', {
body: { some_prop: 'foo' },
query: { some_query_arg: 'bar' },
});
无文件请求段落
要使用无证参数提出请求, 您可以使用 // @ts-expect-error 关于无证件者
参数。 此库不会在运行时验证请求是否与类型相匹配, 所以任何额外的值
发送将按.
client.issues.create({
// ...
// @ts-expect-error baz is not yet public
baz: 'undocumented option',
});
申请与 GET 动词,任何额外的参数都会在查询中,所有其他请求都会发送
身体里有额外的参数.
如果你想明确发送一个额外的参数,你可以这样做与 query, (中文(简体) ), body,以及 headers 请求
选项.
无文件回复属性
要访问无证响应属性, 您可以访问响应对象 // @ts-expect-error 打开
,或者将响应对象投放到必要的类型。 像请求的段落,我们不
验证或从 API 的响应中脱去额外的属性.
自定义获取客户端
默认情况下, 此库需要全局 fetch 函数被定义.
如果你想用另一个 fetch 函数,可以同时填充全局 :
import fetch from 'my-fetch';
globalThis.fetch = fetch;
或传给客户:
import Antimetal from '@antimetal/sdk';
import fetch from 'my-fetch';
const client = new Antimetal({ fetch });
获取选项
如果你想设置自定义 fetch 选项,而不压倒 fetch 函数,您可以提供 fetchOptions 当即决客户端或提出请求时对象。 (请求特定选项压倒客户选项. )
import Antimetal from '@antimetal/sdk';
const client = new Antimetal({
fetchOptions: {
// `RequestInit` options
},
});
配置代理人
要修改代理行为, 您可以提供自定义 fetchOptions 添加运行时特定代理
请求的选项:
节点 [文档[ . ]
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,
},
});
阿宝 [文档[ . ]
import Antimetal from '@antimetal/sdk';
const client = new Antimetal({
fetchOptions: {
proxy: 'http://localhost:8888',
},
});
德诺 [文档[ . ]
import Antimetal from 'npm:@antimetal/sdk';
const httpClient = Deno.createHttpClient({ proxy: { url: 'http://localhost:8888' } });
const client = new Antimetal({
fetchOptions: {
client: httpClient,
},
});
经常被问到的问题
语义版本
这套套件一般沿用 交换器 虽然某些向后兼容的修改可以作为小版本发布:
- 仅影响静态类型的变化,而不突破运行时的行为.
- 图书馆内部的改动,技术上是公开的,但并非打算或记录外部使用的. (请打开一个 GitHub 问题让我们知道, 如果你依赖这样的内部。 )
- 我们预计不会在实践中影响到绝大多数用户的变化.
我们认真对待倒向相容性,并努力地确保你能够依靠平稳的升级经验.
我们很期待你的反馈,请打开 问题 包括问题、错误或建议.
所需资源
TypeScript QQ 4.9 得到支持.
支持以下运行时间:
- 网页浏览器(最新Chrome、Firefox、Safari、Edge等)
- 节点.js 20 LTS 或以后(非欧洲)版本.
- 德诺v1.28.0以上.
- 1.0号或以后.
- 云浮活计.
- Vercel Edge 运行时段.
- 28岁以上
"node"环境"jsdom"目前不支持). - Nitro v 2.6 或 更强.
注意React Industrial此时不支持.
如果您对其它运行时间环境感兴趣, 请在 GitHub 上打开或投票 .
捐款
见 提供的文件。 。 。 .