@celljs/cqrs 4.6.1 → 4.8.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.zh-cn.md +194 -0
- package/package.json +2 -2
package/README.zh-cn.md
ADDED
|
@@ -0,0 +1,194 @@
|
|
|
1
|
+
# Cell - CQRS 组件
|
|
2
|
+
|
|
3
|
+
`@celljs/cqrs` 将改变状态的代码(命令)与读取状态的代码(查询)分离,并让应用的其他部分对发生的事情做出反应(事件),方式参考 [`@nestjs/cqrs`](https://docs.nestjs.com/recipes/cqrs)。处理器是 Cell 组件:通过装饰器查找,获得与其他组件相同的注入,在第一条消息分派时创建。除了 `@celljs/core` 外无其他依赖;仅限后端。
|
|
4
|
+
|
|
5
|
+
```bash
|
|
6
|
+
npm install @celljs/cqrs
|
|
7
|
+
```
|
|
8
|
+
|
|
9
|
+
## 命令与查询
|
|
10
|
+
|
|
11
|
+
命令或查询是类的实例;其类决定了唯一的处理器。扩展 `CommandMessage<R>` / `QueryMessage<R>` 来给 `execute` 指定结果类型(可选:没有它的话,`execute<R>()` 接受类型)。
|
|
12
|
+
|
|
13
|
+
```ts
|
|
14
|
+
import { Autowired } from '@celljs/core';
|
|
15
|
+
import { Body, Controller, Get, Param, Post } from '@celljs/mvc/lib/node';
|
|
16
|
+
import { CommandBus, CommandHandler, CommandMessage, QueryBus, QueryHandler, QueryMessage } from '@celljs/cqrs';
|
|
17
|
+
|
|
18
|
+
export class CreateUser extends CommandMessage<string> {
|
|
19
|
+
constructor(readonly name: string) {
|
|
20
|
+
super();
|
|
21
|
+
}
|
|
22
|
+
}
|
|
23
|
+
|
|
24
|
+
export class GetUser extends QueryMessage<User | undefined> {
|
|
25
|
+
constructor(readonly id: string) {
|
|
26
|
+
super();
|
|
27
|
+
}
|
|
28
|
+
}
|
|
29
|
+
|
|
30
|
+
@CommandHandler(CreateUser)
|
|
31
|
+
export class CreateUserHandler implements CommandHandler<CreateUser> {
|
|
32
|
+
@Autowired(UserRepository)
|
|
33
|
+
protected readonly users: UserRepository;
|
|
34
|
+
|
|
35
|
+
execute(command: CreateUser): Promise<string> {
|
|
36
|
+
return this.users.insert(command.name);
|
|
37
|
+
}
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
@QueryHandler(GetUser)
|
|
41
|
+
export class GetUserHandler implements QueryHandler<GetUser> {
|
|
42
|
+
@Autowired(UserRepository)
|
|
43
|
+
protected readonly users: UserRepository;
|
|
44
|
+
|
|
45
|
+
execute(query: GetUser): Promise<User | undefined> {
|
|
46
|
+
return this.users.findById(query.id);
|
|
47
|
+
}
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
@Controller('users')
|
|
51
|
+
export class UserController {
|
|
52
|
+
@Autowired(CommandBus)
|
|
53
|
+
protected readonly commandBus: CommandBus;
|
|
54
|
+
|
|
55
|
+
@Autowired(QueryBus)
|
|
56
|
+
protected readonly queryBus: QueryBus;
|
|
57
|
+
|
|
58
|
+
@Post()
|
|
59
|
+
create(@Body() body: { name: string }): Promise<string> {
|
|
60
|
+
return this.commandBus.execute(new CreateUser(body.name));
|
|
61
|
+
}
|
|
62
|
+
|
|
63
|
+
@Get(':id')
|
|
64
|
+
get(@Param('id') id: string): Promise<User | undefined> {
|
|
65
|
+
return this.queryBus.execute(new GetUser(id));
|
|
66
|
+
}
|
|
67
|
+
}
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
`execute` 解析为处理器返回的值,拒绝为其抛出的错误。装饰器接受 `@Component` 的选项作为第二参数(`scope`、`proxy` 用于 AOP 等)。
|
|
71
|
+
|
|
72
|
+
## 事件与传奇
|
|
73
|
+
|
|
74
|
+
一个事件类可以有任意数量的 `@EventHandler` 和 `@Saga`。传奇将事件转化为随之而来的命令:事件总线使用命令总线按顺序运行它返回的内容(一个命令、命令数组或无)。
|
|
75
|
+
|
|
76
|
+
```ts
|
|
77
|
+
import { EventBus, EventHandler, Saga } from '@celljs/cqrs';
|
|
78
|
+
|
|
79
|
+
export class UserCreated {
|
|
80
|
+
constructor(readonly id: string, readonly name: string) { }
|
|
81
|
+
}
|
|
82
|
+
|
|
83
|
+
@EventHandler(UserCreated) // 或 @EventHandler([UserCreated, UserRenamed])
|
|
84
|
+
export class UserProjection implements EventHandler<UserCreated> {
|
|
85
|
+
async handle(event: UserCreated): Promise<void> { ... }
|
|
86
|
+
}
|
|
87
|
+
|
|
88
|
+
@Saga(UserCreated)
|
|
89
|
+
export class WelcomeSaga implements Saga<UserCreated> {
|
|
90
|
+
handle(event: UserCreated): SendWelcomeMail {
|
|
91
|
+
return new SendWelcomeMail(event.id);
|
|
92
|
+
}
|
|
93
|
+
}
|
|
94
|
+
|
|
95
|
+
await eventBus.publish(new UserCreated(id, name));
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
`publish(event)` 并发运行事件的处理器和传奇,在全部完成时解析,因此无服务器函数不会在它们之前返回;`publishAll(events)` 一个接一个地发布事件。处理器或传奇抛出的错误不会拒绝 `publish` 也不会阻止其他处理器:它会被记录并交给 `UnhandledExceptionBus`:
|
|
99
|
+
|
|
100
|
+
```ts
|
|
101
|
+
@Component(ApplicationLifecycle)
|
|
102
|
+
export class CqrsAlerts implements ApplicationLifecycle<Application> {
|
|
103
|
+
@Autowired(UnhandledExceptionBus)
|
|
104
|
+
protected readonly exceptions: UnhandledExceptionBus;
|
|
105
|
+
|
|
106
|
+
initialize(): void {
|
|
107
|
+
this.exceptions.onException(({ error, event, handler }) => { ... });
|
|
108
|
+
}
|
|
109
|
+
}
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
## 聚合根
|
|
113
|
+
|
|
114
|
+
`AggregateRoot` 将其更改记录为事件:`apply(event)` 记录事件并调用聚合根的 `on<EventClassName>` 方法(如果存在),以更改状态;`commit()` 用事件总线发布记录的事件。先用 `EventPublisher` 将聚合根连接到事件总线。
|
|
115
|
+
|
|
116
|
+
```ts
|
|
117
|
+
import { AggregateRoot, EventPublisher } from '@celljs/cqrs';
|
|
118
|
+
|
|
119
|
+
export class User extends AggregateRoot {
|
|
120
|
+
name: string;
|
|
121
|
+
|
|
122
|
+
constructor(readonly id: string) {
|
|
123
|
+
super();
|
|
124
|
+
}
|
|
125
|
+
|
|
126
|
+
rename(name: string): void {
|
|
127
|
+
this.apply(new UserRenamed(this.id, name));
|
|
128
|
+
}
|
|
129
|
+
|
|
130
|
+
onUserRenamed(event: UserRenamed): void {
|
|
131
|
+
this.name = event.name;
|
|
132
|
+
}
|
|
133
|
+
}
|
|
134
|
+
|
|
135
|
+
@CommandHandler(RenameUser)
|
|
136
|
+
export class RenameUserHandler implements CommandHandler<RenameUser> {
|
|
137
|
+
@Autowired(EventPublisher)
|
|
138
|
+
protected readonly publisher: EventPublisher;
|
|
139
|
+
|
|
140
|
+
@Autowired(UserRepository)
|
|
141
|
+
protected readonly users: UserRepository;
|
|
142
|
+
|
|
143
|
+
async execute(command: RenameUser): Promise<void> {
|
|
144
|
+
const user = this.publisher.mergeObjectContext(await this.users.load(command.id));
|
|
145
|
+
user.rename(command.name);
|
|
146
|
+
await this.users.save(user);
|
|
147
|
+
await user.commit();
|
|
148
|
+
}
|
|
149
|
+
}
|
|
150
|
+
```
|
|
151
|
+
|
|
152
|
+
- `loadFromHistory(events)` 从存储的事件重建状态,不再次记录它们。
|
|
153
|
+
- `getUncommittedEvents()` 返回记录的事件;`uncommit()` 忘记它们。
|
|
154
|
+
- `eventPublisher.mergeClassContext(User)` 返回创建时连接实例的子类。
|
|
155
|
+
- 记录的事件不是聚合根的属性:`JSON.stringify(user)` 仅给出其状态。
|
|
156
|
+
|
|
157
|
+
## 错误
|
|
158
|
+
|
|
159
|
+
总线和 `commit()` 拒绝时返回 `CqrsError`,其 `code` 稳定,其 `hint` 说明如何修复:
|
|
160
|
+
|
|
161
|
+
| Code | When |
|
|
162
|
+
| --- | --- |
|
|
163
|
+
| `CELL_CQRS_NO_HANDLER` | 命令或查询的类没有 `@CommandHandler` / `@QueryHandler` |
|
|
164
|
+
| `CELL_CQRS_DUPLICATE_HANDLER` | 一个命令或查询类有两个处理器 |
|
|
165
|
+
| `CELL_CQRS_NOT_AN_INSTANCE` | 消息是普通对象、`null` 或原始值,而不是类的实例 |
|
|
166
|
+
| `CELL_CQRS_AGGREGATE_NOT_MERGED` | 对 `EventPublisher` 未连接的聚合根调用 `commit()`;事件保持记录状态 |
|
|
167
|
+
|
|
168
|
+
## 自定义
|
|
169
|
+
|
|
170
|
+
`CommandBus`、`QueryBus`、`EventBus`、`EventPublisher` 和 `UnhandledExceptionBus` 是组件:用 `rebind: true` 替换其中之一,例如要同时将事件发送给消息代理:
|
|
171
|
+
|
|
172
|
+
```ts
|
|
173
|
+
@Component({ id: EventBus, rebind: true })
|
|
174
|
+
export class BrokerEventBus extends EventBusImpl {
|
|
175
|
+
override async publish(event: object): Promise<void> {
|
|
176
|
+
await super.publish(event);
|
|
177
|
+
await this.broker.send(event);
|
|
178
|
+
}
|
|
179
|
+
}
|
|
180
|
+
```
|
|
181
|
+
|
|
182
|
+
## 从 @nestjs/cqrs 迁移
|
|
183
|
+
|
|
184
|
+
| @nestjs/cqrs | @celljs/cqrs |
|
|
185
|
+
| --- | --- |
|
|
186
|
+
| `CqrsModule.forRoot()` | 添加依赖;模块随后端加载 |
|
|
187
|
+
| `ICommandHandler`、`IQueryHandler`、`IEventHandler` | `CommandHandler`、`QueryHandler`、`EventHandler`:装饰器和接口用一个名字 |
|
|
188
|
+
| `@EventsHandler(A, B)` | `@EventHandler([A, B])` |
|
|
189
|
+
| `Command<R>`、`Query<R>` | `CommandMessage<R>`、`QueryMessage<R>`(`@celljs/mvc` 有 `@Query` 装饰器) |
|
|
190
|
+
| `@Saga()` 带 RxJS 流 | `@Saga(Event)` 类,其 `handle(event)` 返回命令;无 RxJS |
|
|
191
|
+
| `eventBus.publish()` 立即返回 | `await eventBus.publish()` 等待处理器和传奇 |
|
|
192
|
+
| `aggregate.commit()` | `await aggregate.commit()`;未连接时拒绝,而不是什么都不做 |
|
|
193
|
+
| `autoCommit` | 不支持:调用 `commit()` |
|
|
194
|
+
| `UnhandledExceptionBus`(RxJS subject) | `UnhandledExceptionBus.onException`(Cell `Event`) |
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@celljs/cqrs",
|
|
3
|
-
"version": "4.
|
|
3
|
+
"version": "4.8.0",
|
|
4
4
|
"description": "Commands, queries, events, sagas and event-sourced aggregates for Cell applications (CQRS)",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"cell-component"
|
|
@@ -31,7 +31,7 @@
|
|
|
31
31
|
"watch": "tsc -b -w --preserveWatchOutput"
|
|
32
32
|
},
|
|
33
33
|
"dependencies": {
|
|
34
|
-
"@celljs/core": "4.
|
|
34
|
+
"@celljs/core": "4.8.0"
|
|
35
35
|
},
|
|
36
36
|
"publishConfig": {
|
|
37
37
|
"access": "public"
|