# @effect-server-utils/cqrs 中文文档

规范地址：https://npmcn.com/package/%40effect-server-utils/cqrs/

版本：0\.1\.0-beta\.10
npm 元数据更新时间：2026-10-30T04:27:18.522Z
中文译文更新时间：2026-11-13T08:17:19.105Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40effect-server-utils/cqrs
原文对照：https://npmcn.com/package/%40effect-server-utils/cqrs/?lang=original
项目主页：https://dataquail.github.io/effect-server-utils
源码仓库：https://github.com/dataquail/effect-server-utils

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

- 包体积（解压后）：418 kB，123 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：effect ^4\.0\.2
- 首次发布：2026-08-16T22:47:06.068Z
- 最新版本发布：2026-10-30T04:27:18.154Z
- 近 30 天下载量：4347（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：11（近 12 个月 11 个）

## 中文简介

已键入 CQRS for Effect: 命令并查询有每条消息成功和出错类型的总线, 由订阅者选择其一致性模式的事件总线, 以及处理管理器

## 安装

```sh
npm install @effect-server-utils/cqrs
```

也可以使用：`pnpm add @effect-server-utils/cqrs`、`yarn add @effect-server-utils/cqrs`、`bun add @effect-server-utils/cqrs`

## README

# @ effect- server- utils/ cqrs

输入的 CQRS 用于 [效果](https://effect.website/): 命令和查询公交车,每条消息都成功 出错类型,是一种由订阅者选择其一致性模型的事件总线,以及处理管理器.

```sh
pnpm add @effect-server-utils/cqrs effect
```

`effect` 是同级依赖.

## 你得到的东西

-   **`Command` 编号 : `Query`** - 发布一次信息,说明其有效载荷计划、成功类型和 失败类型 。 返回错误事物的处理器不编译, 和呼叫器读两个 从定义上而不是从总线上走 二个是分开的外观 将查询组拒绝给一个预期命令组—— CQRS 区分 以类型表示.
-   **`CommandBus` 编号 : `QueryBus`** ——全应用的调度表面. `bus.execute(Command, payload)` 从您通过的定义中读取其签名, 因此没有命令声明的侧表 可以飘来飘去.
-   **`DispatchTable`** ——将每个模块的调度器折叠到一个表格中一个公共汽车路线通过. 这个 一张表格可能错误的三种方式(`DuplicateDispatchTag`, (中文(简体) ), `UnroutableTags`, (中文(简体) ), `MissingHandler`旅费 作为被标记的缺陷,所以启动检查可以匹配条件而不是解析消息字符串.
-   **`EventBus`** - 1辆公共汽车,3个交货合同,选择地点: _订阅_ 而不是在派遣. `subscribe` 运行在出版商的纤维里,并可以将其卷回; `subscribeAfterCommit` 运行一次 出版商的边界已在其自己的边界内完成,永远无法; `stream` 输入相机 绝不等待, 制片人只说出了点事 所以一个事件可以为消费者服务 需要不同的东西.
-   **`DeferralSink`** - 决定什么的可选接缝 `subscribeAfterCommit` 等着 这个 软件包不知道交易是什么:安装 [`@effect-server-utils/unit-of-work`](https://www.npmjs.com/package/@effect-server-utils/unit-of-work) 承诺后意味着承诺后;不安装任何设备,这些操作员在每台设备结束时运行 发送。 汉德勒的书写方式都一样.
-   **`Saga`** 一个过程管理者处理推迟的事件,因为没有单一的事件决定.
-   **`Middleware`** - 行为在每次发送时都适用一次. `Middleware.span` 由 默认; `metrics()` 财务报告和审定财务报表 `deadline()` 选择进入。 中间软件可能不会改变消息的成功或者 出错通道,也就是让公交车有一个接合而不会削弱呼叫者的类型.
-   **`UnhandledFailures`** ——当没有来电者接收时,失败就会发生.

## 宣布和发出命令

```ts
import * as Effect from "effect/Effect";
import * as Schema from "effect/Schema";
import { Command, CommandBus } from "@effect-server-utils/cqrs";

class OrderNotFound extends Schema.TaggedError<OrderNotFound>()("OrderNotFound", {
  orderId: Schema.String,
}) {}

const PlaceOrder = Command.make("PlaceOrder", {
  payload: { orderId: Schema.String },
  success: Schema.String,
  failure: OrderNotFound,
});

// A module groups the tags it owns and implements them in one place. Whatever
// services the handlers need become the Layer's requirements.
const Orders = Command.group(PlaceOrder);

export const OrdersHandlers = Command.handlersOf(Orders, {
  PlaceOrder: (payload) => Effect.succeed(`placed:${payload.orderId}`),
});

// At a call site, the channels come from the definition — not from the bus.
const program = Effect.gen(function* () {
  const bus = yield* CommandBus;
  const receipt = yield* bus.execute(PlaceOrder, { orderId: "ord_1" });
  return receipt;
}).pipe(Effect.catchTag("OrderNotFound", (e) => Effect.succeed(`missing:${e.orderId}`)));
```

在组成根部,每个模块的调度表面被合并到表格中 巴士路线 通过:

```ts
import { makeCommandBus, mergeDispatchTables } from "@effect-server-utils/cqrs";

const table = mergeDispatchTables(ordersDispatcher, billingDispatcher);
const bus = makeCommandBus(table, { declaredIn: [Orders, Billing] });
```

## 活动

```ts
import { Event } from "@effect-server-utils/cqrs";

const OrderPlaced = Event.make("OrderPlaced", { orderId: Schema.String });

const subscriptions = Effect.gen(function* () {
  const bus = yield* EventBus;

  // Part of the same logical operation: its failure rolls the publisher back.
  yield* bus.subscribe(OrderPlaced, (event) => inventory.reserve(event.orderId));

  // A reaction to work that is already durable: isolated, retried on its own.
  yield* bus.subscribeAfterCommit(OrderPlaced, (event) => email.sendReceipt(event.orderId));
});
```

"已经耐用"需要耐用 _内_没有 `DeferralSink` 在上下文中,总线运行 派遣结束时的后承诺处理者——仍然在每一个直接的,仍然孤立的——之后 足以使一个没有数据存储器来协调。 添加 `@effect-server-utils/unit-of-work` 同样的处理者在真正的承诺后开始运行, 每个人在 本身的交易,上面没有重写:

```ts
import { makeUnitOfWork, withUnitOfWork } from "@effect-server-utils/unit-of-work";

// Installs the sink alongside the boundary — they are one decision.
const runtime = Layer.mergeAll(makeEventBus(), makeUnitOfWork()).pipe(
  Layer.provide(YourTransactionDriver),
);

// The boundary a use case declares once, at the end of its pipe.
const placeOrder = (input: Input) => doTheWork(input).pipe(withUnitOfWork);
```

## 测试助手

串行性检查在它们自己的入口后进行,因为它们得到一个样本值 消费者生产过程中无业务的产权测试运行时间:

```ts
import { checkEventsSerializable, checkSerializable } from "@effect-server-utils/cqrs/testing";

const check = Effect.gen(function* () {
  const problems = yield* checkSerializable(Orders); // empty means every contract is portable
});
```

## 文档

完整文档: [https://dataquail.github.io/effect-server-utils 页面存档备份,存于互联网档案馆](https://dataquail.github.io/effect-server-utils)

## 许可证

麻省理工学院

## 常见问题

### @effect-server-utils/cqrs 是什么？

已键入 CQRS for Effect: 命令并查询有每条消息成功和出错类型的总线, 由订阅者选择其一致性模式的事件总线, 以及处理管理器

### 如何安装 @effect-server-utils/cqrs？

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

### @effect-server-utils/cqrs 支持 TypeScript 吗？

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

### @effect-server-utils/cqrs 支持 ESM 还是 CommonJS？

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

### @effect-server-utils/cqrs 可以商用吗？

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

### @effect-server-utils/cqrs 的下载量有多少？

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

### @effect-server-utils/cqrs 还在维护吗？

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