# @commercelayer/sdk-utils 中文文档

规范地址：https://npmcn.com/package/%40commercelayer/sdk-utils/

版本：5\.0\.0
npm 元数据更新时间：2026-10-07T06:33:16.207Z
中文译文更新时间：2026-11-10T12:02:24.996Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：2.4 MB，215 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：0 个
- peer 依赖：@commercelayer/sdk ^8\.0\.0
- 首次发布：2023-10-11T09:06:16.826Z
- 最新版本发布：2026-10-07T06:33:15.818Z
- 近 30 天下载量：8923（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：54（近 12 个月 12 个）

## 中文简介

商业层 Javascript SDK Utils 图书馆

## 安装

```sh
npm install @commercelayer/sdk-utils
```

也可以使用：`pnpm add @commercelayer/sdk-utils`、`yarn add @commercelayer/sdk-utils`、`bun add @commercelayer/sdk-utils`

## README

# 商业层 SDK Utils

[![Version](https://img.shields.io/npm/v/@commercelayer/sdk-utils.svg)](https://npmjs.org/package/@commercelayer/sdk-utils) [![Downloads/week](https://img.shields.io/npm/dw/@commercelayer/sdk-utils.svg)](https://npmjs.org/package/@commercelayer/sdk-utils) [![License](https://img.shields.io/npm/l/@commercelayer/sdk-utils.svg)](https://github.com/commercelayer/commercelayer-sdk-utils/blob/master/package.json) [![semantic-release: angular](https://img.shields.io/badge/semantic--release-angular-e10079?logo=semantic-release)](https://github.com/semantic-release/semantic-release) [![Release](https://github.com/commercelayer/commercelayer-sdk-utils/actions/workflows/semantic-release.yml/badge.svg)](https://github.com/commercelayer/commercelayer-sdk-utils/actions/workflows/semantic-release.yml) [![CodeQL](https://github.com/commercelayer/commercelayer-sdk-utils/actions/workflows/codeql-analysis.yml/badge.svg)](https://github.com/commercelayer/commercelayer-sdk-utils/actions/workflows/codeql-analysis.yml) [![TypeScript](https://img.shields.io/badge/%3C%2F%3E-TypeScript%205-%230074c1.svg)](https://www.typescriptlang.org/)

一个 JavaScript 库, 使与它互动变得更加容易 [商业层 API](https://docs.commercelayer.io/developers) 使用官员 [Java 脚本 SDK](https://github.com/commercelayer/commercelayer-sdk)。 。 。 .

## 安装和使用

#### SDK v8.x (请求) `^8.0.0`(中文(简体) )

Core API 是版本的, 所以 SDK v8 需要 `apiVersion` 当创建客户端时。 默认条目 `@commercelayer/sdk` 是一个捆绑的客户端, 它携带每个资源: 传递给 `CommerceLayerUtils` 并且所有设施都可以使用.

```ts
import { CommerceLayer } from "@commercelayer/sdk"
import CommerceLayerUtils, { executeBatch } from '@commercelayer/sdk-utils'

const cl = CommerceLayer({ organization, accessToken, apiVersion: '2026-05' })
CommerceLayerUtils(cl)

await executeBatch(batch)
```

利用树摇的优势,使用来自 `@commercelayer/sdk/single-client` 并且只通过你真正需要的资源.

```ts
import { CommerceLayer, orders, customers } from "@commercelayer/sdk/single-client"
import CommerceLayerUtils, { retrieveAll } from '@commercelayer/sdk-utils'

const cl = CommerceLayer({ organization, accessToken, apiVersion: '2026-05' })
CommerceLayerUtils(cl, [ orders, customers ])

const customerList = await retrieveAll<Customer>('customers')
```

资源也可以在后期被添加到CommerceLayerUtils配置.

```ts
import { CommerceLayer, orders, customers, skus } from "@commercelayer/sdk/single-client"
import CommerceLayerUtils from '@commercelayer/sdk-utils'

const cl = CommerceLayer({ organization, accessToken, apiVersion: '2026-05' })
const utilsConfig = CommerceLayerUtils(cl)

utilsConfig.addApiResources(orders, customers)
utilsConfig.addApiResource(skus)
```

> \[注\] 在单一客户端的情况下,一个工具只能使用传递给的资源 `CommerceLayerUtils`: 调用 `retrieveAll('skus')` 不添加 `skus` 掷出 `Resource [skus] not available`。 。 。 .

#### SDK v7.x (英语)

使用 `@commercelayer/sdk-utils` 4.x (要求数) `^7.11.0`) (中文(简体) ).

* * *

## 职能和公用事业一览表

共同职能

-   [执行批次](https://npmcn.com/package/%40commercelayer/sdk-utils/#readme-executebatch) - 执行准备的API请求清单
-   [全部检索](https://npmcn.com/package/%40commercelayer/sdk-utils/#readme-retrieveall) - 获取所有现有资源
-   [全部更新](https://npmcn.com/package/%40commercelayer/sdk-utils/#readme-updateall) - 对一组资源应用更改
-   [删除全部](https://npmcn.com/package/%40commercelayer/sdk-utils/#readme-deleteall) - 删除一组资源
-   [检索页面](https://npmcn.com/package/%40commercelayer/sdk-utils/#readme-retrievepage) - 检索资源自定义页面

清理

-   [分页清除](https://npmcn.com/package/%40commercelayer/sdk-utils/#readme-splitcleanup) - 将大清洗分为多个小清理
-   [执行清除](https://npmcn.com/package/%40commercelayer/sdk-utils/#readme-executecleanup) - 在多个小清理中分出一个大清理,然后执行
-   [清理到批量任务](https://npmcn.com/package/%40commercelayer/sdk-utils/#readme-cleanupstobatchtasks) - 翻译可执行批次任务的清理清单

出口

-   [拆分输出](https://npmcn.com/package/%40commercelayer/sdk-utils/#readme-splitexport) - 将大量出口分成多个小出口
-   [执行导出](https://npmcn.com/package/%40commercelayer/sdk-utils/#readme-executeexport) - 在多个小出口中分出一个大出口,并加以执行
-   [导出到批次任务](https://npmcn.com/package/%40commercelayer/sdk-utils/#readme-exportstobatchtasks) - 翻译可执行批量任务的出口清单

进口

-   [分页导入](https://npmcn.com/package/%40commercelayer/sdk-utils/#readme-splitimport) - 将大量进口品分成多个小进口品
-   [执行导入](https://npmcn.com/package/%40commercelayer/sdk-utils/#readme-executeimport) - 将大量进口品分成多个小进口品并加以执行
-   [导入到批量任务](https://npmcn.com/package/%40commercelayer/sdk-utils/#readme-importstobatchtasks) - 翻译可执行批量任务的进口清单

网络呼号

-   [解除 Payload 的正常状态](https://npmcn.com/package/%40commercelayer/sdk-utils/#readme-denormalizepayload) - 剖析一个网钩有效载荷,并将其转换成适当的SDK物体

SDK 查询助手

-   [包含帮助](https://npmcn.com/package/%40commercelayer/sdk-utils/#readme-includehelper) - 建立一个 `include`用于查询过滤器的对象
-   [过滤帮助](https://npmcn.com/package/%40commercelayer/sdk-utils/#readme-filterhelper) - 建立一个 `filter` 用于查询过滤器的对象

* * *

### 共同职能

##### 执行批次

此功能允许准备然后执行一些 API 调用,而无需担心当前利率限制.

```ts
for (const emailAddress of emailList) {
    const task: Task = {
      resourceType: "customers",
      operation: "create",
      resource: { email: emailAddress } as CustomerCreate,
      onSuccess: { callback: sendEmail },
      onFailure: { errorHandler: handleError }
    }
    tasks.push(task)
  }

  const batch: Batch = {
    tasks,
    options: { refreshToken: refreshAccessToken }
  }


await executeBatch(batch)
```

在上述例子中 `onSuccess` 财务报告和审定财务报表 `onFailure` 如果执行成功或失败,则使用回调处理任务结果.

也可以从上批量步骤的结果中取出值来填充资源属性. 在下面的例子中,我们正在更新一个资源,其编号取自以前的 `retrieve` 或者说 `create` 任务 :

```ts
const task: Task = {
    resourceType: "customers",
    operation: "update",
    prepareResource: (res: TaskResourceParam, last: TaskResourceResult): TaskResourceParam => {
        return {
          ...res,
          id: last.id,
          reference: 'new-reference'
        }
      }
  }
```

##### 全部检索

此功能允许获取特定类型的所有现有资源, 执行所有必要的API请求, 遵守当前 API 费率限制 . 这个 `limit` 选项只能用于获取数量有限的资源.

```ts
const skus = await retrieveAll<Sku>('skus', { limit: 100 })
```

##### 全部更新

此函数允许修改一组特定类型的资源,使用过滤器来识别它们.

```ts
const skuData = { reference_origin: 'legacy-system-0' }

const filters = { created_at_lt: '2023-01-01' }

const updateResult = await updateAll('skus', skuData, { filters })
```

##### 删除全部

此函数允许删除一组特定类型的资源,使用过滤器来识别它们.

```ts

const filters = { created_at_lt: '2023-01-01', reference_origin_eq: 'legacy-system-0' }

const deleteResult = await deleteAll('skus', { filters })
```

##### 检索页面

此功能可以获取一个特定资源子集,定义API不允许的页面属性,并使用所有标准通用过滤器. 如果页面参数与现有资源数量不相容,则会出现错误.

```ts
 const skus = await retrievePage<Sku>('skus', { pageNumber: 16, pageSize: 139, sort: ['code'] })
```

* * *

### 清理

##### 分页清除

在多项清理中分开清理,同时遵守资源的最大限度

```ts
const clp: CleanupCreate = {
 resource_type: 'customers',
 filters: { created_at_gt: '2020-01-01'}
}

const splitClp: CleanupCreate[] = await splitCleanup(clp)
```

##### 执行清除

在多项清理中分拆清理,尊重所包括资源的最大限度,并加以执行

```ts
const clp: CleanupCreate = {
 resource_type: 'customers',
 filters: { created_at_gt: '2020-01-01'}
}

const execClp: CleanupResult[] = await executeCleanup(clp)
```

##### 清理到批量任务

转换所生成的清理列表 `splitCleanup` 到函数可以执行的任务列表 `executeBatch`

```ts
const clps = await splitCleanup(clp)

const tasks = cleanupsToBatchTasks(clps)
```

* * *

### 出口

##### 拆分输出

在多个出口中分割一个出口,同时遵守资源的最大限度

```ts
const exp: ExportCreate = {
 resource_type: 'customers',
 filters: { created_at_gt: '2020-01-01'}
}

const splitExp: ExportCreate[] = await splitExport(exp)
```

##### 执行导出

在多个出口中分割一个出口,同时尊重所包含资源的最大限制,并加以执行

```ts
const exp: ExportCreate = {
 resource_type: 'customers',
 filters: { created_at_gt: '2020-01-01'}
}

const execExp: ExportResult[] = await executeExport(exp)
```

##### 导出到批次任务

转换生成的导出列表 `splitExport` 到函数可以执行的任务列表 `executeBatch`

```ts
const exps = await splitExport(exp)

const tasks = exportsToBatchTasks(exps)
```

* * *

### 进口

##### 分页导入

在多个进口中分割一个进口,同时遵守输入的最大限度

```ts
const exp: ImportCreate = {
 resource_type: 'customers',
 inputs: [
  { ... },
  { ... },
  ...
  { ... }
 ]
}

const splitImp: ImportCreate[] = await splitImport(imp)
```

##### 执行导入

在多个进口中拆分一个导入,同时遵守输入的最大限制,并将其执行

```ts
const exp: ImportCreate = {
 resource_type: 'customers',
 inputs: [
  { ... },
  { ... },
  ...
  { ... }
 ]
}

const execImp: ImportResult[] = await executeImport(imp)
```

##### 导入到批量任务

转换生成的导入列表 `splitImport` 到函数可以执行的任务列表 `executeBatch`

```ts
const imps = await splitImport(imp)

const tasks = importsToBatchTasks(imps)
```

* * *

### 网络呼号

##### 解除 Payload 的正常状态

该函数以JSON格式输入一个webhook的有效载荷,并将其转换成适当的打字资源,与正式的Typescript SDK一起使用.

```ts
const shipment = denormalizePayload<Shipment>(webhookPayload)
```

* * *

### SDK 查询助手

##### 包含帮助

这个帮助器可以用来轻松地构建包含在SDK查询参数中使用的数组资源.

> **说明:** 这个 `versions` 资源已经从商务层 API 中删除,在包含的帮助中不再可用.

###### 标准包括

```ts
const include: QueryInclude = [ 'market', 'customer', 'customer.customer_group' ]
```

###### 包含包含帮助

```ts
import { Include } from '@commercelayer/sdk-utils'

const include: QueryInclude = [ Include.orders.market.build(), Include.orders.customer.build(), Include.orders.customer.customer_group.build() ]

// The same as above but using a single instance of the orders helper
const io = Include.orders
const includeSingle: QueryInclude = [ io.market.build(), io.customer.build(), io.customer.customer_group.build() ]
```

###### 包含使用 _包含_ 函数

```ts
import { buildInclude } from '@commercelayer/sdk-utils'

const include: QueryInclude = buildInclude(Include.orders.market, Include.orders.customer, Include.orders.customer.customer_group)
```

###### 将资源添加到已有的查询过滤器中

```ts
import { Include } from '@commercelayer/sdk-utils'

const queryFilter: QueryParams = {}

const io = Include.orders

io.market.addTo(queryFilter)
io.customer.addTo(queryFilter)
io.customer.customer_group.addTo(queryFilter)
```

##### 过滤帮助

这个帮助可以用来方便地构建包含滤波器上游的物体来用于SDK查询参数.

> **说明:** 这个 `versions` 资源已经从商务层 API 中移除,并且已无法在过滤器帮助中获取.

###### 标准过滤器

```ts
const filter: QueryFilter = {
  number_eq: '123',
  market_reference_eq: 'MKT',
  reference_or_customer_customer_group_reference_eq: 'REF',
  status_in: 'placed,approved,cancelled',
  reference_origin_not_null: 'true'
}
```

###### 带有过滤帮助器的过滤器

```ts
import { Filter } from '@commercelayer/sdk-utils'

const filter: QueryFilter = {
  ...Filter.orders.number.eq('123'),
  ...Filter.orders.market.reference.eq('MKT'),
  ...Filter.orders.reference.or.customer.customer_group.reference.eq('REF'),
  ...Filter.orders.status.in('placed', 'approved', 'cancelled'),
  ...Filter.orders.reference_origin.not_null()
}

// The same as above but using a single instance of the orders helper
const of = Filter.orders

const filterSingle: QueryFilter = {
  ...of.number.eq('123'),
  ...of.market.reference.eq('MKT'),
  ...of.reference.or.customer.customer_group.reference.eq('REF'),
  ...of.status.in('placed', 'approved', 'cancelled'),
  ...of.reference_origin.not_null()
}
```

###### 使用过滤器 _构建过滤器_ 函数

```ts
import { buildFilter } from '@commercelayer/sdk-utils'

const filter: QueryFilter = buildFilter(
  of.number.eq('123'),
  of.market.reference.eq('MKT'),
  of.reference.or.customer.customer_group.reference.eq('REF'),
  of.status.in('placed', 'approved', 'cancelled'),
  of.reference_origin.not_null()
)
```

## 常见问题

### @commercelayer/sdk-utils 是什么？

商业层 Javascript SDK Utils 图书馆

### 如何安装 @commercelayer/sdk-utils？

在项目目录运行 npm install @commercelayer/sdk-utils，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@commercelayer/sdk（^8\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @commercelayer/sdk-utils 支持 TypeScript 吗？

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

### @commercelayer/sdk-utils 支持 ESM 还是 CommonJS？

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

### @commercelayer/sdk-utils 需要什么版本的 Node\.js？

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

### @commercelayer/sdk-utils 可以商用吗？

@commercelayer/sdk-utils 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @commercelayer/sdk-utils 的下载量有多少？

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

### @commercelayer/sdk-utils 还在维护吗？

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