lakutata 3.0.0 → 3.1.0

package/doc/zh/Decorator.md

@@ -1,6 +1,6 @@
 # Lakutata 装饰器
 
-框架用装饰器声明依赖、选项、动作和校验（TypeScript 的 `experimentalDecorators` 与 `emitDecoratorMetadata`，两者都已在 `lakutata/tsconfig.json` 中开启）。装饰器由以下子路径导出：
+依赖、选项、动作和校验都用装饰器声明（TypeScript 的 `experimentalDecorators` 和 `emitDecoratorMetadata`，两者都已在 `lakutata/tsconfig.json` 中开启）。装饰器由以下子路径导出：
 
 | 子路径 | 装饰器 |
 |---|---|
@@ -10,6 +10,7 @@
 | `lakutata/decorator/asst` | `@Before`、`@After` |
 | `lakutata/decorator/orm` | TypeORM 的装饰器（`@Entity`、`@Column` 等） |
 | `lakutata/com/mutex` | `@Synchronized` |
+| `lakutata/com/queue` | `@QueueAction` |
 
 ## 1. 依赖注入（`lakutata/decorator/di`）
 
@@ -51,11 +52,11 @@ class Signup extends Component {
 }
 ```
 
-无法解析的注册项会使对象创建失败，并抛出 `DependencyInjectionException`。
+依赖无法解析时，对象创建失败，抛出 `DependencyInjectionException`。
 
 ### 1.2 `@Configurable`
 
-`@Configurable(schema?, fn?)` 把属性声明为对象的选项，选项值来自对象的声明（`{class: Server, port: 8080}`）或 `getObject()` 的第二个参数。值先由校验规则（默认 `DTO.Any()`）校验（及转换），如果提供了 `fn`，再交给 `fn` 处理（调用时 `this` 为该实例）。
+`@Configurable(schema?, fn?)` 把属性声明为对象的选项，选项值来自对象的声明（`{class: Server, port: 8080}`）或 `getObject()` 的第二个参数。值先经过校验规则（默认 `DTO.Any()`）校验和转换；如果提供了 `fn`，再交给 `fn` 处理，调用时 `this` 是这个实例。
 
 ```typescript
 import {Application, Component, DTO} from 'lakutata'
@@ -90,12 +91,12 @@ Application.run(() => ({
 ```
 
 - **取值**：优先使用配置里给的值，其次是属性的初始值（`protected readonly host: string = '127.0.0.1'`），最后是校验规则的默认值（`DTO.Number().default(80)`）。初始值会和配置值一样经过校验和转换；子类可以用自己的初始值给出自己的默认值。
-- **`maxListeners`**：所有组件都有这个可配置属性（默认 11），表示同一个事件的监听器超过多少个时给出可能内存泄漏的警告（0 表示不警告；监听器数量从不受限制）。组件可以用 `protected readonly maxListeners: number = 0` 设置自己的默认值，也可以在声明里设置：`{class: MyComponent, maxListeners: 0}`。
-- **启动检查**：模块（或应用）初始化时，会在创建任何对象之前检查它声明的所有对象（组件、提供者和对象）的选项，所以即使某个对象从未被使用，配置错误也会在启动时暴露：
+- **`maxListeners`**：所有组件都有这个可配置属性（默认 11），同一个事件的监听器超过这个数量时，会发出警告，提示可能有内存泄漏（0 表示不警告；监听器的数量本身从不受限制）。组件可以用 `protected readonly maxListeners: number = 0` 设置自己的默认值，也可以在声明里设置：`{class: MyComponent, maxListeners: 0}`。
+- **启动检查**：应用启动时，会在创建任何对象之前检查它声明的所有对象（组件、提供者和对象）的选项，所以即使某个对象从未被使用，配置错误也会在启动时暴露：
   - 不符合 `@Configurable` 属性校验规则的值会导致启动失败，抛出 `InvalidObjectOptionsException`，并列出所有不合法的选项；
-  - 不是该类 `@Configurable` 属性的选项会被忽略并给出警告，警告中列出该类的可配置属性（用于发现拼错的选项名）。
+  - 不是该类 `@Configurable` 属性的选项（例如拼错的选项名）会被忽略，并发出警告，警告中列出该类的可配置属性。
 
-  通过 `getConfigurableRecords()` 读取非可配置属性选项的类，可以覆盖静态方法 `acceptsOption(name, value)` 来接受这些选项，不产生警告。由外部（异步）规则校验的值在对象创建时校验。在应用或模块的选项中设置 `checkOptions: false` 可以关闭这项检查。
+  不通过可配置属性、而是通过 `getConfigurableRecords()` 读取选项的类，可以覆盖静态方法 `acceptsOption(name, value)` 来接受这些选项，这样就不会产生警告。由外部（异步）规则校验的值在对象创建时校验。在应用的选项中设置 `checkOptions: false` 可以关闭这项检查。
 
 ### 1.3 `@Autoload`
 
@@ -105,17 +106,17 @@ Application.run(() => ({
 
 | 装饰器 | 实例数量 | 默认用于 |
 |---|---|---|
-| `@Singleton(lock?)` | 每个注册该类的容器一个 | `Component`、`Module`（锁定） |
+| `@Singleton(lock?)` | 每个注册该类的容器一个 | `Component`（锁定） |
 | `@Scoped(lock?)` | 每个作用域一个（入口的一次请求） | `Provider`、`Controller`（锁定） |
 | `@Transient(lock?)` | 每次解析一个 | `BaseObject` |
 
-`@Lifetime('SINGLETON' | 'SCOPED' | 'TRANSIENT', lock?)` 是它们的完整写法。`lock` 为 `true` 时，子类不能声明其他生命周期类型（子类定义时抛出 `LifetimeLockedException`）；`Provider` 可以是单例（与 2.x 相同）。
+`@Lifetime('SINGLETON' | 'SCOPED' | 'TRANSIENT', lock?)` 是它们的完整写法。`lock` 为 `true` 时，子类不能声明其他生命周期（定义这样的子类会抛出 `LifetimeLockedException`）。`Provider` 可以是单例，与 2.x 相同。
 
 ```typescript
 import {Provider} from 'lakutata'
 import {Transient} from 'lakutata/decorator/di'
 
-//每个使用者都得到自己的构建器，各自保存状态
+//每个注入它的对象都得到自己的构建器实例，各自保存状态
 @Transient()
 export class QueryBuilder extends Provider {
     protected readonly clauses: string[] = []
@@ -130,8 +131,8 @@ export class QueryBuilder extends Provider {
 ### 1.5 子类的属性
 
 - **继承**：子类继承父类的 `@Inject` 和 `@Configurable` 属性。子类重新声明某个属性时，会取代父类对它的声明，不论使用的是哪种装饰器，以最近一层的声明为准（父类注入的属性，在子类里用 `@Configurable` 重新声明后，只按配置处理，不再注入；反之亦然）。
-- **属性的类型**：TypeScript 允许子类在重新声明属性时把类型改窄（例如把 `Store` 改成 `MemoryStore`），但不允许换成其他类型：把 `number` 换成 `string` 会报 `TS2416`（`Property 'port' in type 'BrokenServer' is not assignable to the same property in base type 'PlainServer'`），而且没有任何编译选项可以关闭这个检查。如果父类允许子类替换某个属性的类型，就用泛型参数来声明这个属性：
-  - 父类在类上声明泛型参数，按属性命名并以 `Type` 结尾（属性 `store` 对应 `StoreType`）。加上约束（`extends Store`）：父类可以按约束的类型使用这个属性，子类也只能换成兼容的类型。再加上默认类型（`= Store`）：不需要替换类型的子类，继承时不用填写类型参数；
+- **属性的类型**：TypeScript 允许子类在重新声明属性时把类型改窄（例如把 `Store` 改成 `MemoryStore`），但不允许换成其他类型：把 `number` 换成 `string` 会报 `TS2416`（`Property 'port' in type 'BrokenServer' is not assignable to the same property in base type 'PlainServer'`），而且没有任何编译选项可以关闭这个检查。如果子类可能需要给某个属性换一种类型，父类就用泛型参数来声明这个属性：
+  - 父类在类上声明泛型参数，按属性命名并以 `Type` 结尾（属性 `store` 对应 `StoreType`）。加上约束（`extends Store`）：父类可以按约束的类型使用这个属性，子类也只能换成兼容的类型；再加上默认类型（`= Store`）：不需要替换类型的子类，继承时不用填写类型参数；
   - 子类在 `extends` 处填入具体类型。只有需要更换装饰器时，才在子类里重新声明这个属性。
 
 ```typescript
@@ -180,9 +181,11 @@ export class NamedPortServer extends Server<string> {
 
 在 `MemoryRepository` 里，IDE 会把 `this.store` 当作 `MemoryStore` 来补全；在 `Repository` 里则当作 `Store`。如果父类没有声明泛型参数，子类只能在属性上用 `// @ts-expect-error` 压制这个错误，而父类的方法仍会按原来的类型使用这个属性。
 
+像 `NamedPortServer` 这样不带初始值地重新声明属性，在 `useDefineForClassFields: false` 下可以编译，`lakutata/tsconfig.json` 已经这样设置。设为 `true`（TypeScript 对 `ES2022` 及更新的编译目标的默认值）时，编译器会报 `TS2612`；这时在属性前加上 `declare`（`@Configurable(...) declare protected readonly port: string`），装饰器照样生效。
+
 ## 2. 控制器动作（`lakutata/decorator/ctrl`）
 
-这些装饰器用于 `Controller` 子类的方法（`@Prefix` 和 `@UseMiddlewares` 也可用于类）；详见 [ActionPattern](ActionPattern.md)。
+这些装饰器用于 `Controller` 子类的方法（`@Prefix` 和 `@UseMiddlewares` 也可用于类）；详见 [Controllers](Controllers.md)。
 
 | 装饰器 | 地址 |
 |---|---|
@@ -224,7 +227,7 @@ CLI 命令名称前面的词是命令分组：`@CLIAction('package exe <name>',
 | 装饰器 | 效果 |
 |---|---|
 | `@Expect(schema)` | DTO 属性的校验规则（`DTO.String().required()`） |
-| `@IndexSignature(schema)` | DTO 类保留没有规则的字段，并按该规则校验 |
+| `@IndexSignature(schema)` | DTO 类保留没有规则的字段，并按这条规则校验它们 |
 | `@Accept(...schemas)` | 每次调用方法时按位置校验参数 |
 | `@Return(schema)` | 每次调用方法时校验返回值 |
 
@@ -232,7 +235,7 @@ CLI 命令名称前面的词是命令分组：`@CLIAction('package exe <name>',
 
 ## 4. 辅助装饰器（`lakutata/decorator/asst`）
 
-`@Before(fn)` 在方法每次调用之前以其参数执行一个函数：函数返回的数组会替换传给方法的参数。`@After(fn)` 在每次调用之后以其结果执行一个函数：函数返回的非 `undefined` 值会替换结果。这些函数调用时 `this` 为该实例；只有方法是异步的，函数才可以是异步的。
+`@Before(fn)` 在方法每次调用之前执行一个函数，传入方法的参数：函数返回的数组会替换传给方法的参数。`@After(fn)` 在每次调用之后执行一个函数，传入方法的结果：函数返回的非 `undefined` 值会替换结果。这些函数调用时 `this` 为该实例；只有方法是异步的，函数才可以是异步的。
 
 ```typescript
 import {Component} from 'lakutata'
@@ -261,9 +264,13 @@ class Prices extends Component {
 
 ## 5. 锁（`lakutata/com/mutex`）
 
-`@Synchronized` 让控制器动作在持有 `Mutex` 组件的锁时执行，锁在输入校验和访问控制通过之后获取。见 [Mutex](Mutex.md)。
+`@Synchronized` 让控制器动作在 `Mutex` 组件的锁的保护下执行，锁在输入校验和访问控制通过之后获取。见 [Mutex](Mutex.md)。
+
+## 6. 消息队列（`lakutata/com/queue`）
+
+`@QueueAction(queue, dto?, options?)` 让控制器动作成为一个队列的消费者：`queueEntrypoint` 适配器把队列的消息投递给它。动作正常返回时确认消息，失败后重试，重试次数用完后把消息送进死信队列。见 [Queue](Queue.md)。
 
-## 6. 数据库实体（`lakutata/decorator/orm`）
+## 7. 数据库实体（`lakutata/decorator/orm`）
 
 `lakutata/decorator/orm` 重新导出 TypeORM 的装饰器：
 
@@ -295,4 +302,4 @@ export class User {
 }
 ```
 
-见 [ORMIntegration](ORMIntegration.md)。
+见 [Entities](Entities.md)。

package/doc/zh/DockerIntegration.md

@@ -2,7 +2,7 @@
 
 **Docker 组件**（`lakutata/com/docker`，`@lakutata/docker` 包）通过 Docker Engine API 操作 Docker 守护进程，不需要 Docker CLI：拉取、构建（使用 BuildKit）、导入、导出、打标签和推送镜像，创建、运行和管理容器（exec、交互式 TTY、日志、统计、commit、导出文件），以及管理网络。它可以连接本地套接字，也可以通过 HTTP、HTTPS 或 SSH 连接远程守护进程。全部选项见 `@lakutata/docker` 的 README 和 `lakutata/com/docker` 的类型声明。
 
-该组件不是预置组件：需要在应用的 `components` 中声明。只运行 containerd、没有 Docker 的机器（嵌入式 Linux 设备）请参阅 [ContainerdIntegration](ContainerdIntegration.md)。
+这个组件没有预置：需要在应用的 `components` 中声明。只运行 containerd、没有 Docker 的机器（嵌入式 Linux 设备）见 [ContainerdIntegration](ContainerdIntegration.md)。
 
 ## 1. 环境要求与连接
 
@@ -16,7 +16,7 @@
 | TCP，HTTPS | `host`、`port`，以及 PEM 内容形式的 `ca`、`cert`、`key`（`buildDockerHttpsConnectionOptions`） |
 | SSH | `host`、`port`、`username`、`sshAuthAgent`（`buildDockerSSHConnectionOptions`） |
 
-组件创建时会 ping 守护进程并协商 API 版本：守护进程不可达时启动失败，抛出 `DockerConnectionException`。`timeout`（毫秒）是请求允许空闲的时间。
+组件创建时会 ping 守护进程，并协商 API 版本：守护进程连不上时，组件创建失败，抛出 `DockerConnectionException`；组件列在 `bootstrap` 里时，应用因此启动失败。`timeout`（毫秒）是请求最多可以空闲多久。
 
 ```typescript
 import {readFileSync} from 'node:fs'
@@ -175,11 +175,11 @@ async function containers(docker: Docker): Promise<void> {
 ```
 
 - `DockerContainer` 是一个快照：它自己的操作会刷新它；其他地方做的修改需要重新获取才能看到（`docker.getContainer(id)`，也接受名称或短 ID）。
-- 启动正在运行的容器或停止已停止的容器不做任何事，与 Docker CLI 一致。
-- `exec()` 在没有 TTY 和 stdin 的情况下运行。数组形式的命令原样执行；字符串是命令行，由 `/bin/sh -c` 执行。
+- 启动正在运行的容器，或者停止已停止的容器，都不会做任何事，与 Docker CLI 相同。
+- `exec()` 运行时没有 TTY，也没有 stdin。数组形式的命令原样执行；字符串是命令行，由 `/bin/sh -c` 执行。
 - `kill()` 默认发送 `SIGKILL`，也可以指定信号。
 - `commit()` 用容器生成镜像，`exportDirectory()` 把容器中的目录写成 tar 归档。
-- 不提供的功能：附加到主进程、向容器中复制文件、卷（`prune()` 除外）以及守护进程的事件。
+- 不提供的功能：附加到主进程、向容器中复制文件、管理卷（`prune()` 的清理除外），以及守护进程的事件。
 
 ## 5. 网络
 
@@ -202,4 +202,4 @@ async function networks(docker: Docker): Promise<void> {
 
 ## 6. 错误
 
-组件的异常由 `lakutata/com/docker` 导出：`DockerConnectionException`（组件创建时守护进程不可达）、`DockerContainerNotFoundException`、`DockerImageNotFoundException`、`DockerNetworkNotFoundException`、`DockerImagePullException`、`DockerImageBuildException`、`DockerImageImportException`、`DockerImagePushException`、`DockerImageRepoTagNotFoundException`，以及 `DockerRequestException`（守护进程拒绝请求；其 `statusCode` 为 HTTP 状态码，名称已被占用时为 409）。选项不合法时抛出 `InvalidMethodAcceptException`。组件被销毁时，正在进行的拉取和构建会被中止。
+组件的异常由 `lakutata/com/docker` 导出：`DockerConnectionException`（组件创建时连不上守护进程）、`DockerContainerNotFoundException`、`DockerImageNotFoundException`、`DockerNetworkNotFoundException`、`DockerImagePullException`、`DockerImageBuildException`、`DockerImageImportException`、`DockerImagePushException`、`DockerImageRepoTagNotFoundException`，以及 `DockerRequestException`（守护进程拒绝请求；其 `statusCode` 为 HTTP 状态码，名称已被占用时为 409）。选项不合法时抛出 `InvalidMethodAcceptException`。组件被销毁时，正在进行的拉取和构建会被中止。

package/doc/zh/Entities.md

@@ -0,0 +1,224 @@
+# Lakutata 实体、查询与事务
+
+实体、仓储、查询和事务都来自 [TypeORM](https://typeorm.io) 1：装饰器来自 `lakutata/decorator/orm`，其余 API 来自 `lakutata/orm`。本指南介绍常见的用法，每个选项的说明见 TypeORM 的文档。
+
+## 1. 实体
+
+实体是映射到一张表的类：
+
+```typescript
+import {
+    BeforeInsert, Column, CreateDateColumn, DeleteDateColumn, Entity, Index, JoinColumn, ManyToOne, OneToMany,
+    PrimaryGeneratedColumn, UpdateDateColumn, VersionColumn
+} from 'lakutata/decorator/orm'
+
+@Entity('orders')
+export class Order {
+    @PrimaryGeneratedColumn('uuid')
+    public id: string
+
+    @Index()
+    @Column()
+    public customer: string
+
+    //随订单一起保存（级联）
+    @OneToMany(() => OrderLine, (line: OrderLine) => line.order, {cascade: true})
+    public lines: OrderLine[]
+
+    @CreateDateColumn({type: 'timestamptz'})
+    public createdAt: Date
+
+    @UpdateDateColumn({type: 'timestamptz'})
+    public updatedAt: Date
+
+    //由 softDelete() 设置：除非设置了 withDeleted，查询会跳过这个订单
+    @DeleteDateColumn({type: 'timestamptz'})
+    public deletedAt: Date | null
+
+    //每次保存加一
+    @VersionColumn()
+    public version: number
+
+    @BeforeInsert()
+    protected normalize(): void {
+        this.customer = this.customer.trim()
+    }
+}
+
+@Entity('order_lines')
+export class OrderLine {
+    @PrimaryGeneratedColumn()
+    public id: number
+
+    @Column()
+    public product: string
+
+    @Column('integer')
+    public quantity: number
+
+    @ManyToOne(() => Order, (order: Order) => order.lines, {onDelete: 'CASCADE'})
+    @JoinColumn({name: 'order_id'})
+    public order: Order
+}
+```
+
+| 装饰器 | 用途 |
+|---|---|
+| `@Entity(name)`、`@ViewEntity`、`@ChildEntity`、`@TableInheritance` | 实体、视图、表的继承 |
+| `@PrimaryGeneratedColumn(strategy)`、`@PrimaryColumn` | 主键：自动生成（`'increment'`、`'uuid'`、`'identity'`），或者手动给出 |
+| `@Column(type, options)` | 列：类型、`length`、`nullable`、`default`、`unique`、`transformer`…… |
+| `@CreateDateColumn`、`@UpdateDateColumn`、`@DeleteDateColumn`、`@VersionColumn` | 由 TypeORM 自动设置的列 |
+| `@OneToOne`、`@OneToMany`、`@ManyToOne`、`@ManyToMany`、`@JoinColumn`、`@JoinTable` | 关系 |
+| `@Index`、`@Unique`、`@Check` | 索引和约束 |
+| `@BeforeInsert`、`@AfterLoad`、`@BeforeUpdate`…… | 在操作前后执行的方法 |
+| `@ObjectIdColumn` | MongoDB 实体的 `_id` |
+
+实体要列在每个使用它的数据库的 `entities` 选项中。实体也可以继承 `lakutata/orm` 中的 `BaseEntity`，从而自己保存和查询（`await Order.findOneBy({id})`、`await order.save()`）：这些操作使用最后一个连接了该实体的数据库。
+
+## 2. 查询
+
+仓储（`db.getRepository(Order)`）用来读写一张表中的实体：
+
+```typescript
+import {Component} from 'lakutata'
+import {Inject} from 'lakutata/decorator/di'
+import {Database} from 'lakutata/com/database'
+import {Column, CreateDateColumn, Entity, PrimaryGeneratedColumn} from 'lakutata/decorator/orm'
+import {Between, ILike, type Repository} from 'lakutata/orm'
+
+@Entity('orders')
+class Order {
+    @PrimaryGeneratedColumn('uuid')
+    public id: string
+
+    @Column()
+    public customer: string
+
+    @CreateDateColumn({type: 'timestamptz'})
+    public createdAt: Date
+}
+
+class Orders extends Component {
+    @Inject('db')
+    protected readonly db: Database
+
+    protected get orders(): Repository<Order> {
+        return this.db.getRepository(Order)
+    }
+
+    //某段时间内订单的一页，以及订单总数
+    public async search(customer: string, from: Date, to: Date, page: number): Promise<[Order[], number]> {
+        return await this.orders.findAndCount({
+            where: {customer: ILike(`%${customer}%`), createdAt: Between(from, to)},
+            order: {createdAt: 'DESC'},
+            skip: (page - 1) * 20,
+            take: 20
+        })
+    }
+
+    //查询构造器
+    public async byCustomer(customer: string): Promise<Order[]> {
+        return await this.db.createQueryBuilder(Order, 'order')
+            .where('order.customer LIKE :customer', {customer: `%${customer}%`})
+            .orderBy('order.createdAt', 'DESC')
+            .getMany()
+    }
+
+    //SQL：占位符在 PostgreSQL 上是 $1、$2……，在 MySQL 和 SQLite 上是 ?
+    public async count(customer: string): Promise<number> {
+        const rows: { count: string }[] = await this.db.query('SELECT COUNT(*) AS count FROM orders WHERE customer = $1', [customer])
+        return Number(rows[0].count)
+    }
+}
+```
+
+- **查询：** `find`、`findBy`、`findOne`、`findOneBy`、`findAndCount`、`count`、`exists`；`findOneByOrFail` 什么都没找到时会抛出 `EntityNotFoundError`。
+- **查询选项**使用对象：`where`、`relations: {lines: true}`、`select: {id: true, customer: true}`、`order: {createdAt: 'DESC'}`、`skip` 和 `take`、`withDeleted`。`where` 中给出条件列表表示 `OR`。
+- **查询操作符**来自 `lakutata/orm`：`In`、`Not`、`IsNull`、`Like`、`ILike`、`Between`、`MoreThan`、`MoreThanOrEqual`、`LessThan`、`LessThanOrEqual`、`Any`、`ArrayContains`、`Raw`……
+- **写入：** `save`（插入或更新，并按关系的级联设置一起保存）、`insert`、`update`、`delete`、`softDelete` 和 `restore`（需要 `@DeleteDateColumn`）、`increment`、`upsert`。
+- **查询构造器**（`createQueryBuilder`）用来写查询选项表达不了的查询：带条件的连接、分组、子查询。它的值（`:customer`）作为参数传递，从不拼接进 SQL 文本。
+- **SQL**（`query(sql, parameters)`）原样返回驱动给出的行：PostgreSQL 的 `COUNT(*)` 是字符串。
+
+## 3. 事务
+
+`transaction(fn)` 在事务中执行一个函数：函数成功时提交，失败时回滚，并重新抛出它的错误。事务中的每个操作都要通过传给函数的实体管理器执行；通过 `db.manager` 或 `db.getRepository()` 执行的操作不在事务中。
+
+```typescript
+import {Component} from 'lakutata'
+import {Inject} from 'lakutata/decorator/di'
+import {Database} from 'lakutata/com/database'
+import {Column, Entity, PrimaryGeneratedColumn} from 'lakutata/decorator/orm'
+import {type EntityManager} from 'lakutata/orm'
+
+@Entity('accounts')
+class Account {
+    @PrimaryGeneratedColumn()
+    public id: number
+
+    @Column('integer')
+    public balance: number
+}
+
+class Transfers extends Component {
+    @Inject('db')
+    protected readonly db: Database
+
+    //两个更新要么都完成，要么都不完成
+    public async transfer(from: number, to: number, amount: number): Promise<void> {
+        await this.db.transaction('SERIALIZABLE', async (manager: EntityManager): Promise<void> => {
+            await manager.decrement(Account, {id: from}, 'balance', amount)
+            await manager.increment(Account, {id: to}, 'balance', amount)
+        })
+    }
+}
+```
+
+- 隔离级别可以省略：`'READ UNCOMMITTED'`、`'READ COMMITTED'`、`'REPEATABLE READ'`、`'SERIALIZABLE'`。
+- `createQueryRunner()` 提供一个独占的连接，用来手动控制事务（`startTransaction()`、`commitTransaction()`、`rollbackTransaction()`，最后 `release()`）。
+- MongoDB 和嵌入式 MongoDB 没有事务：在它们上面，`transaction()` 会在没有事务的情况下执行函数。
+
+## 4. 需要注意的值
+
+- **大数。** PostgreSQL 和 MySQL 以字符串返回 `bigint` 和 `decimal` 列，以保持精度。SQLite 以数字返回它们，超过 2^53 时会丢失精度。如果数字就够用，可以用列的 `transformer` 转换：
+
+  ```typescript
+  import {Column, Entity, PrimaryGeneratedColumn} from 'lakutata/decorator/orm'
+  import type {ValueTransformer} from 'lakutata/orm'
+
+  const decimal: ValueTransformer = {
+      to: (value: number): number => value,
+      from: (value: string | null): number | null => value === null ? null : Number(value)
+  }
+
+  @Entity('invoices')
+  export class Invoice {
+      @PrimaryGeneratedColumn()
+      public id: number
+
+      @Column({type: 'decimal', precision: 10, scale: 2, transformer: decimal})
+      public total: number
+  }
+  ```
+
+- **条件中的 `null` 和 `undefined`** 默认会被忽略：`findOneBy({id: undefined})` 会查到第一行。见 [Database](Database.md) 第 2 节。
+- **日期。** 优先使用带时区的列（PostgreSQL 的 `timestamptz`）。在 MySQL 上，连接的 `timezone` 选项决定日期如何写入和读取。
+
+## 5. 错误
+
+错误都来自 TypeORM，由 `lakutata/orm` 导出：
+
+| 错误 | 什么时候 |
+|---|---|
+| `QueryFailedError` | 数据库拒绝了查询。它的 `driverError` 是驱动的错误：在 PostgreSQL 上，代码 `23505` 表示重复键，`constraint` 是约束的名字 |
+| `EntityNotFoundError` | `findOneByOrFail()` 和 `findOneOrFail()` 什么都没找到 |
+| `EntityMetadataNotFoundError` | 实体不在数据库的 `entities` 中 |
+| `OptimisticLockVersionMismatchError` | 加锁时 `@VersionColumn` 与期望的版本不一致 |
+| `CannotExecuteNotConnectedError` | 在没有连接或已经断开的数据库上查询 |
+
+```typescript
+import {QueryFailedError} from 'lakutata/orm'
+
+export function isDuplicate(error: unknown): boolean {
+    return error instanceof QueryFailedError && (error.driverError as { code?: string }).code === '23505'
+}
+```

package/doc/zh/Entrypoint.md

@@ -0,0 +1,193 @@
+# Lakutata Entrypoint
+
+`entrypoint` 组件把控制器和各种传输方式连接起来。它持有控制器和各传输方式的适配器（HTTP、命令行、服务调用、定时任务、消息队列……）：每个适配器接收自己传输方式的请求，入口则执行对应的动作，连同它的中间件、校验和访问控制。
+
+## 1. 声明入口
+
+`lakutata` 包已经声明了一个名为 `entrypoint` 的组件。应用用 `buildEntrypoints` 在同一个名字下给它提供选项，并把它列入 `bootstrap`：
+
+```typescript
+import {Application} from 'lakutata'
+import {buildEntrypoints, Controller} from 'lakutata/com/entrypoint'
+import {GET} from 'lakutata/decorator/ctrl'
+import {expressHTTPEntrypoint} from 'lakutata/adapter/express'
+
+class HealthController extends Controller {
+    @GET('/health')
+    public async health(): Promise<string> {
+        return 'ok'
+    }
+}
+
+Application.run(() => ({
+    id: 'api.app',
+    name: 'API',
+    components: {
+        entrypoint: buildEntrypoints({
+            controllers: [HealthController],
+            http: expressHTTPEntrypoint({port: 8080})
+        })
+    },
+    bootstrap: ['entrypoint']
+}))
+```
+
+组件在第一次被需要时才会创建。没有其他对象需要入口，所以如果没有 `bootstrap: ['entrypoint']`，它永远不会被创建：服务不会监听，命令不会执行，定时任务也不会开始。
+
+## 2. 选项
+
+| 选项 | 默认值 | 含义 |
+|---|---|---|
+| `controllers` | `[]` | 控制器类 |
+| `http`、`cli`、`service`、`schedule`、`queue`、`mcp`、`dbus` | | 各传输方式的适配器（见下表）：一个适配器，或者适配器数组 |
+| `middlewares` | `[]` | 所有动作的中间件（见 [Middlewares](Middlewares.md)） |
+| `rules` | `[]` | 声明了 `acl: true` 的动作使用的访问规则（见 [Middlewares](Middlewares.md)） |
+| `shutdownTimeout` | `30000` | 应用停止时，留给正在处理的请求的毫秒数（第 4 节） |
+| `httpActionGroups`、`cliActionGroups`、`serviceActionGroups` | `{}` | 动作可以使用的分组及其名称（第 5 节） |
+
+适配器：
+
+| 选项 | 适配器 | 导入自 | 需要安装 | 指南 |
+|---|---|---|---|---|
+| `http` | `expressHTTPEntrypoint()` | `lakutata/adapter/express` | `express` | [HTTP](HTTP.md) |
+| `http` | `fastifyHTTPEntrypoint()` | `lakutata/adapter/fastify` | `fastify` | [HTTP](HTTP.md) |
+| `cli` | `commanderCLIEntrypoint()` | `lakutata/adapter/commander` | `commander` | [CLI](CLI.md) |
+| `service` | `httpServiceEntrypoint()` | `lakutata/com/entrypoint` | | [ServiceCalls](ServiceCalls.md) |
+| `service` | `socketIOServiceEntrypoint()` | `lakutata/adapter/socket.io` | `socket.io` | [ServiceCalls](ServiceCalls.md) |
+| `service` | `jsonRPCServiceEntrypoint()` | `lakutata/adapter/jsonrpc` | `ws`（WebSocket 时） | [ServiceCalls](ServiceCalls.md) |
+| `service` | `electronIPCServiceEntrypoint()` | `lakutata/adapter/electron` | （Electron） | [ServiceCalls](ServiceCalls.md) |
+| `service` | `grpcServiceEntrypoint()` | `@lakutata/grpc/service` | `@lakutata/grpc` | [GRPC](GRPC.md) |
+| `service` | `natsServiceEntrypoint()` | `@lakutata/nats` | `@lakutata/nats` | [NATS](NATS.md) |
+| `schedule` | `scheduleEntrypoint()` | `lakutata/com/entrypoint` | | [Schedules](Schedules.md) |
+| `queue` | `queueEntrypoint()` | `lakutata/com/queue` | 队列服务器的客户端 | [Queue](Queue.md) |
+| `mcp` | `httpMCPEntrypoint()`、`stdioMCPEntrypoint()` | `@lakutata/mcp` | `@lakutata/mcp` | [MCP](MCP.md) |
+| `dbus` | `dbusEntrypoint()` | `@lakutata/dbus` | `@lakutata/dbus` | [DBus](DBus.md) |
+
+## 3. 多个适配器
+
+每个选项都可以是数组，用多种方式提供同一种传输。比如服务动作同时通过 Socket.IO 提供给浏览器、通过 JSON-RPC 提供给脚本，或者 HTTP 动作同时监听两个端口：
+
+```typescript
+import {buildEntrypoints} from 'lakutata/com/entrypoint'
+import {expressHTTPEntrypoint} from 'lakutata/adapter/express'
+import {jsonRPCServiceEntrypoint} from 'lakutata/adapter/jsonrpc'
+import {socketIOServiceEntrypoint} from 'lakutata/adapter/socket.io'
+
+export const entrypoint = buildEntrypoints({
+    controllers: [],
+    http: [
+        expressHTTPEntrypoint({name: 'public', port: 8080}),
+        expressHTTPEntrypoint({name: 'internal', host: '127.0.0.1', port: 9090})
+    ],
+    service: [
+        socketIOServiceEntrypoint({port: 3000}),
+        jsonRPCServiceEntrypoint({port: 4000, path: '/rpc'})
+    ]
+})
+```
+
+一种传输方式的每个适配器都提供该传输方式的全部动作。`name` 选项用来区分这些适配器。
+
+## 4. 启动与停止
+
+**应用启动时**，入口先检查控制器。下面任何一种错误都会让启动失败，并抛出对应的异常：
+
+- 同一传输方式中有两个同名的动作（`DuplicateActionNameException`）；
+- 动作使用的分组没有在对应的 `*ActionGroups` 选项中声明（`InvalidActionGroupException`）；
+- 前缀与某个动作的模式冲突（`InvalidPrefixException`）；
+- 中间件既不是函数，也不是 `Middleware` 类（`InvalidMiddlewareException`）；
+- 适配器放在了另一种传输方式的键下，或者某个选项既不是入口的选项，也不是传输方式（`InvalidEntrypointAdapterException`）。
+
+然后按选项的顺序依次启动各个适配器。某个适配器启动失败（比如端口已被占用）时，应用启动失败。命令行和定时任务在整个应用启动完成之后才开始。
+
+**应用停止时**（收到 `SIGTERM` 或 `SIGINT`，或者调用了 `app.exit()`），适配器按相反的顺序停止：
+
+1. 不再接受新请求。视传输方式而定，仍然到达的请求会以 `EntrypointStoppedException` 被拒绝（HTTP 上是状态码 503）；
+2. 正在处理的请求有 `shutdownTimeout`（默认 30 秒）可以完成；
+3. 仍在执行的请求被中止：它们的 `this.signal` 被触发，并以 `EntrypointStoppedException` 回复；
+4. 适配器关闭各自的服务器和连接。
+
+## 5. 分组与动作列表
+
+动作的 `groups` 选项把它放进分组。访问规则可以使用分组（见 [Middlewares](Middlewares.md)），入口也可以按分组列出动作，用来生成 API 目录或权限列表。HTTP、命令行和服务动作的分组必须连同名称一起声明：
+
+```typescript
+import {Application} from 'lakutata'
+import {buildEntrypoints, Controller, type Entrypoint} from 'lakutata/com/entrypoint'
+import {DELETE, GET} from 'lakutata/decorator/ctrl'
+import {Inject} from 'lakutata/decorator/di'
+
+class UserController extends Controller {
+    @Inject('entrypoint')
+    protected readonly entrypoint: Entrypoint
+
+    @GET('/users', {description: 'List the users'})
+    public async list(): Promise<string[]> {
+        return []
+    }
+
+    @DELETE('/users/:id', {description: 'Delete a user', groups: ['admin']})
+    public async remove(): Promise<void> {
+    }
+
+    //每个分组的动作：[{"group":"Administration","actions":["Delete a user"]}]
+    @GET('/permissions')
+    public async permissions(): Promise<{ group: string, actions: string[] }[]> {
+        return this.entrypoint.getHttpActions().groups.map((group) => ({
+            group: group.name,
+            actions: group.actions.map((action): string => action.description)
+        }))
+    }
+}
+
+Application.run(() => ({
+    id: 'users.app',
+    name: 'Users',
+    components: {
+        entrypoint: buildEntrypoints({
+            controllers: [UserController],
+            httpActionGroups: {admin: 'Administration'}
+        })
+    },
+    bootstrap: ['entrypoint']
+}))
+```
+
+`getHttpActions()`、`getCliActions()` 和 `getServiceActions()` 返回 `{groups, actions}`：`groups` 是已声明的分组（`id`、`name` 及其 `actions`），`actions` 是该传输方式的全部动作。其他传输方式的动作用 `getActions(channel)` 列出（比如 `getActions('schedule')`）。每个动作由以下属性描述：
+
+| 属性 | 含义 |
+|---|---|
+| `id` | 由控制器、方法和地址计算出的固定 id |
+| `name`、`description`、`groups`、`acl` | 它的选项 |
+| `controller`、`method` | 控制器类名和方法名 |
+| `route` / `command` / `pattern` | 它的地址，包含前缀 |
+| `jsonSchema` | 它的 DTO 的 JSON schema |
+
+## 6. 向客户端推送事件
+
+保持客户端连接的服务传输方式（Socket.IO、Electron、HTTP 服务的事件流、WebSocket 或 stdio 上的 JSON-RPC、gRPC）可以接收应用推送的事件。`entrypoint.notify(clientId, event, ...args)` 把事件发给一个客户端，即某个动作从 `this.context.clientId` 读到的那个客户端，返回客户端是否收到；`entrypoint.broadcast(event, ...args)` 发给所有已连接的客户端，返回客户端的数量。见 [GRPC](GRPC.md) 和 [ServiceCalls](ServiceCalls.md)。
+
+## 7. 定制入口
+
+`Entrypoint` 的子类可以替换组件的类：用 `class` 声明它，其他选项照常写在旁边。
+
+```typescript
+import {AccessControl, Entrypoint} from 'lakutata/com/entrypoint'
+
+//记录访问控制的每一次判断
+class AuditedAccessControl extends AccessControl {
+    protected async match(): Promise<boolean> {
+        const allowed: boolean = await super.match()
+        console.log(`${this.target.name}: ${allowed ? 'allowed' : 'denied'}`)
+        return allowed
+    }
+}
+
+export class AuditedEntrypoint extends Entrypoint {
+    protected readonly accessControl: typeof AccessControl = AuditedAccessControl
+}
+
+//components: {entrypoint: {class: AuditedEntrypoint, controllers: [...], http: ...}}, bootstrap: ['entrypoint']
+```
+
+其他传输方式的适配器需要实现 `@lakutata/entrypoint/channel` 中的 `EntrypointAdapter` 接口。lakutata 2.x 的入口函数（`buildHTTPEntrypoint`、`buildCLIEntrypoint`、`buildServiceEntrypoint`）仍然可以用在 `http`、`cli` 和 `service` 选项中。