# @elastic\.io/component-commons-library 中文文档

规范地址：https://npmcn.com/package/%40elastic.io/component-commons-library/

版本：4\.0\.3
npm 元数据更新时间：2026-08-14T12:11:48.970Z
中文译文更新时间：2026-11-13T10:49:55.597Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40elastic.io/component-commons-library
原文对照：https://npmcn.com/package/%40elastic.io/component-commons-library/?lang=original
项目主页：https://github.com/elasticio/component-commons-library#readme
源码仓库：https://github.com/elasticio/component-commons-library

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

- 包体积（解压后）：199 kB，59 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=24
- 运行依赖：5 个
- 首次发布：2019-07-15T13:40:34.107Z
- 最新版本发布：2026-08-14T12:11:48.809Z
- 近 30 天下载量：9700（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：155（近 12 个月 4 个）

## 中文简介

用于最常用组件开发案例的图书馆

## 安装

```sh
npm install @elastic.io/component-commons-library
```

也可以使用：`pnpm add @elastic.io/component-commons-library`、`yarn add @elastic.io/component-commons-library`、`bun add @elastic.io/component-commons-library`

## README

# 组件 - 通用图书馆

![](https://github.com/elasticio/splitter-component/blob/master/elastic.io%20Logo%20pure-01.png)

## 目录

-   [说明](https://npmcn.com/package/%40elastic.io/component-commons-library/#readme-description)
-   [可用函数](https://npmcn.com/package/%40elastic.io/component-commons-library/#readme-Available-Functions)
    -   [API 客户端](https://npmcn.com/package/%40elastic.io/component-commons-library/#readme-Platform-API-Clients)
        -   [平台ApiRest客户端](https://npmcn.com/package/%40elastic.io/component-commons-library/#readme-PlatformApiRestClient)
        -   [平台ApiLogic 客户端](https://npmcn.com/package/%40elastic.io/component-commons-library/#readme-PlatformApiLogicClient)
    -   [JSON Schema 转换器](https://npmcn.com/package/%40elastic.io/component-commons-library/#readme-JSON-Schema-Converter)
    -   [JSON 转换](https://npmcn.com/package/%40elastic.io/component-commons-library/#readme-JSON-Transformation)
    -   [附件处理器](https://npmcn.com/package/%40elastic.io/component-commons-library/#readme-Attachment-Processor)
    -   [外部 API](https://npmcn.com/package/%40elastic.io/component-commons-library/#readme-external-api)
    -   [锁定器](https://npmcn.com/package/%40elastic.io/component-commons-library/#readme-Logger)
-   [许可证](https://npmcn.com/package/%40elastic.io/component-commons-library/#readme-license)

# 说明

这个库以简单,可再用的方式提供一些最常用的组件开发功能.

要安装, 类型

```
npm install @elastic.io/component-commons-library
```

# 可用函数

## API 客户端

一些平台API客户端类可供使用并扩展,为平台API创建客户端.

### 平台ApiRest客户端

[平台ApiRest客户端](https://github.com/elasticio/component-commons-library/blob/master/src/authentication/PlatformApiRestClient.ts) 类扩展 [BasicAuthRest 客户端](https://npmcn.com/package/%40elastic.io/component-commons-library/#readme-BasicAuthRestClient) 课. 此类中检查状态代码 200 的方法如果没有,则丢出一个错误. 并检查该响应是否带有JSON格式的正确数据和其他预期响应头.

#### 构造器(emiters, cfg)

-   排放物 -- -- EIO排放环境.
-   cfg - EIO 组件对象的配置.

```
const Client = new PlatformApiRestClient(emitter, cfg);
```

### 平台ApiLogic 客户端

[平台ApiLogic 客户端](https://github.com/elasticio/component-commons-library/blob/master/src/authentication/PlatformApiLogicClient.ts) 类扩展 [平台ApiRest客户端](https://npmcn.com/package/%40elastic.io/component-commons-library/#readme-PlatformApiRestClient) 课. 包含用于操纵流量状态的有用方法, 以设置为活动运行或停止活动, 搜索流量, 工作空间, 证书等等 .

#### 构造器(emiters, cfg)

-   排放物 -- -- EIO排放环境.
-   cfg - EIO 组件对象的配置.

```
const Client = new PlatformApiLogicClient(emitter, cfg);
```

#### 方法清单

-   获取 AllFlows ForWorkspace( 选项) - 获取给定工作空间的所有流程
-   获取所有证书用于工作空间( 选项) - 获取给定工作空间的所有证书
-   获取 AllSecrets ForWorkspace - 为给定的工作空间获取全部机密
-   获取SecretById - 通过 ID 获取特定工作空间的秘密
-   刷新 TokenBySecretId - 通过给定的工作空间的秘密代号刷新令牌
-   从合同( 选项) 获取组件可访问性 - 从给定的工作空间获取所有可访问组件
-   分解Parallelization( maxParallelization, 分解Factor) - 帮助计算并行呼叫的正确次数的方法
-   获取 FlowList( 选项) - 获取流量列表
-   获取 WorkspaceList( 选项) - 为用户获取所有合同中的所有工作空间列表
-   获取 WorkspaceId( Workspace UniqueCriteria) - 鉴于一组独特的标准,请找到匹配的工作空间
-   删除 NonWritable Properties( flow, 包括DataSamples) - 根据流量, 移除系统经常更改的流量属性, 如上次执行的时间
-   获取FlowId( flowId (flow UniqueCriteria) ) - 以它独特的标准获取流量
-   获取 FlowById( id) - 按其代码获取流量
-   获取 FlowByName And WorkspaceId( flowName, workspaceId) - 按流程名称和工作空间 ID 获取流量
-   更改 Flow state( 选项) - 给定流量, 将流量改为给定状态( 运行、 停止等)
-   启动 Flow( flowId, 选项) - 设置流到活动运行状态
-   stop Flow( flowId, 选项) - 将流量设置为不活动已停止状态
-   水合物花(options) - 使用去除不可写入的Properties方法将流量水化,但会用所有数据样本,证书名称,命令和组件 Id 字段来进一步丰富流量.

## JSON Schema 转换器

包含 JSON 元数据生成工具

-   `convertJsonSchemaToEioSchema(keyToReturn, completeSchemaOriginal)` - 将通用的JSON schema转换为平台友好的JSON元数据
-   `makeSchemaInline(json, availableSchemas)` - 替换 _(单位:美元)_ 递归, 提供完整的对象描述 _乔森_ 对象使用 _可用计划_ 计划图.

## JSON 转换

包含转换包含 JSONata 表达式的平台数据的函数

-   `jsonataTransform(msg, cfg)` - 返回 `msg.body` 将 JSONata 表达式评价为数值

## 附件处理器

附件处理器功能可用于将附件存储在平台上. 它暴露了以下功能

-   `uploadAttachment(getAttachment, retryOptions, contentType)`,它将把附件上传到平台 `Maester` 存储并返回结果对象. 地点:  
    `getAttachment` - 返回流的同步函数  
    `retryOptions` - (可选):如果请求失败,用于重试上传附件的参数。 参数为: `retriesCount` 财务报告和审定财务报表 `requestTimeout`(单位:百万美元) `contentType` - (可选): `Content-Type` 被附着。 默认 `Content-Type` 将自动计算.  
    
-   `getAttachment(url, contentType)`,将检索附件 `steward` 或者说 `maester` 存储。 指定存储 - 查询参数 `storage_type` 必须提供。 要从 `maester` 存储 - `?storage_type=maester` 应添加到 `url` 参数。 默认附件从 `steward` 存储,所以 `?storage_type=steward` 没有义务添加到 `url` 参数. `contentType` - 说吧 \[`stream`, (中文(简体) ), `arraybuffer` \[ . \]

示例

```javascript
const { AttachmentProcessor } = require('@elastic.io/component-commons-library');

const getAttachAsStream = async () => (
  await axios.get('http://sample.pdf', { responseType: 'stream' })
).data;
const result = await new AttachmentProcessor().uploadAttachment(getAttachAsStream, 'application/pdf');

const { objectId } = result.data;
```

```javascript
const { AttachmentProcessor } = require('@elastic.io/component-commons-library');

const result = await new AttachmentProcessor().getAttachment('http://example.com', 'stream'); // steward storage
const result = await new AttachmentProcessor().getAttachment('http://example.com?storage_type=steward', 'arraybuffer'); // steward storage
const result = await new AttachmentProcessor().getAttachment('http://example.com?storage_type=maester', 'stream'); // maester storage
```

## 外部 API

### 环境变量

-   **API RETRIES COUNT (英语)** (默认为 3): 5xx 错误的最大重试量 。 如果服务器仍然响应 5xx, 错误会被丢出 .
-   **请求执行** (默认为 15000, min: 500, 最大为 120000) : 在请求时间到期前指定毫秒数 。 如果请求需要超过超时,请求将被中止.

-   `axiosReqWithRetryOnServerError` (与 `.call()` 来通过上下文,执行它作为一种分类方法 `logger` 财务报告和审定财务报表 `cfg` (当前动作的配置对象值) - 构造器中的值 -- -- 函数通过指定的请求-配置来进行轴请求,使记录和错误处理:
    1.  如果发生 5xx 错误, 将进行最大重试 `API_RETRIES_COUNT` 每次重试都会被延迟 `exponentialSleep` 函数.
    2.  如果发生 4xx 错误 - 错误会被丢弃 .
    3.  如果动作 `cfg` 已经 `doNotThrow404` 设置为真: 404 个错误不会被当作错误处理.  
        从下面的例子来看.
-   `getErrMsg` - 从轴响应中形成错误消息.
-   `getRetryOptions` - 返回嵌入的有效值 `API_RETRIES_COUNT` 财务报告和审定财务报表 `API_REQUEST_TIMEOUT`。如果数值高于或低于极限,则会被默认值所覆盖.
-   `sleep` - 返回承诺,在N时间之后解决.
-   `exponentialDelay` - 根据当前重试返回毫秒数。 见 [指数后退](https://en.wikipedia.org/wiki/Exponential_backoff) 为了解释.
-   `exponentialSleep` - 返回承诺,在N时间之后解决。 以毫秒数表示的 N `exponentialDelay` 执行.

示例 `axiosReqWithRetryOnServerError` 函数 :

```javascript
class Client {
  private logger: any;

  private cfg: any;

  constructor(emitter, cfg) {
    this.logger = emitter.logger;
    this.cfg = cfg;
  }

   public async apiRequest(options: AxiosRequestConfig): Promise<any> {
    try {
      const response = await axiosReq.axiosReqWithRetryOnServerError(this, requestOptions);
      return response.data;
    } catch (error) {
      if (error.response?.status === 401) {
       // update token
      }
      throw error;
    }
  }

  public async getUserById(id) {
    return this.apiRequest({
      url: `/users/${id}`,
      method: 'GET',
    });
  }
}
```

## 锁定器

在logger所建的以Bunyan Logger作为其基础执行. 可找到可用的日志方法 [这里](https://github.com/elasticio/component-commons-library/blob/master/src/logger/logger.ts#L19)。 。 。 .

示例

```javascript
const { Logger } = require('@elastic.io/component-commons-library');

const logger = Logger.getLogger();
logger.info('Hello, world');
```

这个 `getLogger()` 方法使用可选参数 `loggerName` 这样你就可以宣布多种不同的伐木者.

# 许可证

阿帕奇-2.0 © [弹性.io GmbH](http://www.elastic.io/)

## 常见问题

### @elastic\.io/component-commons-library 是什么？

用于最常用组件开发案例的图书馆

### 如何安装 @elastic\.io/component-commons-library？

在项目目录运行 npm install @elastic\.io/component-commons-library，或使用 pnpm add / yarn add / bun add。

### @elastic\.io/component-commons-library 支持 TypeScript 吗？

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

### @elastic\.io/component-commons-library 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @elastic\.io/component-commons-library 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=24。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @elastic\.io/component-commons-library 可以商用吗？

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

### @elastic\.io/component-commons-library 的下载量有多少？

根据 npm 官方下载统计，@elastic\.io/component-commons-library 在 2026/10/13 – 2026/11/11 这 30 天内被下载 9,700 次，日均约 323 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @elastic\.io/component-commons-library 还在维护吗？

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