# bpmn-client 中文文档

规范地址：https://npmcn.com/package/bpmn-client/

版本：3\.5\.1
npm 元数据更新时间：2026-11-03T02:54:21.219Z
中文译文更新时间：2026-11-03T06:55:42.112Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/bpmn-client
原文对照：https://npmcn.com/package/bpmn-client/?lang=original
项目主页：https://github.com/bpmnServer/bpmn-server#readme
源码仓库：https://github.com/bpmnServer/bpmn-server

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

- 包体积（解压后）：92.3 kB，29 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=20\.0\.0
- 运行依赖：3 个
- 首次发布：2020-07-25T04:48:20.043Z
- 最新版本发布：2026-11-03T02:54:21.004Z
- 已发布版本数：28（近 12 个月 5 个）

## 中文简介

BPMN-Server web服务的客户端API

## 安装

```sh
npm install bpmn-client
```

也可以使用：`pnpm add bpmn-client`、`yarn add bpmn-client`、`bun add bpmn-client`

## README

# bpmn-client

[![Project Status: Active - The project has reached a stable, usable state and is being actively developed.](http://www.repostatus.org/badges/latest/active.svg)](http://www.repostatus.org/#active)

这是一个允许远程访问的轻量级包 [bpmn-server](https://github.com/bpmnServer/bpmn-server)

# 安装

在调用bpmn-server的应用程序中（一个新文件夹，或一个现有的Node.js项目）：

```sh
npm init -y && npm pkg set type=module      # a new project; skip in an existing one
npm install bpmn-client
npx bpmn-client-setup                       # writes .env: API_KEY, HOST, PORT
```

集 `.env` 对服务器： `API_KEY` 服务器的(从它的？ `.env`； `ADMIN_API_KEY` 同样，对于模型 管理), `HOST` 和 `PORT` 它跑的地方。然后:

```sh
npx bpmn-client-cli                         # a console on the server: start processes, list and invoke items
```

一个完整的示例应用程序： [bpmn-client-sample](https://github.com/bpmnServer/bpmn-client-sample).

### 更新到最新版本

```
$ npm update bpmn-client
```

# 使用

```js
import { BPMNClient2 } from 'bpmn-client';

// apiKey: the server's API_KEY; adminApiKey (optional): its ADMIN_API_KEY, for model administration
const client = new BPMNClient2('localhost', 3000, process.env.API_KEY, { adminApiKey: process.env.ADMIN_API_KEY });

const instance = await client.engine.start('Buy Used Car', { caseId: 1001 });
const items = await client.data.findItems({ id: instance.id, 'items.status': 'wait' });
await client.engine.invoke({ id: instance.id, 'items.elementId': 'task_Buy' }, { needsRepairs: 'Yes' });

const models = await client.model.list();          // /admin/api2, with the admin key
```

`BPMNClient` 是遗产的客户吗 `/api` (其 `definitions` 和 `datastore.deleteInstances` 去 `/admin/api` 使用管理键)。

### 错误

当每个调用失败时，都会拒绝它，并伴随着服务器的消息：

-   HTTP错误： `"<status> <message>"`,如。 `401 missing or invalid "x-api-key"` （`error.status` 保持状态)；
-   服务器在其应答(`{ errors }` 或者 `{ error }`),如。 `No process definition named X`；
-   一个网页而不是API（错误的主机，端口或路径）；
-   无法连接到服务器时的连接错误(例如： `ECONNREFUSED`）。

### 权限

API密钥代表服务器上的一个服务帐户(`API_SERVICE_USER_NAME`/`_GROUPS`): 信息，信号和原始 `data.find` 需要它 `SYSTEM` 集团;删除实例和模型 政府需要 `ADMIN`.

# 测试

```sh
npm test                 # build, unit tests, contract tests
npm run test:unit        # what each method sends and how answers and failures come back (no server)
npm run test:contract    # every method against a real bpmn-web (BPMN_WEB_DIR, default ../bpmn-web, built;
                         # uses bpmn-web's test harness and a MongoDB of its own; skipped without it)
npm run test:live        # the older scenarios against a running server (localhost:3000, key 12345)
```

## 常见问题

### bpmn-client 是什么？

BPMN-Server web服务的客户端API

### 如何安装 bpmn-client？

在项目目录运行 npm install bpmn-client，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 bpmn-client-cli、bpmn-client-setup，可以用 npx bpmn-client-cli 直接运行。

### bpmn-client 支持 TypeScript 吗？

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

### bpmn-client 支持 ESM 还是 CommonJS？

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

### bpmn-client 需要什么版本的 Node\.js？

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

### bpmn-client 可以商用吗？

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

### bpmn-client 还在维护吗？

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