# @adobe/spacecat-shared-utils 中文文档

规范地址：https://npmcn.com/package/%40adobe/spacecat-shared-utils/

版本：1\.128\.0
npm 元数据更新时间：2026-10-02T07:55:30.030Z
中文译文更新时间：2026-11-05T21:55:10.050Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：412 kB，56 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.0\.0 \<25\.0\.0
- 运行依赖：14 个
- 首次发布：2023-11-28T14:46:26.709Z
- 最新版本发布：2026-10-02T07:55:29.658Z
- 近 30 天下载量：14847（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：318（近 12 个月 106 个）

## 中文简介

Spacecat 服务的共享模块- utils

## 安装

```sh
npm install @adobe/spacecat-shared-utils
```

也可以使用：`pnpm add @adobe/spacecat-shared-utils`、`yarn add @adobe/spacecat-shared-utils`、`bun add @adobe/spacecat-shared-utils`

## README

# SpaceCat 共享设备

该寄存器包含在SpaceCat各项目中使用的共享实用功能的集合. 这些公用事业提供一系列的检查和验证,从基本数据类型验证到更复杂的检查,如ISO日期字符串和URL验证.

> **页:1**: 添加了跟踪标识传播支持,用于在SpaceCat服务中分布追踪.

## 安装

要安装 SpaceCat 共享公用事业, 您可以使用 npm :

```bash
npm install spacecat-shared-utils
```

或者,如果你在使用纱线:

```bash
yarn add spacecat-shared-utils
```

## 使用量

以下是您如何在您的工程中使用不同的功能:

```javascript
import { isBoolean, isValidUrl } from 'spacecat-shared-utils';

console.log(isBoolean('true')); // true
console.log(isValidUrl('https://www.example.com')); // true
```

## 职能

图书馆包括下列公用事业功能:

-   `isBoolean(value)`: 确定给定值是布尔表示还是布尔表示的字符串表示.
-   `isInteger(value)`:检查给定值是否是一个整数.
-   `isValidDate(obj)`:检查给定对象是否为有效的JavaScript Date.
-   `isIsoDate(str)`:验证给定的字符串是否是Zulu(UTC)时区中的JavaScript ISO日期字符串.
-   `isIsoTimeOffsetsDate(str)`:验证给定的字符串是否为UTC时间抵消格式后的JavaScript ISO日期字符串.
-   `isNumber(value)`: 确定给定的值是否是一个数字.
-   `isObject(obj)`:检查给定参数是否是对象而不是数组或无效.
-   `isString(str)`:确定给定参数是否为字符串.
-   `toBoolean(value)`: 将给定值转换为布尔值。 如果值不是布尔值, 则丢出错误 .
-   `arrayEquals(a, b)`: 比较两个数组平等.
-   `isValidUrl(urlString)`: 验证给定的字符串是否与 https 协议是有效的 URL .
-   `hasText(str)`:检查给定的字符串是否为空 .
-   `dateAfterDays(number)`: 计算从当前日期起特定天数后的日期.

## 日志折叠器

这个 `logWrapper` 通过自动预览增强您的 Lambda 函数日志 `jobId` (留言)和 `traceId` (从AWS X-Ray)到所有日志语句. 这改善了分布式服务的日志可追踪性.

### 特征

-   自动提取 AWS X-Ray 痕量 ID
-   可用时包括消息中的工作编号
-   增强 `context.log` 直接 - **无需更改代码**
-   与已存在的日志级别( 信息、 错误、 调试、 警告、 跟踪等) 无缝工作

### 使用量

```javascript
import { logWrapper, sqsEventAdapter } from '@adobe/spacecat-shared-utils';

async function run(message, context) {
  const { log } = context;
  
  // Use context.log as usual - trace IDs are added automatically
  log.info('Processing started'); 
  // Output: [jobId=xxx] [traceId=1-xxx-xxx] Processing started
}

export const main = wrap(run)
  .with(sqsEventAdapter)
  .with(logWrapper)  // Add this line early in the wrapper chain
  .with(dataAccess)
  .with(sqs)
  .with(secrets)
  .with(helixStatus);
```

**说明:** 这个 `logWrapper` 增强 `context.log` 直接说 所有已存在的代码使用 `context.log` 将自动在日志中包含痕量ID和工作ID,而不修改代码.

## SQS 事件适应器

库还包含一个SQS事件适配器来将一个SQS记录转换为函数参数. 这在与由 SQS 事件所触发的 AWS Lambda 函数合作时有用. 用法 :

```javascript
import { sqsEventAdapter } from '@adobe/spacecat-shared-utils';

// ...

export const main = wrap(run)
  .with(dataAccess)
  .with(sqsEventAdapter) // Add this line
  .with(sqs)
  .with(secrets)
  .with(helixStatus);
```

## AWS X-射线集成

### 获取 TraceId ()

从段取出当前 AWS X-Ray 的痕量ID 。 回返 `null` 如果不在AWS Lambda中,或者没有线段.

```javascript
import { getTraceId } from '@adobe/spacecat-shared-utils';

const traceId = getTraceId();
// Returns: '1-5e8e8e8e-5e8e8e8e5e8e8e8e5e8e8e8e' or null
```

此函数由 `logWrapper` 以在日志中包含痕量ID.

## 测试

该图书馆包括一个综合测试套件,以确保公用事业功能的可靠性。 要进行测试,请使用下列命令:

```bash
npm test
```

## 子路径导出

为了避免拉入完整依赖树(~110MB),从子路径导入:

| 导入 | 依赖关系 |
| --- | --- |
| `@adobe/spacecat-shared-utils` | 全部(~110MB) |
| `@adobe/spacecat-shared-utils/core` | 无——纯粹的联署材料 |
| `@adobe/spacecat-shared-utils/aws` | `@aws-sdk/*`, (中文(简体) ), `aws-xray-sdk`, (中文(简体) ), `@adobe/fetch` ⚠ **边效果 :** 在导入时初始化 HTTP 连接池 —— 需要外出上网 |
| `@adobe/spacecat-shared-utils/locale` | `cheerio`, (中文(简体) ), `world-countries`, (中文(简体) ), `franc-min`, (中文(简体) ), `iso-639-3`, (中文(简体) ), `@adobe/fetch` ⚠ **边效果 :** 在导入时初始化 HTTP 连接池 —— 需要外出上网 |
| `@adobe/spacecat-shared-utils/calendar` | `date-fns` |
| `@adobe/spacecat-shared-utils/schemas` | `zod` |
| `@adobe/spacecat-shared-utils/constants` | 无——纯数据 |

### 类型脚本

亚路径出口需要 `"moduleResolution": "node16"`, (中文(简体) ), `"nodenext"`,或 `"bundler"` 内 `tsconfig.json`. 遗产 `"moduleResolution": "node"` 无法解决子路径输出.

### 维修

任何新的 `src/` 包含顶级必备代码的文件( 超出 `import`编号 :`export` 发言) `sideEffects` 阵列 `package.json`。 。 。 .

## 许可证

这个项目根据Apache许可证2.0获得许可——见 [自由主义](https://npmcn.com/package/%40adobe/spacecat-shared-utils/LICENSE.txt) 详细文件.

## 常见问题

### @adobe/spacecat-shared-utils 是什么？

Spacecat 服务的共享模块- utils

### 如何安装 @adobe/spacecat-shared-utils？

在项目目录运行 npm install @adobe/spacecat-shared-utils，或使用 pnpm add / yarn add / bun add。

### @adobe/spacecat-shared-utils 支持 TypeScript 吗？

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

### @adobe/spacecat-shared-utils 支持 ESM 还是 CommonJS？

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

### @adobe/spacecat-shared-utils 需要什么版本的 Node\.js？

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

### @adobe/spacecat-shared-utils 可以商用吗？

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

### @adobe/spacecat-shared-utils 的下载量有多少？

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

### @adobe/spacecat-shared-utils 还在维护吗？

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