lakutata 3.0.0 → 3.1.0

package/doc/zh/Exceptions.md

@@ -0,0 +1,158 @@
+# Lakutata 异常
+
+`lakutata` 中的 `Exception` 是框架所有错误的基类，也是应用自己的异常的基类。异常带有一个供客户端和日志识别的错误码（`errno`）、一条由模板生成的消息，以及错误对应的 HTTP 状态码。动作失败时，传输方式把这些信息发给客户端。
+
+## 1. 声明异常
+
+继承 `Exception`，设置 `errno`；对于会发给客户端的错误，再设置 `statusCode`：
+
+```typescript
+import {Exception} from 'lakutata'
+
+export class OrderNotFoundException extends Exception {
+    public errno: string = 'E_ORDER_NOT_FOUND'
+
+    public readonly statusCode: number = 404
+}
+
+export class PaymentFailedException extends Exception {
+    public errno: string = 'E_PAYMENT_FAILED'
+
+    public readonly statusCode: number = 502
+
+    //自己的属性：随错误一起发送，也一起写入日志
+    public readonly gateway: string = 'stripe'
+}
+
+export function findOrder(id: number): never {
+    throw new OrderNotFoundException('Order {id} not found', {id: id})
+}
+```
+
+异常带有这些属性：
+
+| 属性 | 是什么 |
+|---|---|
+| `errno` | 错误码，可以是字符串（`'E_ORDER_NOT_FOUND'`）或数字 |
+| `message`、`errMsg` | 消息；`errMsg` 是它的副本，会发给客户端 |
+| `err` | 类名（`'OrderNotFoundException'`） |
+| `statusCode` | 错误对应的 HTTP 状态码，默认 500 |
+| `appId`、`appName` | 应用的 id 和名字；异常在应用加载选项之前创建时为 `'Unknown'` |
+| `stack` | 调用栈 |
+
+子类自己的属性，比如上面的 `gateway`，会和其他属性一起发送、一起写入日志。
+
+## 2. 消息
+
+构造函数的参数决定消息：
+
+| 创建方式 | 消息 |
+|---|---|
+| `new OrderNotFoundException('Order {id} not found', {id: 7})` | `Order 7 not found` |
+| `new OrderNotFoundException('Order {0} of {1} not found', 7, 'ada')` | `Order 7 of ada not found` |
+| `new OrderNotFoundException('Order {0} of {1} not found', [7, 'ada'])` | `Order 7 of ada not found` |
+| `new OrderNotFoundException('Order {0} not found', 7)` | `Order 7 not found` |
+| `new OrderNotFoundException('Order %d not found (%s)', 7, 'archived')` | `Order 7 not found (archived)` |
+| `new OrderNotFoundException('Order {id} of {owner} not found', {id: 7})` | `Order 7 of {owner} not found` |
+| `new OrderNotFoundException('Order not found')` | `Order not found` |
+| `new OrderNotFoundException(new Error('timeout'))` | `timeout` |
+| `new OrderNotFoundException()` | `Order not found exception` |
+
+- 模板从一个对象中取值（`{id}`），或者按位置从它后面的参数中取值（`{0}`、`{1}`），参数可以逐个给出，也可以放在一个数组里。`util.format()` 的占位符（`%s`、`%d`、`%j`……）使用同样的参数。
+- 缺少的值会让占位符保留在消息中。生成消息从不抛出错误。
+- 不给参数时，消息由类名中的单词组成，缩写保持大写（`HTTPRequestException` 得到 `HTTP request exception`）。
+
+## 3. 默认消息与原因
+
+要给异常一个默认消息，就在构造函数中接收它，再传给 `super()`：
+
+```typescript
+import {Exception} from 'lakutata'
+
+export class QuotaExceededException extends Exception {
+    public errno: string = 'E_QUOTA_EXCEEDED'
+
+    public readonly statusCode: number = 429
+
+    constructor(message: string = 'The quota of the month is used up') {
+        super(message)
+    }
+}
+```
+
+不要在字段中设置 `message`：这个字段会替换抛出异常时给出的消息；并且在编译选项 `useDefineForClassFields` 为 `true` 时，`errMsg` 会保留默认消息。`lakutata` 发布的 `tsconfig.json` 把这个选项设为 `false`。
+
+`new XxxException(error)` 只保留另一个错误的消息。要保留这个错误本身，把它设为 `cause`：
+
+```typescript
+import {Exception} from 'lakutata'
+
+class PaymentFailedException extends Exception {
+    public errno: string = 'E_PAYMENT_FAILED'
+
+    public readonly statusCode: number = 502
+}
+
+export async function pay(orderId: number, charge: () => Promise<void>): Promise<void> {
+    try {
+        await charge()
+    } catch (error) {
+        const failure: PaymentFailedException = new PaymentFailedException('Payment of order {id} failed', {id: orderId})
+        failure.cause = error
+        throw failure
+    }
+}
+```
+
+日志会在错误之后写出它的原因（见 [Logger](Logger.md) 第 2 节）；HTTP 适配器会沿着原因查找状态码，第一个客户端错误（4xx）优先（见 [HTTP](HTTP.md) 第 6 节）。
+
+## 4. 客户端收到什么
+
+动作失败时，传输方式这样报告异常：
+
+| 传输方式 | 客户端收到 |
+|---|---|
+| HTTP | 状态码 `statusCode` 和 `{errno, errMsg}`（见 [HTTP](HTTP.md) 第 6 节） |
+| Socket.IO、Electron、HTTP 服务、NATS、gRPC | 完整的错误：它所有的自身属性（见 [ServiceCalls](ServiceCalls.md) 第 3 节） |
+| JSON-RPC | 一个错误：输入不合法时错误码为 `-32602`，没有匹配的动作时为 `-32601`，应用正在停止时为 `-32001`，其他情况为 `-32000`；完整的错误放在 `data` 中 |
+| 命令行 | 标准错误中的 `error: <消息>`，退出码为 1（见 [CLI](CLI.md)） |
+| 定时任务 | 没有客户端：异常交给 `onError`，或者写入日志（见 [Schedules](Schedules.md)） |
+
+- 选择 `statusCode` 时看错误出在哪一方：请求有误时用 400 到 499（资源不存在用 404，冲突用 409），应用自身出错时用 500 及以上。
+- 被 DTO 拒绝的输入是 `InvalidValueException`，它的状态码是 400，表示客户端的错误。
+
+## 5. 翻译与识别异常
+
+使用 `I18nMiddleware` 时，异常的消息会按请求的语言翻译，翻译的键是 `errors.<errno>`，参数来自异常的模板（见 [I18n](I18n.md) 中的“异常消息的翻译”一节）。在请求之外，`lakutata` 中的 `exceptionParams(exception)` 返回这些参数。
+
+在应用内部用 `instanceof` 识别异常，跨进程时用 `errno`：客户端收到的是错误的属性，而不是它的类。HTTP 服务、NATS 和 gRPC 的代理抛出的 `ServiceInvokeException` 带有远端错误的 `errno`。
+
+```typescript
+import {Exception} from 'lakutata'
+
+class OrderNotFoundException extends Exception {
+    public errno: string = 'E_ORDER_NOT_FOUND'
+}
+
+export function isMissingOrder(error: unknown): boolean {
+    return error instanceof OrderNotFoundException || (error as { errno?: unknown })?.errno === 'E_ORDER_NOT_FOUND'
+}
+```
+
+## 6. 框架的异常
+
+框架会抛出自己的异常。最常遇到的有：
+
+| 异常 | `errno` | 什么时候 |
+|---|---|---|
+| `InvalidValueException` | `E_INVALID_VALUE` | DTO 拒绝了一个值：动作的输入，或者对 `validate()` 的调用（400） |
+| `InvalidObjectOptionsException` | `E_INVALID_OBJECT_OPTIONS` | 应用启动时，某个对象的选项无效 |
+| `DependencyInjectionException` | `E_DEPENDENCY_INJECTION` | 无法创建对象：缺少某个依赖 |
+| `AccessDeniedException` | `E_ACCESS_DENY` | 访问控制拒绝了请求（403） |
+| `RouteNotFoundException` | `E_ROUTE_NOT_FOUND` | 没有 HTTP 动作对应这个路由和方法（404） |
+| `ControllerActionNotFoundException` | `E_CONTROLLER_ACTION_NOT_FOUND` | 没有动作与服务消息或命令匹配（404） |
+| `EntrypointStoppedException` | `E_ENTRYPOINT_STOPPED` | 应用正在停止（503） |
+| `ServiceInvokeException` | `E_SERVICE_INVOKE` | 通过代理（HTTP 服务、NATS、gRPC）调用的动作失败；带有远端错误的各个属性 |
+| `ServiceUnavailableException` | `E_SERVICE_UNAVAILABLE` | `HTTPServiceProxy` 调用的服务没有给出响应（503） |
+
+每个包的 README 列出了它自己的异常。没有被任何代码捕获的异常，以及导致应用启动失败的异常，会交给应用的处理函数（`onUncaughtException`、`onFatalException`，见 [Application](Application.md) 第 2 节）。

package/doc/zh/GRPC.md

@@ -0,0 +1,226 @@
+# Lakutata gRPC
+
+`@lakutata/grpc` 包让应用通过 gRPC 提供服务动作，也能从另一个应用调用这些动作；任何有 gRPC 库的语言都可以调用它们。它用 TypeScript 基于 Node.js（`^22.13.0 || >=24.11.0`）的 HTTP/2 模块实现，不需要原生插件，也不需要生成代码。`lakutata` 不包含这个包，需要另外安装：
+
+```bash
+npm install lakutata @lakutata/grpc
+```
+
+## 1. 提供服务动作
+
+`@lakutata/grpc/service` 中的 `grpcServiceEntrypoint()` 是入口的一种 `service` 适配器。控制器里的 `@ServiceAction` 方法可以通过 gRPC 按模式调用，和其他服务传输方式一样。
+
+```typescript
+import {Application, Exception} from 'lakutata'
+import {buildEntrypoints, Controller} from 'lakutata/com/entrypoint'
+import {ServiceAction} from 'lakutata/decorator/ctrl'
+import {grpcServiceEntrypoint} from '@lakutata/grpc/service'
+
+class OrderNotFoundException extends Exception {
+    public errno: string = 'E_ORDER_NOT_FOUND'
+}
+
+class OrderController extends Controller {
+    //用 {cmd: 'order.get', id: 1} 调用
+    @ServiceAction({cmd: 'order.get'})
+    public async get(input: { id: number }): Promise<{ id: number, status: string }> {
+        if (input.id === 0) throw new OrderNotFoundException('Order {id} not found', {id: input.id})
+        return {id: input.id, status: 'paid'}
+    }
+}
+
+Application.run(() => ({
+    id: 'orders.service',
+    name: 'Orders',
+    components: {
+        entrypoint: buildEntrypoints({
+            controllers: [OrderController],
+            service: grpcServiceEntrypoint({port: 50051})
+        })
+    },
+    bootstrap: ['entrypoint']
+}))
+```
+
+`grpcServiceEntrypoint` 的选项：
+
+| 选项 | 默认值 | 含义 |
+|---|---|---|
+| `port` | `50051` | 端口；`0` 表示随机选一个空闲端口 |
+| `host` | 所有网络接口 | 监听的地址 |
+| `socketPath` | | 改用 unix socket，代替端口和地址 |
+| `tls` | 无（明文 HTTP/2） | `{cert, key}` 启用 TLS；再加上 `ca` 时，客户端必须出示由它签发的证书（双向 TLS） |
+| `maxMessageSize` | 4 MiB | 请求的最大大小（解压前后都算）；超过时以 `RESOURCE_EXHAUSTED` 失败 |
+| `compression` | `'identity'` | 设为 `'gzip'` 或 `'deflate'` 时，对支持的客户端压缩响应。压缩过的请求总是可以接收 |
+| `listening` | | `(address) => void`，服务开始监听后调用；启动过程会等它完成 |
+| `middlewares` | | 通过 gRPC 调用的动作专用的中间件，在入口的中间件之后执行 |
+| `name` | | 适配器的名字，用来区分多个适配器 |
+
+服务端不提供反射服务，也不提供健康检查服务。
+
+## 2. 从另一个应用调用
+
+`GRPCServiceProxy` 用来调用远端应用的动作。它是一个组件：用 `buildGRPCServiceProxy` 声明在 `components` 下，每个远端应用一个。
+
+```typescript
+import {Application} from 'lakutata'
+import {ServiceInvokeException} from 'lakutata/com/entrypoint'
+import {GRPCError, GRPCStatus} from '@lakutata/grpc'
+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')
+        try {
+            //模式和输入放在同一个对象里，截止时间 5 秒
+            console.log(await orders.invoke({cmd: 'order.get', id: 1}, 5000))
+        } catch (error) {
+            if (error instanceof ServiceInvokeException) {
+                //动作失败：它的 errno、消息和其他属性
+                console.log(error.errno, error.message)
+            } else if (error instanceof GRPCError && error.code === GRPCStatus.UNAVAILABLE) {
+                console.log('The orders service is unreachable')
+            } else {
+                throw error
+            }
+        }
+    })
+```
+
+`invoke(input, timeout)` 返回动作的结果（动作没有返回值时为 `null`）。timeout 默认 10 分钟，就是这次 gRPC 调用的截止时间：时间一到，调用失败，服务端的动作也会被中止（触发它的 `this.signal`）。
+
+`buildGRPCServiceProxy` 的选项：
+
+| 选项 | 默认值 | 含义 |
+|---|---|---|
+| `address` | 必填 | `host:port`、`tcp://host:port`，或 unix socket：`/path`、`unix:///path` |
+| `tls` | 无 | `{ca, cert, key, servername}`，都可省略。只要设置了（哪怕是 `{}`）就启用 TLS；`cert` 和 `key` 是双向 TLS 中客户端的证书 |
+| `clientId` | 随机 UUID | 这个客户端的 id，随每次调用发送（见第 3 节） |
+| `compression` | `'identity'` | 设为 `'gzip'` 或 `'deflate'` 时压缩请求 |
+| `maxMessageSize` | 不限 | 接收的响应的最大大小 |
+| `reconnectDelay` | `1000` | 事件流结束后，等待多少毫秒再重新打开（见第 4 节） |
+
+代理在第一次调用时才建立连接，调用失败时不会自己重试。
+
+## 3. 客户端 id、元数据与截止时间
+
+每次调用都带着元数据 `id`，即客户端的 id：代理的 `clientId`，或者其他语言的客户端发送的 `id` 头。动作通过 `this.context.clientId` 读取它。
+
+`grpcCallOfContext(context)` 让动作拿到整个 gRPC 调用：客户端发送的元数据、截止时间和对端地址。请求来自其他传输方式时，它返回 `undefined`。
+
+```typescript
+import {Controller, type ServiceContext} from 'lakutata/com/entrypoint'
+import {ServiceAction} from 'lakutata/decorator/ctrl'
+import {grpcCallOfContext} from '@lakutata/grpc/service'
+import type {GRPCServerCall} from '@lakutata/grpc'
+
+class OrderController extends Controller {
+    @ServiceAction({cmd: 'order.get'})
+    public async get(input: { id: number }): Promise<{ id: number, tenant: string }> {
+        const call: GRPCServerCall | undefined = grpcCallOfContext(this.context as ServiceContext)
+        //客户端发送的元数据：grpcurl -H 'tenant: acme' ...
+        const tenant: string = call?.metadata('tenant')[0] ?? 'default'
+        return {id: input.id, tenant: tenant}
+    }
+}
+```
+
+- `GRPCServiceProxy` 只发送 `id` 这一项元数据。需要其他元数据（比如授权令牌）的客户端，可以用 `GRPCConnection`（见第 8 节）或其他语言的客户端。
+- 同一个元数据键的值会按逗号拆分，所以 id 里不要有逗号。
+- 客户端取消调用或截止时间已过时，动作的 `this.signal` 会被触发，结果会被丢弃。耗时长的动作应该检查这个信号。
+
+## 4. 事件
+
+动作可以用 `entrypoint.notify(clientId, event, ...args)` 向某个客户端推送事件，或者用 `entrypoint.broadcast(event, ...args)` 推送给所有已连接的客户端。`notify` 返回客户端是否收到了事件，`broadcast` 返回客户端的数量。
+
+```typescript
+import {Controller, type Entrypoint, type ServiceContext} from 'lakutata/com/entrypoint'
+import {ServiceAction} from 'lakutata/decorator/ctrl'
+import {Inject} from 'lakutata/decorator/di'
+
+class OrderController extends Controller {
+    @Inject('entrypoint')
+    protected readonly entrypoint: Entrypoint
+
+    @ServiceAction({cmd: 'order.ship'})
+    public async ship(input: { id: number }): Promise<void> {
+        const clientId: string | undefined = (this.context as ServiceContext).clientId
+        if (clientId) this.entrypoint.notify(clientId, 'orderChanged', {id: input.id, status: 'shipped'})
+    }
+}
+```
+
+另一端用 `orders.on('orderChanged', listener)` 监听；`once` 和 `off` 的用法与事件发射器相同。代理在注册第一个监听器时打开事件流，最后一个监听器移除时关闭。事件流意外结束时（比如服务重启了），会在 `reconnectDelay` 之后重新打开。
+
+事件不会被保存：发送时没有连接的客户端会错过它。
+
+## 5. 错误
+
+动作失败不会让 gRPC 调用失败：调用本身是成功的，响应里带着这个错误，包括它的消息和全部属性（`errno`、`statusCode`，以及调用栈）。`GRPCServiceProxy` 把它作为 `lakutata/com/entrypoint` 中的 `ServiceInvokeException` 抛出：消息是远端的消息，`errno` 等属性从远端错误复制而来，`service` 是代理的地址。
+
+gRPC 层面失败的调用会抛出 `@lakutata/grpc` 中的 `GRPCError`，它的 `code` 是一个 `GRPCStatus`：
+
+| 状态 | 什么时候 |
+|---|---|
+| `UNAVAILABLE` | 连不上服务 |
+| `DEADLINE_EXCEEDED` | 超过截止时间 |
+| `CANCELLED` | 调用被取消 |
+| `RESOURCE_EXHAUSTED` | 消息超过 `maxMessageSize` |
+| `UNIMPLEMENTED` | 方法不存在，或使用了服务端不支持的压缩方式 |
+
+没有模式匹配的调用会以 errno `E_CONTROLLER_ACTION_NOT_FOUND` 失败，和其他服务传输方式一样。
+
+## 6. 从其他语言调用
+
+`SERVICE_PROTO` 是这个服务的 `.proto` 文件，用它生成其他语言的客户端：
+
+```typescript
+import {writeFileSync} from 'node:fs'
+import {SERVICE_PROTO} from '@lakutata/grpc/service'
+
+writeFileSync('service.proto', SERVICE_PROTO)
+```
+
+```text
+service Service {                                       // package lakutata.service.v1
+  rpc Invoke (InvokeRequest) returns (InvokeResponse);  // data：模式和输入的 JSON
+  rpc Events (EventsRequest) returns (stream Event);    // 推送给该客户端的事件，第一个是 "client"（它的 id）
+}
+message InvokeResponse { bool success = 1; bytes payload = 2; bytes error = 3; }  // payload、error：JSON
+message Event { string event = 1; bytes args = 2; }                              // args：JSON 数组
+```
+
+调用时，在 `InvokeRequest.data` 里放模式和输入的 JSON，在元数据 `id` 里放客户端的 id。响应的 `payload` 是结果的 JSON，或者 `error` 是错误的 JSON。用 grpcurl 调用（它把 `bytes` 字段显示为 base64）：
+
+```bash
+DATA=$(printf '{"cmd":"order.get","id":7}' | base64)
+grpcurl -plaintext -proto service.proto -H 'id: go-1' -d "{\"data\": \"$DATA\"}" localhost:50051 lakutata.service.v1.Service/Invoke
+```
+
+用 Python（`grpcio` 包，存根由 `grpcio-tools` 生成）：
+
+```python
+import json
+import grpc
+import service_pb2 as pb
+import service_pb2_grpc as rpc
+
+stub = rpc.ServiceStub(grpc.insecure_channel('localhost:50051'))
+response = stub.Invoke(pb.InvokeRequest(data=json.dumps({'cmd': 'order.get', 'id': 5}).encode()), metadata=[('id', 'python-1')], timeout=5)
+print(json.loads(response.payload) if response.success else json.loads(response.error))
+```
+
+## 7. 停止
+
+应用停止时，服务会拒绝新的调用：代理把它作为 `ServiceInvokeException` 抛出，其 `errno` 为 `E_ENTRYPOINT_STOPPED`。正在进行的调用有入口的 `shutdownTimeout`（默认 30 秒）可以完成。之后事件流结束，服务端关闭。
+
+## 8. 底层组件
+
+这个包也提供服务所依赖的底层组件，脱离 lakutata 也能使用：`GRPCConnection` 是可以调用任何 gRPC 服务端的客户端（一元调用、服务端流、双向流、元数据、TLS）；`GRPCServer` 是服务端；`encode`/`decode` 是基于 schema 的 protobuf 编解码器。详见 `@lakutata/grpc` 的 README。

package/doc/zh/GettingStarted.md

@@ -0,0 +1,148 @@
+# 快速开始
+
+本页先用模板创建第一个 Lakutata 项目，然后介绍如何在已有项目中加入框架，并手写一个应用。
+
+## 1. 环境要求
+
+- Node.js `^22.13.0 || >=24.11.0`：22.13 及以后的 22.x，或 24.11 及以后的版本（不支持 23）。
+- TypeScript，开启它的装饰器（`experimentalDecorators`）及其元数据（`emitDecoratorMetadata`）。框架所需的编译选项以 `lakutata/tsconfig.json` 发布；模板使用 TypeScript 6。
+- ES 模块（`"type": "module"`），和模板一样；包里同时也提供了 CommonJS 构建。
+
+## 2. 创建项目
+
+```bash
+npx @lakutata/cli create --name my-app
+cd my-app
+npm run dev
+```
+
+`npm run dev` 编译项目并启动它；日志中会出现 `my-app started in development mode`，应用在 8080 端口上响应：
+
+```bash
+curl 'http://localhost:8080/example?name=you'
+# {"message":"Hello, you!"}
+```
+
+`default` 模板是一个小型 HTTP 应用。其他模板从另一类应用开始：
+
+| 模板 | 应用 |
+|---|---|
+| `default` | 提供 HTTP 动作的最小应用 |
+| `cli` | 命令行工具，构建为不需要 Node.js 就能运行的可执行文件 |
+| `service` | 以 Docker 镜像部署的 HTTP API |
+| `web-react`、`web-vue` | 提供 React 或 Vue 单页应用（Vite）的 HTTP API |
+| `web-next`、`web-nuxt` | 在同一个进程中提供 Next.js 或 Nuxt 应用的 HTTP API |
+| `electron-react`、`electron-vue` | 桌面应用：Electron，主进程通过 IPC 为 React 或 Vue 渲染进程提供服务 |
+
+```bash
+npx @lakutata/cli create --name shop --template service --with i18n,installer
+```
+
+`--with` 加入可选功能：所有模板都有 `i18n`（多语言消息），`cli`、`service` 和 `web-*` 模板还有 `installer`（安装包和系统服务）。在终端里没有给出 `--with` 时，工具会列出这些功能供选择。模板中的文件见 [ProjectStructure](ProjectStructure.md)，`lakutata create` 的选项见 [Command](Command.md)。
+
+`default` 模板的脚本：
+
+| 脚本 | 作用 |
+|---|---|
+| `npm run dev` | 把项目编译到 `build/` 并启动 |
+| `npm run build` | 把项目编译到 `build/` |
+| `npm start` | 启动编译好的应用 |
+| `npm test` | 编译项目并运行测试（`node --test`） |
+
+其他模板是包含多个包的工作区，它们的脚本作用于每个包，`npm test` 也会先构建各个包再运行测试（见 [ProjectStructure](ProjectStructure.md) 第 2 节）。
+
+## 3. 在已有项目中加入 Lakutata
+
+```bash
+npm install lakutata express
+npm install --save-dev typescript @types/node @types/express @lakutata/cli
+```
+
+`express` 是下面用到的 HTTP 适配器所基于的库。适配器和驱动都是可选依赖，用到时才安装：`fastify`，`commander` 和 `@inquirer/prompts`（命令行工具），`socket.io`，`ws`，数据库驱动（`pg`、`mysql2`、`better-sqlite3` 等），缓存存储（`redis` 等）。
+
+`tsconfig.json`：
+
+```json
+{
+  "extends": "lakutata/tsconfig.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "build"
+  },
+  "include": ["src"]
+}
+```
+
+请保留 `include`：发布的编译选项也会编译 JavaScript 文件（`allowJs`），没有它的话，项目根目录下的配置文件（`eslint.config.js`、`vite.config.ts`）会让构建失败。在 `package.json` 中设置 `"type": "module"`，并参照模板加上脚本：
+
+```json
+{
+  "type": "module",
+  "main": "build/App.js",
+  "scripts": {
+    "clean": "lakutata clean",
+    "build": "npm run clean && tsc",
+    "start": "node build/App.js"
+  }
+}
+```
+
+源码中的相对导入以 `.js` 结尾（`import {config} from './config/Config.js'`），因为 Node.js 在编译后的代码中按这个路径解析。
+
+## 4. 第一个应用
+
+`src/App.ts`：
+
+```typescript
+import {Application, DTO, type ILogger} from 'lakutata'
+import {buildEntrypoints, Controller} from 'lakutata/com/entrypoint'
+import {GET, ServiceAction} from 'lakutata/decorator/ctrl'
+import {Expect} from 'lakutata/decorator/dto'
+import {expressHTTPEntrypoint} from 'lakutata/adapter/express'
+
+class GreetDTO extends DTO {
+    @Expect(DTO.String().optional().default('world'))
+    public name: string
+}
+
+class GreetController extends Controller {
+    //GET /greet?name=you，以及服务动作 {cmd: 'greet', name: 'you'}
+    @GET('/greet', GreetDTO)
+    @ServiceAction({cmd: 'greet'}, GreetDTO)
+    public async greet(input: GreetDTO): Promise<{ message: string }> {
+        return {message: `Hello, ${input.name}!`}
+    }
+}
+
+Application
+    .run(() => ({
+        id: 'com.example.greeter',
+        name: 'Greeter',
+        components: {
+            entrypoint: buildEntrypoints({
+                controllers: [GreetController],
+                http: expressHTTPEntrypoint({port: 8080})
+            })
+        },
+        bootstrap: ['entrypoint']
+    }))
+    .onLaunched((app: Application, log: ILogger): void => log.info('%s started', app.appName))
+```
+
+```bash
+npm run build && npm start
+curl 'http://localhost:8080/greet?name=you'
+# {"message":"Hello, you!"}
+```
+
+- `GreetDTO` 校验输入：`name` 可选，默认为 `world`（[DTOValidation](DTOValidation.md)）。
+- `GreetController` 声明一个动作，这里通过 HTTP 提供；同一个方法也可以同时作为命令行工具的命令或服务动作（[Controllers](Controllers.md)）。
+- `Application.run()` 声明应用的组件：`entrypoint` 组件通过它的适配器对外提供控制器，`bootstrap` 在启动时创建它（[Application](Application.md)、[Entrypoint](Entrypoint.md)）。
+
+## 5. 接下来
+
+- [示例](examples/README.md)：一步步从模板构建完整的应用。
+- [ProjectStructure](ProjectStructure.md)：项目中的文件和脚本。
+- [Application](Application.md)、[Objects](Objects.md) 和 [Injection](Injection.md)：怎样声明应用，以及应用中的对象如何创建、如何获取彼此。
+- [Controllers](Controllers.md) 和 [HTTP](HTTP.md)：动作、它们的输入和响应。
+- [Command](Command.md)、[Workspaces](Workspaces.md)、[NativeAddons](NativeAddons.md)、[Packaging](Packaging.md) 和 [Installers](Installers.md)：`lakutata` 命令、项目中的各个包，以及打包后的应用。