# @blockscout/api-types 中文文档

规范地址：https://npmcn.com/package/%40blockscout/api-types/

版本：12\.0\.4
npm 元数据更新时间：2026-11-02T13:08:30.418Z
中文译文更新时间：2026-11-08T07:33:01.151Z
软件包许可：LicenseRef-Blockscout

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

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

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

- 包体积（解压后）：8.9 MB，23 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2026-06-05T10:59:24.050Z
- 最新版本发布：2026-11-02T13:08:30.142Z
- 近 30 天下载量：2311（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：31（近 12 个月 31 个）

## 中文简介

由 Blockscout OpenAPI 规格( 公共、 私有和特定链) 生成的脚本类型

## 安装

```sh
npm install @blockscout/api-types
```

也可以使用：`pnpm add @blockscout/api-types`、`yarn add @blockscout/api-types`、`bun add @blockscout/api-types`

## README

# @ blockscout/ api 类型

通过 Blockscout OpenAPI 规格生成的脚本类型 [openapi 类型标记](https://openapi-ts.dev/)数字 :

-   **缩写** (单位:千美元)`schemas`, (中文(简体) ), `operations`, (中文(简体) ), `paths`)——推荐的入门点;平坦地查看被合并的光谱,横跨每一个链条类型. 见 [使用量](https://npmcn.com/package/%40blockscout/api-types/#readme-usage)
-   **合并** – 从下方所有规格的每个计划,路径和操作组合到一个命名空间(对于在运行时处理任何链式类型的通用前端);参见 [合并计划](https://npmcn.com/package/%40blockscout/api-types/#readme-merged-schemas)
-   **公开Api** ——默认公开 API(`BlockScoutWeb.Specs.Public`,没有 `CHAIN_TYPE`(中文(简体) )
-   **隐私Api** - 账户 API(`BlockScoutWeb.Specs.Private`(中文(简体) )
-   **链命名空间** 特定链式公共API(`CHAIN_TYPE` 设置; 匹配 [生成- swagger.yml](https://github.com/blockscout/blockscout/blob/master/.github/workflows/generate-swagger.yml)(中文(简体) )

建造文物(`openapi/`, (中文(简体) ), `dist/`) 被给定; 运行 `npm run build` 复制后.

## 先决条件

-   **Elixir / 混音** blockscout repo 根 (编译) `block_scout_web` 应用)
-   **节点.js** 18+(用于 `openapi-typescript`(中文(简体) )

## 生成

从此目录 :

```bash
npm install
npm run build
```

`build` 运行 :

1.  **`generate:spec`** —— 说 `mix openapi.spec.yaml` 用于公共、私人和每一链型
2.  **`generate:types`** —— 说 `openapi-typescript` 将匹配的文件写入到 `dist/`

## 使用量

### 简称( 建议)

3个顶级出口将最常见的视线固定在合并的光谱上,所以你从来没有通过索引 `components["schemas"]` 或者说 `["responses"][200]["content"]["application/json"]` 手边。 优先供日常使用:

```ts
import type { schemas, operations, paths } from "@blockscout/api-types";

// `schemas` — a model by name (merged across all chains; chain-specific props optional).
type Transaction = schemas["Transaction"];

// `operations` — keyed by short operationId, with `json` / `params` / `requestBody`.
type TxJson = operations["TransactionController.transaction"]["json"];
type TxParams = operations["TransactionController.transaction"]["params"];
type EthCallBody = operations["EthController.eth_call"]["requestBody"];

// `paths` — the 200 `application/json` body keyed by path, then HTTP method.
type Blocks = paths["/api/v2/blocks"]["get"];
```

注释:

-   **操作ID被缩短** ——控制器模块前缀(`BlockScoutWeb.API.V2.`, (中文(简体) ), `BlockScoutWeb.Account.API.V2.`, (中文(简体) ), `BlockScoutWeb.API.Legacy.`)被剥去,所以 `BlockScoutWeb.API.V2.TransactionController.transaction` 变成 `TransactionController.transaction`。 。 。 .
-   `json` 这是200 `application/json` 反应机构; `params` 是请求 `query`编号 :`path` 参数; `requestBody` 这是 `application/json` 请求机构(`never` 没有终点.
-   `paths` 只披露 HTTP 方法, 即实际定义的终点; 缺少方法, 而不是 `never`。 。 。 .
-   三者皆从 `merged`,所以它们已经跨越了每一个链的类型。 到达 `merged`/ 在下方的每个链命名空间, 只有当您需要的东西不覆盖时( 非200 响应, 响应头, 原始路径项目) .

### 合并计划

上面的简称是建立在 **合并** 命名空间——每个从所有光谱组合出来的计划,路径,和操作,因此一个通用前端可以在运行时间从一个单一类型宇宙处理任何链型. 导入 `merged` 当您需要检查时, 短手不暴露( 非200 个响应、 响应头、 原始路径项) :

```ts
import type { merged } from "@blockscout/api-types";

// Includes the public base plus `arbitrum?`, `zksync?`, blob fields, etc. — all optional.
type Transaction = merged.components["schemas"]["Transaction"];

// Paths/operations are merged too, referencing the merged models:
type Tx = merged.paths["/api/v2/transactions/{transaction_hash_param}"]["get"]["responses"][200];
```

### 单相命名空间

类型还按包项中的 spec 名称分组:

```ts
import type { publicApi, privateApi, arbitrum, optimismCelo } from "@blockscout/api-types";

type AddressResponse = publicApi.components["schemas"]["AddressResponse"];

type GetAddressParams =
  publicApi.paths["/api/v2/addresses/{address_hash_param}"]["get"]["parameters"];

type ArbitrumPath = arbitrum.paths[keyof arbitrum.paths];
```

`publicApi` 编号 : `privateApi` 避免 TypeScript 保留单词(`public`, (中文(简体) ), `private`) (中文(简体) ). `optimism-celo` 导出为 `optimismCelo` (标识符中的连字符无效)

## 链型

与 `.github/workflows/generate-swagger.yml` 通过 `scripts/chain-types.sh`数字 :

`arbitrum`, (中文(简体) ), `arc`, (中文(简体) ), `blackfort`, (中文(简体) ), `ethereum`, (中文(简体) ), `filecoin`, (中文(简体) ), `neon`, (中文(简体) ), `optimism`, (中文(简体) ), `optimism-celo`, (中文(简体) ), `rsk`, (中文(简体) ), `scroll`, (中文(简体) ), `shibarium`, (中文(简体) ), `stability`, (中文(简体) ), `suave`, (中文(简体) ), `zetachain`, (中文(简体) ), `zilliqa`, (中文(简体) ), `zksync`

当 CI 添加或删除链式时, 更新 `scripts/chain-types.sh` 财务报告和审定财务报表 `index.ts`。 。 。 .

## 组合图

`scripts/merge-specs.mjs` 将所有生成的光谱( 公共 ) —— 私人 —— 链条按字母顺序合并到 `openapi/merged.yaml`,用于编译 `dist/merged.schema.ts` (以 `merged`) (中文(简体) ).

合并语义 :

-   **示马斯** —— 说 `properties` 工会; `required` 是定义 schema 的相交点, 因此链状特性是可选的 。 在一个光谱中定义的子对象保留其 `required` (例如:. `arbitrum.gas_used_for_l1` 需要保留时 `arbitrum` 页:1. `enum` 数值结合(例如). `transaction_types` 收益链专用条目).
-   **路径操作( O)** ——跨个相通;仅链式终点(如. `/v2/arbitrum/batches`页:1 共享业务已深入开展 `parameters` 与(在名称中)及其 `schema`s结合(如enum查询参数获得链特有值). 所有操作 `$ref`点为 `components.schemas`,因此它们自动引用合并的模型.
-   不可调和的图案形状( 如 ethereum 重新定义) `Status` 作为信标存储器 `anyOf` 工会,并报告为对工会的警告.

## 常见问题

### @blockscout/api-types 是什么？

由 Blockscout OpenAPI 规格\( 公共、 私有和特定链\) 生成的脚本类型

### 如何安装 @blockscout/api-types？

在项目目录运行 npm install @blockscout/api-types，或使用 pnpm add / yarn add / bun add。

### @blockscout/api-types 支持 TypeScript 吗？

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

### @blockscout/api-types 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @blockscout/api-types 可以商用吗？

@blockscout/api-types 使用 LicenseRef-Blockscout 许可。声明的许可为 LicenseRef-Blockscout，请阅读许可原文确认使用条件。以上为概括，不构成法律意见，请以许可原文为准。

### @blockscout/api-types 的下载量有多少？

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

### @blockscout/api-types 还在维护吗？

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