lakutata 3.0.0 → 3.1.1

package/doc/zh/ActionPattern.md

@@ -1,334 +0,0 @@
-# Lakutata 控制器与动作
-
-`Entrypoint` 组件（`lakutata/com/entrypoint`，`@lakutata/entrypoint` 包）通过多种传输方式对外提供控制器的方法，即**动作**。动作的地址可以是 HTTP 路由、CLI 命令、服务模式或定时计划，同一个方法可以同时拥有多个地址：无论通过哪种传输方式调用，它的输入都以相同的方式经过 DTO 校验、访问控制和中间件。更多细节见 `@lakutata/entrypoint` 的 README，以及 `lakutata/com/entrypoint` 和 `lakutata/decorator/ctrl` 的类型声明。
-
-## 1. 控制器
-
-控制器继承 `Controller`（`lakutata/com/entrypoint`），它是一个生命周期为 `@Scoped`（锁定）的提供者：每次请求都会在该请求的作用域中创建自己的控制器，请求结束时销毁；控制器注入的提供者也属于该请求的作用域。
-
-- `this.context` 是请求的上下文：`HTTPContext`（含 `request`、`response`、`route`、`method`）、`CLIContext`（含 `command`）、`ServiceContext`（含 `clientId`）或 `ScheduleContext`；可通过类或 `type` 区分。
-- `this.signal` 是一个 `AbortSignal`，在请求被中止时触发：客户端断开、超过截止时间或入口正在停止。耗时较长的动作应随之停止，因为它的结果会被丢弃。
-- 方法接收的输入（请求的数据，经动作的 DTO 校验，填充默认值并移除未知字段）是一个普通对象，而不是 DTO 实例。没有 DTO 时，输入原样传入。
-- 返回值就是响应；抛出的异常以其 `statusCode`（HTTP）以及 `errno` 和消息作为响应，输入不合法时返回状态码 400。
-
-```typescript
-import {Application, DTO} from 'lakutata'
-import {buildEntrypoints, Controller, scheduleEntrypoint} from 'lakutata/com/entrypoint'
-import {CLIAction, GET, POST, Schedule, ServiceAction} from 'lakutata/decorator/ctrl'
-import {Expect} from 'lakutata/decorator/dto'
-import {expressHTTPEntrypoint} from 'lakutata/adapter/express'
-import {commanderCLIEntrypoint} from 'lakutata/adapter/commander'
-import {socketIOServiceEntrypoint} from 'lakutata/adapter/socket.io'
-
-class GetOrderDTO extends DTO {
-    //路由参数和查询参数都是字符串：strict(false) 会转换它们
-    @Expect(DTO.Number().integer().strict(false).required())
-    public id: number
-}
-
-class CreateOrderDTO extends DTO {
-    @Expect(DTO.String().required())
-    public product: string
-
-    @Expect(DTO.Number().integer().min(1).default(1))
-    public quantity: number
-}
-
-class OrderController extends Controller {
-    //GET /orders/42、命令 "order --id 42"、服务消息 {cmd: 'order.get', id: 42}
-    @GET('/orders/:id', GetOrderDTO)
-    @CLIAction('order', GetOrderDTO)
-    @ServiceAction({cmd: 'order.get'}, GetOrderDTO)
-    public async get(input: GetOrderDTO): Promise<{ id: number }> {
-        return {id: input.id}
-    }
-
-    //POST /orders，请求体为 JSON
-    @POST('/orders', CreateOrderDTO)
-    public async create(input: CreateOrderDTO): Promise<{ product: string, quantity: number }> {
-        return input
-    }
-
-    //每 5 分钟执行一次
-    @Schedule('5m')
-    public async report(): Promise<void> {
-    }
-}
-
-Application.run(() => ({
-    id: 'orders.app',
-    name: 'Orders',
-    components: {
-        entrypoint: buildEntrypoints({
-            controllers: [OrderController],
-            http: expressHTTPEntrypoint({port: 8080}),
-            cli: commanderCLIEntrypoint(),
-            service: socketIOServiceEntrypoint({port: 8081}),
-            schedule: scheduleEntrypoint()
-        })
-    },
-    bootstrap: ['entrypoint']
-}))
-```
-
-## 2. 动作装饰器（`lakutata/decorator/ctrl`）
-
-每个装饰器的参数依次为：地址，可选的输入 DTO 类，可选的动作选项（`acl`、`name`、`description`、`groups`、`rule`、`middlewares`）。
-
-### HTTP：`@HTTPAction`、`@GET`、`@POST`、`@PUT`、`@PATCH`、`@DELETE`、`@HEAD`、`@OPTIONS`
-
-```text
-@HTTPAction(route, method | methods, DTOClass?, options?)
-@GET(route, DTOClass?, options?)
-```
-
-- 路由使用 HTTP 适配器的语法（`/users/:id`）；方法不区分大小写（`'get'`、`['get', 'post']`）。
-- 输入由查询参数和解析后的请求体（JSON 或 URL 编码）合并而成，路由参数覆盖在其上。查询参数和路由参数都是字符串，而校验规则是严格的：用 `.strict(false)` 进行转换。
-- 返回值以 JSON 响应（`undefined` 时为 204）。`lakutata/com/entrypoint` 中的 `Result.status(201, data, headers)`、`Result.file(path)` 和 `Result.events(producer)`（Server-Sent Events）用于控制响应。
-
-### CLI：`@CLIAction`
-
-```text
-@CLIAction(command, DTOClass?, options?)
-```
-
-- 命令由名称和可选的位置参数组成（`'copy <source> [target]'`、`'<files...>'`）；名称前面的词是命令分组（`'package exe <file>'`）。DTO 的其他属性是选项（`--times 2`），布尔属性是开关（`--shout`）；校验规则的 `.description()` 是选项的帮助文本，动作选项 `description` 是命令的帮助文本。
-- 返回值写到 stdout（字符串原样输出，其他值输出为 JSON）；错误写到 stderr，命令以退出码 1 结束。
-
-### 服务：`@ServiceAction`
-
-```text
-@ServiceAction(pattern, DTOClass?, options?)
-```
-
-- 模式是一个对象（最多嵌套 2 层），消息必须包含这些键且值相同；字符串值可以是通配符（`'user.*'`）。匹配的模式中最具体的一个胜出。输入是去掉模式中各键后的消息。
-- 调用方收到 `{success: true, error: null, payload}`，或 `{success: false, error, payload: null}`，其中 `error` 包含错误的各属性（`errno`、`errMsg`、`statusCode`、`message` 等）；JSON-RPC 则以它自己的 `result` 和 `error` 响应。没有模式匹配的消息会以 `ControllerActionNotFoundException` 失败。
-
-### 定时任务：`@Schedule`
-
-```text
-@Schedule(schedule, options?)
-```
-
-当入口配置了定时适配器（`schedule: scheduleEntrypoint()`）时，方法按计划执行。计划可以是时长（`'30s'`、`'1h30m'`，表示间隔）、cron 表达式（`'0 */5 * * * *'`，5 或 6 个字段，或 `'@daily'` 这样的宏），或者是 `{every}`、`{cron, timezone}` 形式的选项，并可附带：
-
-- `overlap`（默认 `false`）：上一次执行尚未结束时也开始新的执行；否则跳过本次；
-- `immediate`（默认 `false`）：应用启动后立即额外执行一次；
-- `exclusive`（默认 `false`）：借助互斥锁组件，同一时间只在应用的一个实例中执行（`true` 使用名为 `mutex` 的组件，`{mutex, key}` 指定组件名和锁名）；见 [Mutex](Mutex.md)。
-
-每次执行都有自己的作用域，并经过中间件和访问控制；方法接收空输入，`this.context` 是 `ScheduleContext`（含 `schedule`、计划时间、执行序号 `run`）。抛出的错误交给 `scheduleEntrypoint` 的 `onError` 选项，或记录到日志，后续执行照常进行。
-
-```typescript
-import {Controller, ScheduleContext} from 'lakutata/com/entrypoint'
-import {Schedule} from 'lakutata/decorator/ctrl'
-
-class JobController extends Controller {
-    //每 30 秒一次，并在应用启动后立即执行一次
-    @Schedule({every: '30s', immediate: true})
-    public async heartbeat(): Promise<void> {
-        if (this.context instanceof ScheduleContext) console.log(`run ${this.context.run} of ${this.context.schedule}`)
-    }
-
-    //上海时间每天 03:00，同一时间只在一个实例中执行（需要名为 "mutex" 的互斥锁组件）
-    @Schedule({cron: '0 3 * * *', timezone: 'Asia/Shanghai', exclusive: true}, {name: 'Purge the expired sessions'})
-    public async purge(): Promise<void> {
-    }
-}
-```
-
-### 前缀：`@Prefix`
-
-在控制器类上使用 `@Prefix({route, command, pattern})` 为它的动作添加前缀：`route` 加在 HTTP 路由之前，`command` 加在 CLI 命令之前（以 `:` 连接，`user` 和 `get` 得到 `user:get`），`pattern` 合并到服务模式中。
-
-```typescript
-import {DTO} from 'lakutata'
-import {Controller} from 'lakutata/com/entrypoint'
-import {CLIAction, GET, Prefix, ServiceAction} from 'lakutata/decorator/ctrl'
-import {Expect} from 'lakutata/decorator/dto'
-
-class UserIdDTO extends DTO {
-    @Expect(DTO.String().required())
-    public id: string
-}
-
-@Prefix({route: '/users', command: 'user', pattern: {resource: 'user'}})
-class UserController extends Controller {
-    //GET /users/:id、命令 "user:get <id>"、消息 {resource: 'user', act: 'get', id}
-    @GET('/:id', UserIdDTO)
-    @CLIAction('get <id>', UserIdDTO)
-    @ServiceAction({act: 'get'}, UserIdDTO)
-    public async get(input: UserIdDTO): Promise<{ id: string }> {
-        return {id: input.id}
-    }
-}
-```
-
-## 3. 中间件与访问控制
-
-中间件包裹在动作外围执行，早于输入校验和访问控制：可以是函数 `(invocation, next) => Promise<unknown>`，也可以是 `Middleware` 类。可以把它们交给 `buildEntrypoints({middlewares})`（作用于所有动作）、适配器的 `middlewares` 选项、控制器类或方法上的 `@UseMiddlewares(...)`，以及动作选项 `middlewares`。
-
-```typescript
-import {type ActionInvocation, Controller, type Next} from 'lakutata/com/entrypoint'
-import {GET, UseMiddlewares} from 'lakutata/decorator/ctrl'
-
-async function timing(invocation: ActionInvocation, next: Next): Promise<unknown> {
-    const started: number = Date.now()
-    try {
-        return await next()
-    } finally {
-        console.log(`${invocation.context.type} took ${Date.now() - started} ms`)
-    }
-}
-
-@UseMiddlewares(timing)
-class HealthController extends Controller {
-    @GET('/health')
-    public async health(): Promise<string> {
-        return 'ok'
-    }
-}
-```
-
-声明了 `{acl: true}` 的动作由 `buildEntrypoints({rules})` 中的规则检查：规则是 `AccessControlRule` 的子类，每次请求都会创建，其 `rule()` 返回 `false` 时以 `AccessDeniedException`（HTTP 403）拒绝请求。动作选项 `rule` 是该动作自己的规则。
-
-```typescript
-import {AccessControlRule, ContextType, Controller, type HTTPContext} from 'lakutata/com/entrypoint'
-import {DELETE} from 'lakutata/decorator/ctrl'
-
-class AdminRule extends AccessControlRule<HTTPContext> {
-    public get supportContextTypes(): ContextType[] {
-        return [ContextType.HTTP]
-    }
-
-    public async rule(): Promise<boolean> {
-        if (!this.targetAction.groups.includes('admin')) return true
-        return this.context.request.headers['x-role'] === 'admin'
-    }
-}
-
-class UserController extends Controller {
-    @DELETE('/users/:id', {acl: true, groups: ['admin']})
-    public async remove(input: { id: string }): Promise<void> {
-    }
-}
-
-//buildEntrypoints({controllers: [UserController], rules: [AdminRule], httpActionGroups: {admin: 'Administration'}})
-```
-
-动作的分组必须在 `buildEntrypoints` 的 `httpActionGroups`、`cliActionGroups` 或 `serviceActionGroups` 中声明。`shutdownTimeout`（默认 30000 毫秒）是入口停止时留给正在处理的请求的时间。
-
-## 4. 传输方式
-
-| `buildEntrypoints` 的选项 | 适配器 | 子路径 | 需安装 |
-|---|---|---|---|
-| `http` | `expressHTTPEntrypoint({port})` | `lakutata/adapter/express` | `express` |
-| `http` | `fastifyHTTPEntrypoint({port})` | `lakutata/adapter/fastify` | `fastify` |
-| `cli` | `commanderCLIEntrypoint()` | `lakutata/adapter/commander` | `commander`（交互提示需要 `@inquirer/prompts`） |
-| `service` | `socketIOServiceEntrypoint({port})` | `lakutata/adapter/socket.io` | `socket.io` |
-| `service` | `jsonRPCServiceEntrypoint()`（HTTP、WebSocket、stdio） | `lakutata/adapter/jsonrpc` | WebSocket 需要 `ws` |
-| `service` | `electronIPCServiceEntrypoint()` | `lakutata/adapter/electron` | （Electron） |
-| `service` | `httpServiceEntrypoint({port})`（`POST /`，事件通过 SSE 推送） | `lakutata/com/entrypoint` | |
-| `service` | `grpcServiceEntrypoint({port})` | `@lakutata/grpc/service` | `@lakutata/grpc` |
-| `service` | `natsServiceEntrypoint('nats')` | `@lakutata/nats` | `@lakutata/nats` |
-| `schedule` | `scheduleEntrypoint()` | `lakutata/com/entrypoint` | |
-
-每个选项可以是一个适配器或适配器数组。`lakutata/com/entrypoint` 中的 `buildHTTPEntrypoint`、`buildCLIEntrypoint` 和 `buildServiceEntrypoint` 用于以 lakutata 2.x 的风格编写入口函数，以接入其他库；`EntrypointAdapter`（来自 `@lakutata/entrypoint/channel`）是适配器的接口。
-
-### 从 2.x 的入口函数迁移到 HTTP 适配器
-
-2.x 的 HTTP 入口函数（`buildHTTPEntrypoint`）仍然可以使用：它在入口的启动阶段被调用（此时它获取的对象，比如注入了入口的 Authenticator，都可以正常获取），并且会被等待，所以应用在它的服务开始监听之后才算启动完成。迁移到 `expressHTTPEntrypoint` 时：
-
-- 应用自己的中间件和路由（CORS、压缩、健康检查、Authenticator、Web UI）放进 `before` 钩子，钩子里用 `module.getObject()` 获取对象；请求体解析用 `body` 选项（`{limit: '100mb'}`）；服务器的 `keepAliveTimeout`/`headersTimeout` 用 `server` 选项；
-- 从请求构造动作输入（查询参数、请求体、会话中的值）用 `input` 选项；
-- `{errno, errMsg, data}` 封套用 `jsonEnvelope()`。2.x 的应用通常对动作的错误返回 200，而对 Express 中间件的错误（`next(error)`，比如 Authenticator 的 401）使用错误自带的状态码：`jsonEnvelope({actionErrorStatus: 200})` 的行为与此相同。如果用 `errorStatus: 200`，401 也会变成 200，按 401 跳转登录页的前端就会失效；
-- 应用封套里的其他字段（`timestamp`、`nonce`、请求 ID）用 `extra` 选项给出。它在每次响应时调用，成功和错误的响应都会带上这些字段：`jsonEnvelope({actionErrorStatus: 200, extra: () => ({timestamp: Date.now()})})`。这些字段排在 `errno`、`errMsg`、`data` 之后，不会覆盖这三个字段，因此不需要为了保留它们自己实现响应器。
-
-```typescript
-import {buildEntrypoints} from 'lakutata/com/entrypoint'
-import {expressHTTPEntrypoint, jsonEnvelope} from 'lakutata/adapter/express'
-import type {Express, NextFunction, Request, Response} from 'express'
-
-class Unauthorized extends Error {
-    public readonly errno: string = 'E_UNAUTHORIZED'
-
-    public readonly statusCode: number = 401
-}
-
-export const entrypoint = buildEntrypoints({
-    controllers: [],
-    http: expressHTTPEntrypoint({
-        port: 3000,
-        body: {limit: '100mb'},
-        before: async (app: Express): Promise<void> => {
-            app.get('/health', (_request: Request, response: Response): unknown => response.json({status: 'ok'}))
-            //请求的鉴权：它的错误保留自带的状态码（401）
-            app.use((request: Request, _response: Response, next: NextFunction): void => request.headers.authorization ? next() : next(new Unauthorized('Not logged in')))
-        },
-        //动作的错误在封套中以 200 返回，与 2.x 相同，并带上时间戳
-        respond: jsonEnvelope({actionErrorStatus: 200, extra: (): Record<string, unknown> => ({timestamp: Date.now()})})
-    })
-})
-```
-
-`fastifyHTTPEntrypoint` 的选项相同（使用 `fastifyJSONEnvelope({actionErrorStatus: 200, extra})`，Authenticator 写成 Fastify 的钩子）。自定义的响应器可以从 `error` 的第四个参数得到每个错误的来源（`'action'` 或 `'request'`）。
-
-### 服务动作的客户端与推送事件
-
-带客户端的服务适配器会把请求所属客户端的 id 放入上下文的 `ServiceContext.clientId`：`electronIPCServiceEntrypoint`（窗口中的每个页面）、`socketIOServiceEntrypoint`（每个 socket，连接时通过 `auth.id` 或 `id` 请求头给出 id）、`httpServiceEntrypoint`（`POST` 请求的 `id` 请求头，事件流 `GET /events` 的 `id` 请求头或查询参数）、WebSocket 和 stdio 上的 `jsonRPCServiceEntrypoint`，以及 `grpcServiceEntrypoint`（`id` 元数据）。入口组件用 `notify(clientId, event, ...args)` 向某个客户端推送事件（返回是否有客户端收到），用 `broadcast(event, ...args)` 向所有客户端推送（返回客户端数量）：
-
-```typescript
-import {Controller, Entrypoint, ServiceContext} from 'lakutata/com/entrypoint'
-import {ServiceAction} from 'lakutata/decorator/ctrl'
-import {Inject} from 'lakutata/decorator/di'
-
-class TaskController extends Controller {
-    @Inject('entrypoint')
-    protected readonly entrypoint: Entrypoint
-
-    @ServiceAction({cmd: 'start'})
-    public async start(): Promise<void> {
-        const clientId: string | undefined = (this.context as ServiceContext).clientId
-        if (clientId) setTimeout((): void => void this.entrypoint.notify(clientId, 'done', {task: 1}), 1000)
-        this.entrypoint.broadcast('started', {task: 1})
-    }
-}
-```
-
-Electron 的渲染进程用 `window.ipc.on(event, listener)` 监听事件（Electron 模板中提供），socket 用 `socket.on(event, listener)`，HTTP 客户端通过 `GET /events` 的 Server-Sent Events 监听（`EventSource`、curl）。窗口中的页面在重新加载或窗口关闭之前都是同一个客户端。
-
-### JSON-RPC 2.0
-
-`jsonRPCServiceEntrypoint` 通过 JSON-RPC 2.0 提供服务动作：请求的 method 和（按名称给出的）params 就是动作的模式和输入，`{"method": "order.get", "params": {"id": 1}}` 会被分发为 `{method: 'order.get', id: 1}`（`methodField` 指定字段名，`toPattern(method, params)` 把它们映射为其他模式，`positionalParams` 接受按位置给出的 params）。批量请求和通知遵循规范；错误码为 `-32601`（没有匹配的动作）、`-32602`（DTO 拒绝了输入）和 `-32000`（动作抛出的错误，完整的错误对象放在 `data` 中）。传输方式有 HTTP（`POST`）、WebSocket（`ws` 包）和 stdio（按行或按 `Content-Length` 头分帧）；后两者以通知的形式推送客户端事件。在 WebSocket 上，不响应 ping 的连接会被关闭（`heartbeat`，30 秒）；在 stdio 上，输入结束后应用退出（`end: 'application'`）。
-
-```text
-service: [
-    jsonRPCServiceEntrypoint({port: 4000, path: '/rpc'}),
-    jsonRPCServiceEntrypoint({transport: 'websocket', port: 4001}),
-    jsonRPCServiceEntrypoint({transport: 'stdio', framing: 'content-length'})
-]
-```
-
-### gRPC 与 NATS
-
-`grpcServiceEntrypoint`（`@lakutata/grpc/service`）通过 gRPC 提供服务动作：服务 `lakutata.service.v1.Service`（`SERVICE_PROTO`，供其他语言的客户端使用）以模式和输入的 JSON 调用动作，并以流的形式推送客户端的事件。用 `buildGRPCServiceProxy` 声明的 `GRPCServiceProxy` 调用远程应用的动作并监听其事件。调用的截止时间到达时会中止对应的动作（`this.signal`）。详见 `@lakutata/grpc` 的 README。
-
-```typescript
-import {Application} from 'lakutata'
-import {buildGRPCServiceProxy, type GRPCServiceProxy} from '@lakutata/grpc/service'
-
-Application
-    .run(() => ({
-        id: 'shop.app',
-        name: 'Shop',
-        components: {
-            orders: buildGRPCServiceProxy({address: 'orders.internal:50051'})
-        }
-    }))
-    .onLaunched(async (app: Application): Promise<void> => {
-        const orders: GRPCServiceProxy = await app.getObject<GRPCServiceProxy>('orders')
-        orders.on('orderChanged', (order: { id: number }): void => console.log(order))
-        console.log(await orders.invoke({cmd: 'order.get', id: 1}))
-    })
-```
-
-`natsServiceEntrypoint`（`@lakutata/nats`）通过 NATS 提供服务动作，订阅以应用 id 为名的主题，各实例共享同一个队列组；用 `buildServiceProxy` 声明的 `ServiceProxy` 调用它们。详见 `@lakutata/nats` 的 README。

package/doc/zh/Core.md

@@ -1,256 +0,0 @@
-# Lakutata 核心
-
-本指南介绍框架的核心（`@lakutata/core` 包，由 `lakutata`、`lakutata/decorator/di`、`lakutata/decorator/dto` 和 `lakutata/decorator/asst` 重新导出）：对象及其容器、生命周期类型与作用域、异步构造、依赖注入、模块以及应用的生命周期。更多细节见 `@lakutata/core` 的 README 和各导出的类型声明。
-
-## 1. 对象与容器
-
-应用中的每个对象都由 IoC 容器创建，从不使用 `new`。类的继承关系如下：
-
-| 类 | 作用 | 默认生命周期 |
-|---|---|---|
-| `BaseObject` | 根类：异步构造、`init()`/`destroy()`、`getObject()` | `@Transient` |
-| `Provider` | 存在于某个作用域（如一次请求）中的功能单元（仓储、哈希器等） | `@Scoped` |
-| `Component` | 整个应用共享的长期服务（日志、数据库、入口等），同时是事件发射器 | `@Singleton`（锁定） |
-| `Module` | 拥有自己的组件、提供者和对象的组件 | `@Singleton`（锁定） |
-| `Application` | 根模块，由 `Application.run()` 创建 | |
-| `Controller`（`lakutata/com/entrypoint`） | 处理入口请求的提供者 | `@Scoped`（锁定） |
-
-### 生命周期类型
-
-| 装饰器（`lakutata/decorator/di`） | 实例数量 |
-|---|---|
-| `@Singleton()` | 每个注册该类的容器一个，由它的使用者和它的作用域共享 |
-| `@Scoped()` | 每个作用域一个（`container.createScope()`；入口的每次请求是一个作用域，根容器本身也是一个作用域） |
-| `@Transient()` | 每次解析都新建，从不缓存 |
-
-子类继承父类的生命周期类型。`Component` 和 `Module` 锁定了自己的类型：子类声明其他类型会抛出 `LifetimeLockedException`；`Provider` 默认是 `@Scoped`，也可以声明为 `@Transient` 或 `@Singleton`（与 2.x 相同：一个实例由各作用域共享，例如 `@lakutata/nats` 的 `ServiceProxy`）；长期持有资源（连接、订阅、服务器）的对象更适合用 `Component`。单例注入作用域对象时，拿到的是创建它的那个作用域的实例。`@Lifetime('SINGLETON' | 'SCOPED' | 'TRANSIENT', lock)` 是这三个装饰器的完整写法。
-
-### 作用域
-
-作用域是一个子容器，持有自己的作用域对象实例，父容器的单例和注册项则是共享的。入口为每次请求创建一个作用域：该请求的控制器以及它注入的提供者都在其中创建，请求结束时一并销毁。组件可以通过受保护的 `createScope()` 创建自己的作用域。
-
-## 2. 异步构造
-
-容器以异步方式创建对象，`getObject()`（或 `@Inject`）返回的 Promise 在对象就绪后才完成：
-
-1. 解析它的 `@Inject` 属性；
-2. 为它的 `@Configurable` 属性赋予配置值，并由各自的校验规则校验（及转换）；未配置的属性保留其初始值，没有初始值时取校验规则的默认值；
-3. 执行它的 `init()`（在此抛出的错误会导致创建失败）；
-4. 在它可以被其他对象获取之后，执行它的 `startup()`：获取它的一方会等待 `startup()` 完成（失败时得到同样的错误）；但在 `startup()` 内部、直接或经由它所创建的对象去获取的对象，会立即拿到这个对象，所以它获取的对象可以反过来注入它（入口在这里启动各个适配器，适配器的钩子会获取注入了入口的 Authenticator）。之所以叫 `startup` 而不叫 `start`，是为了避免自带 `start()` 方法的类（如 `@lakutata/docker` 的容器）被框架自动启动；
-5. 应用启动完成（且对象已启动）后，执行它的 `launched()`（不会被等待，其错误会被记录到日志）。
-
-销毁时（调用 `dispose()`，或创建它的对象、作用域、应用被销毁时），先等待 `startup()` 结束，再执行它的 `beforeDestroy()`，再销毁它创建的对象，最后执行它的 `destroy()`。每个对象都拥有自己的容器：通过 `this.getObject()` 创建的对象会随它一起销毁。
-
-```typescript
-import {Application, Component, DTO, type ILogger} from 'lakutata'
-import {Configurable, Inject} from 'lakutata/decorator/di'
-
-class Mailer extends Component {
-    //它的选项，由应用选项中的声明给出
-    @Configurable(DTO.String().required())
-    protected readonly host: string
-
-    //未配置时为 25：初始值就是默认值，和配置值一样会被校验
-    @Configurable(DTO.Number().integer().min(1).max(65535))
-    protected readonly port: number = 25
-
-    //lakutata 包预置的日志组件 "log"
-    @Inject('log')
-    protected readonly log: ILogger
-
-    protected async init(): Promise<void> {
-        this.log.info('Mailer connected to %s:%d', this.host, this.port)
-    }
-
-    public async send(to: string, text: string): Promise<void> {
-        this.log.info('Mail to %s: %s', to, text)
-    }
-
-    protected async destroy(): Promise<void> {
-        this.log.info('Mailer disconnected')
-    }
-}
-
-Application
-    .run(() => ({
-        id: 'com.example.app',
-        name: 'Example',
-        components: {
-            mailer: {class: Mailer, host: 'smtp.example.com'}
-        },
-        bootstrap: ['mailer']
-    }))
-    .onLaunched(async (app: Application): Promise<void> => {
-        const mailer: Mailer = await app.getObject<Mailer>('mailer')
-        await mailer.send('someone@example.com', 'Hello')
-    })
-```
-
-## 3. 依赖注入
-
-`@Inject`（来自 `lakutata/decorator/di`）在对象创建时、`init()` 之前为属性赋值：
-
-- `@Inject()`：注入以属性名注册的对象；
-- `@Inject('name')` 或 `@Inject(symbol)`：注入以该名称注册的对象；
-- `@Inject(SomeClass)`：注入为该类注册的对象（`@Inject(Application)` 注入应用本身）；
-- `@Inject('name', transform)`：注入 `transform(object)` 的返回值（可以是异步函数）。
-
-标记了 `@Autoload()` 的类在第一次被请求时自动注册，而不是报错：单例注册到根容器，作用域类注册到最近的作用域，瞬态类注册到发起请求的容器。无法解析的注册项会使创建失败并抛出 `DependencyInjectionException`。
-
-`@Configurable(schema, fn?)` 把属性声明为对象的选项：它的值来自对象的声明（`{class: Mailer, host: 'smtp.example.com'}`）或 `getObject()` 的第二个参数，经校验规则校验后，如果提供了 `fn` 再交给 `fn` 处理。模块在初始化时会检查其声明的对象的选项：不合法的值会使初始化失败并抛出 `InvalidObjectOptionsException`，不是可配置属性的选项会给出警告。
-
-```typescript
-import {Application, Component, Provider} from 'lakutata'
-import {Autoload, Inject, Scoped} from 'lakutata/decorator/di'
-
-//未在应用中声明：第一次被注入时自动注册
-@Autoload()
-@Scoped()
-class RequestClock extends Provider {
-    public readonly startedAt: number = Date.now()
-}
-
-class Reports extends Component {
-    @Inject(RequestClock)
-    protected readonly clock: RequestClock
-
-    @Inject(Application)
-    protected readonly app: Application
-
-    public elapsed(): number {
-        return Date.now() - this.clock.startedAt
-    }
-}
-```
-
-## 4. 模块
-
-`Module` 在其 `options` 属性的初始值中，用与应用相同的选项声明自己的组件、提供者和对象。模块内的对象先从模块解析依赖，再从应用解析；应用的对象看不到模块内的对象。在应用（或父模块）的 `objects.named` 中声明模块，它的选项写在 `options` 下（合并到其初始值之上），并把它列入 `bootstrap` 以便在启动时创建。
-
-模块被创建时，先检查选项，再注册对象，然后依次执行它的 `bootstrap`。模块外部的对象获取它时（`getObject()`、`@Inject`），要等这些步骤全部完成才会拿到它，若某一步失败则得到该步骤的错误；模块自己的对象（由这些步骤创建）则会立即拿到它。
-
-```typescript
-import {Application, Component, Module, type ModuleOptions} from 'lakutata'
-
-class Billing extends Component {
-    public charge(amount: number): void {
-        console.log(`Charged ${amount}`)
-    }
-}
-
-class PaymentModule extends Module {
-    protected options: ModuleOptions = {
-        components: {
-            billing: {class: Billing}
-        },
-        bootstrap: ['billing']
-    }
-}
-
-Application.run(() => ({
-    id: 'shop.app',
-    name: 'Shop',
-    objects: {
-        named: {
-            payment: {class: PaymentModule}
-        }
-    },
-    bootstrap: ['payment']
-}))
-```
-
-`module.reload()` 会销毁模块及其对象，然后重新初始化。
-
-## 5. 应用
-
-### 选项
-
-`Application.run(options)`（或 `run(() => options)`，在启动时调用该函数，可以是异步的）接受以下选项：
-
-| 选项 | 含义 |
-|---|---|
-| `id`、`name` | 必填。应用的 ID（同时作为 `process.title`）和名称（`app.appId`、`app.appName`） |
-| `timezone` | IANA 时区名，或 `'auto'`（默认）表示使用系统时区；写入 `TZ` |
-| `mode` | `'development'` 或 `'production'`，在环境变量未指定时生效（见下文） |
-| `shutdownSignals` | 使应用优雅退出的信号（默认 `['SIGTERM', 'SIGINT']`），或 `false` |
-| `components`、`providers` | 按名称声明的组件和提供者：`{class, ...options}` |
-| `objects` | 其他对象（模块、普通对象）：`{named: {...}, anonymous: [...]}` |
-| `bootstrap` | 启动时依次执行的步骤：名称、symbol 或类（创建该对象），或以应用为参数调用的异步函数 |
-| `checkOptions` | 启动时检查所声明对象的选项（默认 `true`） |
-
-不带 `class` 的声明会补充框架预置的同名对象的选项：`lakutata` 包预置了 `log`（`Logger`）和 `entrypoint`（`Entrypoint`），因此 `log: {level: 'debug'}` 会设置预置日志组件的级别。`Application.preset(options)` 为进程中的所有应用预置对象。
-
-### 链式 API
-
-```typescript
-import {Application, type ApplicationExitReason, type ILogger} from 'lakutata'
-
-Application
-    //环境变量，在启动时、调用选项函数之前设置
-    .env({TZ_NAME: 'Asia/Shanghai'})
-    //路径别名：传给 path.resolve() 或 app.alias.resolve() 的路径中的 '@data'；目录不存在时创建
-    .alias({'@data': './data'}, true)
-    .run(() => ({
-        id: 'com.example.app',
-        name: 'Example',
-        components: {}
-    }))
-    //bootstrap 完成后调用（不会被等待）
-    .onLaunched((app: Application, log: ILogger): void => log.info('%s launched in %s mode', app.appName, app.mode()))
-    //应用退出时、对象销毁之前调用，会被等待
-    .onDone(async (app: Application, log: ILogger, reason: ApplicationExitReason): Promise<void> => {
-        log.info('%s done (exit code %d%s)', app.appName, reason.code, reason.signal ? `, ${reason.signal}` : '')
-    })
-    //进程中未捕获的异常，应用继续运行
-    .onUncaughtException((error: Error, log: ILogger): void => log.warn(error.message))
-    //启动失败：返回的数字作为退出码（未返回时为 1）
-    .onFatalException((error: Error, log: ILogger): number => {
-        log.error('Launch failed: %s', error.message)
-        return 100
-    })
-```
-
-`app.exit(code)` 以指定退出码优雅地结束应用；`app.exit(true)` 立即以退出码 2 结束进程，不执行 `onDone` 处理函数，也不销毁对象。
-
-### 生命周期
-
-1. 设置环境变量，注册路径别名（`@runtime` 为当前工作目录）。
-2. 读取并校验选项；应用 ID、时区和运行模式。
-3. 在新的根容器中创建应用：注册它的对象，并依次执行 `bootstrap`。
-4. 执行 `onLaunched` 处理函数和各对象的 `launched()` 钩子。
-
-- **启动失败**：应用无法启动时（选项不合法、对象初始化失败、bootstrap 步骤失败），由 `onFatalException` 的处理函数决定退出码（没有返回时为 1）。没有注册处理函数时，框架记录错误后以退出码 1 退出，和 Node.js 处理未捕获异常的方式一致，这样运行它的工具（Docker 的重启策略、Kubernetes、systemd、CI）都能知道启动失败了；已经创建的对象（正在监听的服务、数据库连接等）也不会让进程继续挂着。
-- **退出信号**：收到 `SIGTERM`（`docker stop`、Kubernetes 滚动更新、systemd 停止服务）或 `SIGINT`（Ctrl+C）时，应用会优雅退出：先执行 `onDone` 处理函数，此时应用仍然完全可用（第三个参数说明退出原因：收到信号时是 `{code: 0, signal: 'SIGTERM'}`，调用 `app.exit(code)` 时是 `{code}`）；然后各入口停止接收新请求并等待正在处理的请求完成，各对象被销毁，最后以退出码 0 退出。如果再次收到信号（比如退出过程卡住了），或者信号是在应用启动期间收到的，进程会立即以 128 + 信号编号退出（`SIGTERM` 为 143，`SIGINT` 为 130）。选项 `shutdownSignals` 可以指定其他信号（如 `['SIGTERM', 'SIGINT', 'SIGHUP']`），设为 `false` 则交由 Node.js 处理。
-- **运行模式**：`app.mode()` 返回 `'development'` 或 `'production'`。环境变量会覆盖代码里的配置，同一份构建产物可以在不同模式下运行：依次看环境变量 `MODE`、`NODE_ENV`，然后是选项 `mode`，都没有时为 `'development'`。不是这两个值的 `MODE` 会发出警告并被忽略，不是这两个值的 `NODE_ENV`（如 `test`）会被跳过。确定的模式会写回 `MODE` 和 `NODE_ENV`，第三方库读到的也是同一个模式。环境变量可以来自系统、`Application.env({MODE: 'production'})`，或者 Bun 读取的 `.env` 文件（指 `bun App.js` 这种运行方式；Bun 构建的可执行文件不会读取它）。
-- **打包后的应用**：`isPackaged()`（来自 `lakutata`）表示应用是否以打包形式运行（`lakutata package bundle` 的打包产物或 `lakutata package exe` 的可执行文件）。应用运行时要读取的文件（Web 应用构建好的页面、模板、数据等）在 `package.json` 的 `lakutata.resources` 中声明，写法和 electron-builder 的 `extraResources` 一样：`[{"from": "../ui/dist", "to": "ui"}]`。打包后，`resourcesPath()` 返回这些文件所在的目录；未打包时返回 `undefined`，由应用到构建目录中查找：`const ui = resourcesPath() ? path.join(resourcesPath()!, 'ui') : uiBuildDirectory`。
-
-## 6. 入口
-
-`entrypoint` 组件（`lakutata/com/entrypoint`）通过 HTTP、CLI、服务传输和定时任务对外提供控制器。用 `buildEntrypoints({controllers, http, cli, service, schedule})` 给出它的选项，并把它列入 `bootstrap`；详见 [ActionPattern](ActionPattern.md)。
-
-## 7. 不使用应用的容器
-
-测试、脚本和库可以在单独的容器中使用这些对象：
-
-```typescript
-import {Component, Container, DTO} from 'lakutata'
-import {Configurable} from 'lakutata/decorator/di'
-
-class Mailer extends Component {
-    @Configurable(DTO.String().required())
-    protected readonly host: string
-
-    public async send(to: string, text: string): Promise<string> {
-        return `${this.host} -> ${to}: ${text}`
-    }
-}
-
-const container: Container = new Container()
-//按选项创建，并等待它的 init() 完成
-const mailer: Mailer = await container.set(Mailer, {host: 'localhost'})
-await mailer.send('someone@example.com', 'Hello')
-//销毁它创建的所有对象
-await container.destroy()
-```
-
-`container.register()`/`registerNamed()` 只注册类而不创建对象，`get()` 解析对象，`build()` 无论生命周期类型都新建一个对象，`createScope()` 创建作用域。