lakutata 3.0.0 → 3.1.0

package/doc/zh/HTTP.md

@@ -0,0 +1,445 @@
+# Lakutata HTTP
+
+HTTP 适配器用 Express 或 Fastify 提供控制器的 HTTP 动作（`@GET`、`@POST`……）。本指南介绍 HTTP 特有的内容：两个适配器及其选项、路由、请求如何变成动作的输入、响应、错误，以及 Web 框架本身的功能。控制器及其动作见 [Controllers](Controllers.md)，中间件和访问控制见 [Middlewares](Middlewares.md)，适配器的启动和停止见 [Entrypoint](Entrypoint.md)。
+
+## 1. 第一个 HTTP API
+
+```bash
+npm install lakutata express
+```
+
+```typescript
+import {Application, DTO, Exception} from 'lakutata'
+import {buildEntrypoints, Controller, Result, type StatusResult} from 'lakutata/com/entrypoint'
+import {DELETE, GET, POST} from 'lakutata/decorator/ctrl'
+import {Expect} from 'lakutata/decorator/dto'
+import {expressHTTPEntrypoint} from 'lakutata/adapter/express'
+
+class OrderIdDTO extends DTO {
+    //路由参数是文本：strict(false) 把 '1' 转换成 1
+    @Expect(DTO.Number().integer().strict(false).required())
+    public id: number
+}
+
+class NewOrderDTO extends DTO {
+    @Expect(DTO.String().required())
+    public product: string
+
+    @Expect(DTO.Number().integer().min(1).default(1))
+    public quantity: number
+}
+
+class OrderNotFoundException extends Exception {
+    public errno: string = 'E_ORDER_NOT_FOUND'
+
+    public statusCode: number = 404
+}
+
+type Order = { id: number, product: string, quantity: number }
+
+const orders: Map<number, Order> = new Map()
+
+class OrderController extends Controller {
+    @POST('/orders', NewOrderDTO)
+    public async create(input: NewOrderDTO): Promise<StatusResult> {
+        const order: Order = {id: orders.size + 1, product: input.product, quantity: input.quantity}
+        orders.set(order.id, order)
+        return Result.status(201, order, {Location: `/orders/${order.id}`})
+    }
+
+    @GET('/orders/:id', OrderIdDTO)
+    public async get(input: OrderIdDTO): Promise<Order> {
+        const order: Order | undefined = orders.get(input.id)
+        if (!order) throw new OrderNotFoundException('Order {id} not found', {id: input.id})
+        return order
+    }
+
+    @DELETE('/orders/:id', OrderIdDTO)
+    public async remove(input: OrderIdDTO): Promise<void> {
+        orders.delete(input.id)
+    }
+}
+
+Application.run(() => ({
+    id: 'orders.app',
+    name: 'Orders',
+    components: {
+        entrypoint: buildEntrypoints({
+            controllers: [OrderController],
+            http: expressHTTPEntrypoint({port: 8080})
+        })
+    },
+    bootstrap: ['entrypoint']
+}))
+```
+
+```text
+$ curl -i -X POST localhost:8080/orders -H 'Content-Type: application/json' -d '{"product": "lamp"}'
+HTTP/1.1 201 Created
+Location: /orders/1
+
+{"id":1,"product":"lamp","quantity":1}
+$ curl localhost:8080/orders/1
+{"id":1,"product":"lamp","quantity":1}
+$ curl -i -X DELETE localhost:8080/orders/1
+HTTP/1.1 204 No Content
+$ curl -i localhost:8080/orders/1
+HTTP/1.1 404 Not Found
+
+{"errno":"E_ORDER_NOT_FOUND","errMsg":"Order 1 not found"}
+$ curl -i -X POST localhost:8080/orders -H 'Content-Type: application/json' -d '{}'
+HTTP/1.1 400 Bad Request
+
+{"errno":"E_INVALID_VALUE","errMsg":"\"product\" is required"}
+```
+
+## 2. Express 还是 Fastify
+
+两个适配器提供同样的动作，返回同样的结果：
+
+| | Express | Fastify |
+|---|---|---|
+| 适配器 | `lakutata/adapter/express` 中的 `expressHTTPEntrypoint()` | `lakutata/adapter/fastify` 中的 `fastifyHTTPEntrypoint()` |
+| 需要安装 | `express`（4 或 5） | `fastify`（5） |
+
+`expressHTTPEntrypoint()` 的选项：
+
+| 选项 | 默认值 | 含义 |
+|---|---|---|
+| `port` | `80` | 端口；`0` 表示任选一个空闲端口。端口已被占用时，应用启动失败 |
+| `host` | 所有网络接口 | 监听的地址，比如 `'127.0.0.1'` 表示只接受本机的请求 |
+| `name` | | 适配器的名字，用来区分多个适配器 |
+| `body` | `{limit: '1mb'}` | JSON 和 URL 编码请求体的大小上限（`'5mb'`，或者字节数）；`false` 表示不解析请求体 |
+| `server` | | Node.js HTTP 服务器的选项：`keepAliveTimeout`、`headersTimeout`、`requestTimeout`…… |
+| `app` | 新建的应用 | 一个已有的 Express 应用，动作会加到它上面 |
+| `input` | 查询参数和请求体 | 从请求构造输入（第 4 节） |
+| `respond` | `JSONResponder` | 写出结果和错误（第 6 节） |
+| `middlewares` | | 这个适配器上的动作使用的中间件，在入口的中间件之后执行 |
+| `before` | | `(app, context) => …`：添加应用自己的中间件和路由（第 7 节） |
+| `fallback` | | 响应动作路径之外的请求，比如 Web 界面的页面（第 7 节） |
+| `stop` | | 适配器停止、服务器关闭之后调用 |
+| `heartbeat` | `15000` | 每隔多久发送一条注释，让事件流保持连接，单位毫秒（第 5 节） |
+
+`fastifyHTTPEntrypoint()` 的选项相同，只是没有 `body`、`server` 和 `app`，取而代之的是 `fastify`：一个 Fastify 实例，或者要创建的实例的选项（`bodyLimit`，默认 1 MiB；`trustProxy`；`connectionTimeout`、`keepAliveTimeout`、`requestTimeout`；`logger`……）。
+
+两者的不同之处：
+
+| | Express | Fastify |
+|---|---|---|
+| URL 编码的表单请求体 | 会解析 | 以 415 拒绝 |
+| `this.context.request` | Express 的请求（`ip`、`get()`、`hostname`……） | Node.js 的请求 |
+| 通配符路由 | `/files/*path`：输入得到 `path: ['docs', 'a.txt']` | `/files/*`：输入得到 `'*': 'docs/a.txt'` |
+| `GET`、`HEAD`、`POST`、`PUT`、`PATCH`、`DELETE`、`OPTIONS`、`TRACE` 之外的 HTTP 方法 | 直接支持 | 需要在 `before` 中用 `app.addHttpMethod()` 注册，否则启动失败 |
+| 用 `fallback` 提供 Web 界面 | `staticUI()`（第 7 节） | 自己编写处理函数 |
+| Web 框架自身错误的 `errno` | `E_UNKNOWN` | 它自己的错误码，比如 `FST_ERR_CTP_BODY_TOO_LARGE` |
+| 应用停止时，传入的 Express 应用或 Fastify 实例 | 保持不变 | 被关闭 |
+
+应用停止时（见 [Entrypoint](Entrypoint.md) 第 4 节），适配器不再接受新的连接，并结束事件流；Fastify 还会对已打开的连接上仍然到达的请求返回 503。正在处理的请求可以在入口的 `shutdownTimeout` 内完成（超时后以 503 响应），之后最多再有一秒来发送响应，然后剩下的连接被关闭，WebSocket 连接也一样。
+
+## 3. 路由
+
+| 装饰器 | 方法 |
+|---|---|
+| `@GET(route)`、`@POST`、`@PUT`、`@PATCH`、`@DELETE`、`@HEAD`、`@OPTIONS` | 与名字相同的方法 |
+| `@HTTPAction(route, method)` | 一个方法（`'purge'`），或者一组方法（`['get', 'post']`） |
+
+它们接下来的参数是输入的 DTO 和动作的选项，两者都可以省略（见 [Controllers](Controllers.md) 第 3 节）。
+
+```typescript
+import {DTO} from 'lakutata'
+import {Controller} from 'lakutata/com/entrypoint'
+import {GET, HTTPAction, Prefix} from 'lakutata/decorator/ctrl'
+import {Expect} from 'lakutata/decorator/dto'
+
+class SearchDTO extends DTO {
+    @Expect(DTO.String().required())
+    public keyword: string
+}
+
+@Prefix({route: '/api'})
+class LibraryController extends Controller {
+    //GET /api/search?keyword=lamp，或者带请求体 {"keyword": "lamp"} 的 POST /api/search
+    @HTTPAction('/search', ['get', 'post'], SearchDTO)
+    public async search(input: SearchDTO): Promise<string[]> {
+        return [input.keyword]
+    }
+
+    //使用 Express 时，GET /api/files/docs/guide.pdf：input.path 是 ['docs', 'guide.pdf']（使用 Fastify 时：'/files/*' 和 input['*']）
+    @GET('/files/*path')
+    public async file(input: { path: string[] }): Promise<string> {
+        return input.path.join('/')
+    }
+}
+```
+
+- 路由使用 Web 框架的语法：在两个框架中，`:id` 都表示一个参数；通配符的写法不同（第 2 节）。
+- `@Prefix({route})` 给控制器的所有路由加上前缀（见 [Controllers](Controllers.md) 第 6 节）。
+- `GET` 动作也会响应同一路由的 `HEAD` 请求（不带响应体），除非这个路由有自己的 `HEAD` 动作。
+- 如果请求的方法在它的路由上没有对应的动作，请求以 404（`E_ROUTE_NOT_FOUND`）响应，而不是 405。没有任何机制会自动响应 `OPTIONS`：在添加处理 CORS 的中间件之前，浏览器的预检请求都会失败（第 7 节）。
+
+## 4. 输入
+
+默认情况下，动作的输入由查询参数、请求体的属性和路由参数依次合并而成，后者覆盖前者：
+
+```text
+POST /orders/7?id=1&note=a   请求体为 {"id": 5, "note": "b"}   →   {id: '7', note: 'b'}
+```
+
+之后由动作的 DTO 校验输入，并去掉 DTO 没有声明的键。`this.context.data` 是校验之前的输入，不包含路由参数。
+
+- **文本。** 查询参数和路由参数的值都是字符串：数字或布尔值的校验规则需要 `.strict(false)`，才能接受 `'42'` 或 `'true'`。
+- **查询参数。** 出现多次的键是一个数组（`?tag=a&tag=b` → `tag: ['a', 'b']`）。在 Express 5 和 Fastify 中，方括号不会形成嵌套：`?filter[status]=open` 得到的键是 `'filter[status]'`。
+- **JSON 请求体。** 数组无法作为输入使用（Express 把它的元素放在以序号为名的键下，Fastify 忽略它）：列表要放在一个对象里发送（`{"items": [...]}`）。
+- **表单。** Express 会解析 URL 编码的请求体，方括号会形成嵌套（`a[b]=1` → `a: {b: '1'}`）；Fastify 以 415 拒绝它们。两者都不解析 `multipart/form-data`，也就是文件上传（第 7 节）。
+- **上限。** 请求体超过上限时以 413 拒绝，JSON 格式错误时以 400 拒绝。
+
+`input` 选项从请求构造输入。比如，把客户端的地址和语言交给动作（只有声明了 `ip` 和 `language` 的 DTO 才会保留它们）：
+
+```typescript
+import {expressHTTPEntrypoint} from 'lakutata/adapter/express'
+import type {Request} from 'express'
+
+export const http = expressHTTPEntrypoint({
+    port: 8080,
+    input: (request: Request): Record<string, unknown> => ({
+        ...request.query,
+        ...request.body,
+        ip: request.ip,
+        language: request.get('accept-language')
+    })
+})
+```
+
+路由参数总是会合并到它的结果上。使用 Express 时，动作也可以直接读取请求：`(this.context as HTTPContext).request as unknown as Request` 得到 Express 的请求，带有 `ip`、`get()` 以及中间件添加的属性。使用 Fastify 时，`this.context.request` 是 Node.js 的请求：要通过 `input` 把 `request.ip` 交给动作。
+
+## 5. 响应
+
+- 返回值以 JSON 发送；`undefined` 以 204 响应。
+- `Result.status(status, data?, headers?)` 发送状态码和响应头，可以带数据，也可以不带。
+- `Result.file(source, options?)` 发送一个文件：文件路径（相对于工作目录）、`Buffer` 或者流。`filename` 让它作为下载发送；`contentType` 设置它的类型，否则根据文件名的扩展名推断；`etag` 发送 `ETag` 响应头，请求的 `If-None-Match` 与它相同时以 304 响应。
+- `Result.events(producer)` 发送 Server-Sent Events。
+
+```typescript
+import {Readable} from 'node:stream'
+import {Controller, Result, type EventsResult, type FileResult, type StatusResult} from 'lakutata/com/entrypoint'
+import {GET, POST} from 'lakutata/decorator/ctrl'
+
+class ExportController extends Controller {
+    //一个下载
+    @GET('/exports/orders.csv')
+    public async orders(): Promise<FileResult> {
+        return Result.file(Readable.from(['id,product\n', '1,lamp\n']), {contentType: 'text/csv', filename: 'orders.csv'})
+    }
+
+    //一个任务的进度，直到任务结束或者客户端离开
+    @GET('/exports/progress')
+    public async progress(): Promise<EventsResult> {
+        return Result.events(async (send, signal: AbortSignal): Promise<void> => {
+            for (let percent: number = 0; percent <= 100 && !signal.aborted; percent += 25) {
+                send({percent: percent}, 'progress')
+                await new Promise((resolve: (value: unknown) => void): unknown => setTimeout(resolve, 1000))
+            }
+        })
+    }
+
+    //重定向
+    @POST('/logout')
+    public async logout(): Promise<StatusResult> {
+        return Result.status(303, undefined, {Location: '/'})
+    }
+}
+```
+
+事件按照标准的格式写出：数据为 JSON（字符串按原样写出，每行一个 `data:`），给出了事件名和 id 时也一并写出：
+
+```text
+id: 1
+event: tick
+data: {"n":1}
+
+data: line one
+data: line two
+```
+
+- 每隔 `heartbeat` 毫秒发送一条注释（`: ping`），让代理不断开连接。
+- 生产者函数返回或失败时，流就结束；失败时不会再发送任何内容，因为响应头已经发出。客户端离开或应用停止时，`signal` 会被中止。
+- 生产者函数在请求的作用域销毁之后运行：它应该使用组件，而不是属于请求的提供者。
+
+动作也可以通过 `this.context.response`（Node.js 的响应）自己写出响应。动作发出响应头之后，适配器既不写出它的结果，也不写出它的错误。客户端在收到响应之前离开时，`this.signal` 会被中止，并且什么都不会写出。
+
+## 6. 错误
+
+错误以一个状态码和 `{errno, errMsg}` 响应：
+
+- 状态码取错误本身及其原因（`cause`）中第一个客户端错误（4xx）的 `statusCode` 或 `status`；没有时，取错误自己在 400 到 599 之间的状态码；否则为 500；
+- `errno` 和 `errMsg` 来自错误本身：`errno` 取它的 `errno`，没有时取 `code`，再没有时为 `E_UNKNOWN`；`errMsg` 取它的 `errMsg`，没有时取 `message`。所以 `new Error('Lookup failed', {cause: notFound})` 以其原因的 404 响应，内容是 `{"errno": "E_UNKNOWN", "errMsg": "Lookup failed"}`。
+
+| 状态码 | `errno` | 什么时候 |
+|---|---|---|
+| 400 | `E_INVALID_VALUE` | DTO 拒绝了输入 |
+| 400 | `E_UNKNOWN`（Express）、`FST_ERR_CTP_INVALID_JSON_BODY`（Fastify） | 请求体的 JSON 格式错误 |
+| 403 | `E_ACCESS_DENY` | 访问控制拒绝了请求（见 [Middlewares](Middlewares.md)） |
+| 404 | `E_ROUTE_NOT_FOUND` | 没有动作对应这个路由和方法 |
+| 413 | `E_UNKNOWN`（Express）、`FST_ERR_CTP_BODY_TOO_LARGE`（Fastify） | 请求体超过上限 |
+| 415 | `FST_ERR_CTP_INVALID_MEDIA_TYPE` | Fastify 不解析这种类型的请求体 |
+| 503 | `E_ENTRYPOINT_STOPPED` | 应用正在停止 |
+| 500 | 错误自己的 | 其他所有错误 |
+
+应用自己的异常可以给出自己的 `errno` 和 `statusCode`，比如第 1 节的 `OrderNotFoundException`。
+
+**封套。** `jsonEnvelope()`（Express）和 `fastifyJSONEnvelope()`（Fastify）把每个响应包装成 `{errno, errMsg, data}`：
+
+```typescript
+import {expressHTTPEntrypoint, jsonEnvelope} from 'lakutata/adapter/express'
+
+export const http = expressHTTPEntrypoint({
+    port: 8080,
+    //{"errno": null, "errMsg": null, "data": {...}, "timestamp": 1792209357257}
+    respond: jsonEnvelope({actionErrorStatus: 200, extra: (): Record<string, unknown> => ({timestamp: Date.now()})})
+})
+```
+
+- 结果是 `{errno: null, errMsg: null, data}`；没有数据时，状态码为 200，`data` 为 `null`。
+- 错误是 `{errno, errMsg, data: null}`，使用错误的状态码。`errorStatus` 设置所有错误的状态码，比如对从封套中读取错误的客户端设为 200。`actionErrorStatus` 只设置动作的错误（校验、访问控制、动作抛出的异常）的状态码：找不到路由，以及 Web 框架中间件的错误，仍然使用它们自己的状态码。
+- `extra(request)` 给每个响应添加字段，排在 `errno`、`errMsg` 和 `data` 之后，不会覆盖这三个字段。
+
+**自定义响应器**是一个有两个方法的对象，交给 `respond` 选项：`success(response, data, request)` 和 `error(response, error, request, origin)`。请求已经到达动作时，`origin` 是 `'action'`；在此之前就失败时（Web 框架的中间件、找不到路由），`origin` 是 `'request'`。适配器子路径中的 `statusOfError()` 和 `describeError()` 按上面的规则计算状态码和 `{errno, errMsg}`。文件和事件流不经过响应器。
+
+## 7. Web 框架的功能
+
+`before` 钩子在添加动作的路由之前收到 Express 应用或 Fastify 实例。它添加的中间件、插件和路由排在前面：它自己的路由优先于路径相同的动作。它的第二个参数提供：
+
+| 属性 | 是什么 |
+|---|---|
+| `module` | 入口所在的模块，用来获取对象：`await module.getObject('db')` |
+| `server` | HTTP 服务器，此时还没有开始监听：可以把 WebSocket 服务器挂到它上面 |
+| `routes` | 动作的路由，以及每个路由的方法 |
+| `actionPrefixes`、`isActionPath(path)` | 动作路由的第一段，以及某个路径是否在它们之下 |
+
+`before` 失败会让应用启动失败。使用 Express 时，请求体解析器在 `before` 之后才添加：`before` 中的中间件看不到解析后的请求体。
+
+```typescript
+import compression from 'compression'
+import cors from 'cors'
+import {expressHTTPEntrypoint} from 'lakutata/adapter/express'
+import type {Express, Request, Response} from 'express'
+
+export const http = expressHTTPEntrypoint({
+    port: 8080,
+    before: (app: Express): void => {
+        //在同一台机器上的反向代理之后：request.ip 和 request.protocol 取自它的 X-Forwarded-* 请求头
+        app.set('trust proxy', 'loopback')
+        //响应浏览器的预检请求，并给响应加上 CORS 响应头
+        app.use(cors({origin: 'https://app.example.com'}))
+        app.use(compression())
+        app.get('/health', (_request: Request, response: Response): void => void response.send('ok'))
+    }
+})
+```
+
+使用 Fastify 时，在 `async` 钩子中注册插件（`await app.register(fastifyCors, {origin: …})`，`fastifyCors` 来自 `@fastify/cors`），并用 `fastify: {trustProxy: true}` 信任代理。
+
+**HTTPS。** 适配器只提供 HTTP。要提供 HTTPS，请在应用前面放一个反向代理（nginx、Caddy、负载均衡器），并像上面那样信任它。
+
+### 上传
+
+适配器不解析 `multipart/form-data`。使用 Express 时，在 `before` 中给这个路由加上 `multer` 之类的解析器，再把它解析出的文件放进输入：
+
+```typescript
+import multer from 'multer'
+import {DTO} from 'lakutata'
+import {Controller} from 'lakutata/com/entrypoint'
+import {POST} from 'lakutata/decorator/ctrl'
+import {Expect} from 'lakutata/decorator/dto'
+import {expressHTTPEntrypoint} from 'lakutata/adapter/express'
+import type {Express, Request} from 'express'
+
+class AvatarDTO extends DTO {
+    @Expect(DTO.String().required())
+    public user: string
+
+    //multer 的文件：{originalname, mimetype, size, buffer…}
+    @Expect(DTO.Object().required())
+    public file: Express.Multer.File
+}
+
+class AvatarController extends Controller {
+    @POST('/avatars', AvatarDTO)
+    public async upload(input: AvatarDTO): Promise<{ name: string, size: number }> {
+        return {name: input.file.originalname, size: input.file.buffer.length}
+    }
+}
+
+const upload: multer.Multer = multer({storage: multer.memoryStorage(), limits: {fileSize: 5 * 1024 * 1024}})
+
+export const http = expressHTTPEntrypoint({
+    port: 8080,
+    before: (app: Express): void => {
+        //先解析 POST /avatars 的表单，请求再继续交给动作
+        app.post('/avatars', upload.single('file'))
+    },
+    input: (request: Request): Record<string, unknown> => ({...request.query, ...request.body, file: request.file})
+})
+```
+
+multer 的错误（比如文件超过上限，`LIMIT_FILE_SIZE`）没有状态码：它们以 500 响应。
+
+使用 Fastify 时，在 `before` 中以 `attachFieldsToBody: 'keyValues'` 注册 `@fastify/multipart`：表单的字段和文件就成为请求体的属性，也就进入了输入。文件是一个 `Buffer`（用 `DTO.Binary()` 声明），不带文件名；超过上限的文件以 413 拒绝。
+
+### Web 界面
+
+`fallback` 响应动作路径之外的请求（见上文的 `isActionPath()`）。使用 Express 时，`staticUI()` 提供一个构建好的单页应用，比如 Vite 构建出的 `dist` 目录：
+
+```typescript
+import {expressHTTPEntrypoint, staticUI} from 'lakutata/adapter/express'
+
+export const http = expressHTTPEntrypoint({
+    port: 8080,
+    fallback: staticUI('./ui/dist')
+})
+```
+
+- 目录中的文件按原样发送。文件名中带有内容哈希的文件（`index-B2x9fQ1a.js`）由浏览器缓存一年（`assetsMaxAge`）；其他文件在每次请求时重新验证。
+- 请求页面的 `GET` 请求（接受 HTML，路径没有扩展名）如果没有对应的文件，就以应用的 `index.html` 响应，由应用的路由处理这个路径。`spa: false` 关闭这个行为，`index` 可以指定另一个文件。
+- 其他没有对应文件的请求，比如缺失的脚本，以 404 响应。
+- 动作路由之下的路径（`/api/…`）永远不会交给 `fallback`：这些路径上没有对应动作的请求以 404 响应。
+
+使用 Fastify 时，`fallback` 是你自己编写的处理函数 `(request, reply) => …`，它会收到动作路径之外的所有请求。
+
+## 8. 从 lakutata 2.x 迁移
+
+2.x 的 HTTP 入口函数（`buildHTTPEntrypoint`）仍然可以使用：它在入口的启动阶段被调用（此时它获取的对象，比如注入了入口的鉴权组件，都可以正常获取），并且会被等待，所以应用在它的服务器开始监听之后才算启动完成。迁移到 `expressHTTPEntrypoint` 时：
+
+- 应用自己的中间件和路由（CORS、压缩、健康检查、鉴权、Web 界面）放进 `before` 钩子，钩子里用 `module.getObject()` 获取对象；请求体解析器用 `body` 选项（`{limit: '100mb'}`）；服务器的 `keepAliveTimeout` 和 `headersTimeout` 用 `server` 选项；
+- 从请求构造的输入（查询参数、请求体、会话中的值）用 `input` 选项；
+- `{errno, errMsg, data}` 封套用 `jsonEnvelope()`。2.x 的应用通常对动作的错误返回 200，而对 Express 中间件的错误（`next(error)`，比如鉴权的 401）使用错误自己的状态码：`jsonEnvelope({actionErrorStatus: 200})` 的行为与此相同。如果用 `errorStatus: 200`，401 也会变成 200，遇到 401 就跳转到登录页的客户端就会失效；
+- 应用封套中的其他字段（`timestamp`、`nonce`、请求 ID）用 `extra` 选项给出，它在每次响应时调用，结果和错误都一样。不需要为了保留这些字段而自己编写响应器。
+
+```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()})})
+    })
+})
+```
+
+使用 Fastify 时，`fastifyJSONEnvelope()` 接受同样的选项，鉴权写成 Fastify 的钩子。

package/doc/zh/HelperFunctions.md

@@ -118,7 +118,7 @@ console.log(UUID.validate(UUID.v4()))
 |---|---|
 | `delay(ms)` | 等待指定的毫秒数 |
 | `gracefulExit` | 执行完清理函数后退出进程 |
-| `pathExists(path)`、`isPath(text)` | 文件或目录是否存在；字符串是否是路径的写法 |
+| `pathExists(path)`、`isPath(text)` | 文件或目录是否存在；字符串看起来是否像路径 |
 | `Glob(patterns, options?)`、`GlobSync`、`isGlobString` | 匹配 glob 模式的文件；字符串是否是 glob 模式 |
 | `isPromise`、`isPromiseLike`、`isAbortError` | 值是否是 Promise 或 thenable；错误是否是 Node.js 的中止错误 |
 | `isSymbol`、`isNativeFunction`、`isHTML`、`isXML` | 类型判断 |
@@ -137,4 +137,4 @@ console.log(Statistics.median(latencies), Statistics.quantile(latencies, 0.9))
 //13.5 90
 ```
 
-类型判断函数（`Is*`）不会抛出异常，而是返回 `false`；其他函数抛出标准的 JavaScript 错误（`RangeError`、`TypeError`），`templating()` 还会抛出 `MissingValueError`。
+类型判断函数（`is…`）不会抛出异常，而是返回 `false`；其他函数抛出标准的 JavaScript 错误（`RangeError`、`TypeError`），`templating()` 还会抛出 `MissingValueError`。

package/doc/zh/I18n.md

@@ -1,6 +1,6 @@
 # 国际化（i18n）
 
-`lakutata/com/i18n`（`@lakutata/i18n` 包）按**键名**管理各语言的消息：代码里写键名，每种语言在自己的文件里给出这个键的句子。消息使用 [ICU MessageFormat](https://unicode-org.github.io/icu/userguide/format_parse/messages/) 的语法，数字、货币、日期和复数由 Node.js 内置的 `Intl` 按语言格式化，不依赖第三方库。
+`lakutata/com/i18n`（`@lakutata/i18n` 包）按**键名**管理各语言的消息：代码里写键名，每种语言在自己的文件里给出这个键对应的文字。消息使用 [ICU MessageFormat](https://unicode-org.github.io/icu/userguide/format_parse/messages/) 的语法，数字、货币、日期和复数由 Node.js 内置的 `Intl` 按语言格式化，不依赖第三方库。
 
 ## 翻译文件
 
@@ -23,7 +23,7 @@ locales/
 
 JSON 的嵌套就是键名的层级：上面的键是 `order.count` 和 `order.created`。键名的每一段都不能包含 `.`。
 
-也可以一种语言一个目录，目录里的文件名（和子目录名）作为键名的前缀：
+一种语言也可以是一个目录，目录里的文件名（和子目录名）作为键名的前缀：
 
 ```
 locales/
@@ -82,7 +82,7 @@ const i18n = buildI18nOptions({
 | `defaultLocale` | 默认语言，默认 `en` |
 | `fallback` | 某种语言缺少消息时，接着去哪些语言里找（`{'zh-TW': 'zh-CN'}`，或一个列表） |
 | `messages` | 在代码里直接给出的消息（按语言），在目录之后加载，同名的键会覆盖；只用它时不需要 `directory` |
-| `missing` | 缺少消息或参数时：`'throw'` 抛出异常；`'key'` 返回键名（参数原样保留为 `{name}`）并发出一次警告。默认抛出，`NODE_ENV=production` 时返回键名 |
+| `missing` | 缺少消息或参数时怎么办：`'throw'` 抛出异常；`'key'` 返回键名（缺少的参数原样保留为 `{name}`），第一次出现时发出警告。默认 `'throw'`，`NODE_ENV=production` 时默认 `'key'` |
 | `currency` | 消息和参数都没有指定货币时使用的货币（ISO 4217） |
 | `timeZone` | 日期和时间的时区（IANA） |
 | `validationMessages` | 是否注册支持的语言的内置校验消息，默认 `true`（见“校验错误的翻译”） |
@@ -106,7 +106,7 @@ class OrderService extends Provider {
 
 | 方法 | 说明 |
 |---|---|
-| `t(key, params?, locale?)` | 某种语言下的消息，用参数格式化；不传语言时使用默认语言 |
+| `t(key, params?, locale?)` | 某个键在某种语言下的消息，用参数格式化；不传语言时使用默认语言 |
 | `has(key, locale?)` | 某种语言（或它回退到的语言）是否有这个键 |
 | `format(message, params?, locale?)` | 格式化一条不在翻译文件里的 ICU 消息 |
 | `translator(locale)` | 得到绑定某种语言的翻译器（`ITranslator`），之后不用每次都传语言 |
@@ -114,7 +114,7 @@ class OrderService extends Provider {
 | `addMessages(locale, messages)` | 运行时添加某种语言的消息，同名的键会覆盖 |
 | `getLocales()`、`getDefaultLocale()`、`getKeys(locale)`、`getTimeZone()` | 支持的语言、默认语言、某种语言自己的键、时区 |
 
-`t()`、`has()`、`format()` 和 `translator()` 不做语言协商：不支持的语言按原样查找，然后回退。`addMessages()` 返回一个 Promise，在新语言的校验消息注册完成后完成（消息本身在它返回后即可通过 `t()` 取得）。
+`t()`、`has()`、`format()` 和 `translator()` 不做语言协商：不支持的语言按原样查找，然后回退。`addMessages()` 返回一个 Promise，新语言的校验消息注册完成后它才完成；而新消息本身在 `addMessages()` 返回后就能通过 `t()` 取得。
 
 ### 按请求的语言回复
 
@@ -157,7 +157,7 @@ Application.run(() => ({
 }))
 ```
 
-请求要的语言按以下顺序读取，再和支持的语言协商（见下文），都不支持时用默认语言：
+请求所要的语言按下表的顺序读取，再和支持的语言协商（见“语言的协商与回退”），都不支持时用默认语言：
 
 | 入口 | 来源（优先的在前） |
 |---|---|
@@ -189,7 +189,7 @@ Application.run(() => ({
   }
   ```
 
-- 没有配置 `I18nMiddleware` 时使用 `Translator` 会抛出 `I18nTranslatorException`。
+- 没有配置 `I18nMiddleware` 时，调用 `Translator` 的方法会抛出 `I18nTranslatorException`。
 - 翻译器（`Translator` 和 `translator(locale)` 得到的 `ITranslator`）有 `locale`、`t(key, params)`、`has(key)`、`format(message, params)`、`number(value, options)` 和 `date(value, options)`。
 - 自己处理语言时，可以用 `parseAcceptLanguage(header)` 解析 `Accept-Language`，用 `environmentLocales()` 读取环境变量里的语言（`zh_CN.UTF-8` 会转换为 `zh-CN`），再交给 `negotiate()`。
 - 不在请求里的地方（定时任务、单例组件），用组件的 `t(key, params, locale)` 或 `translator(locale)`。
@@ -222,7 +222,7 @@ Application.run(() => ({
         i18n: buildI18nOptions({messages: {'zh-CN': zhCN}}),
         entrypoint: buildEntrypoints({
             controllers: [GreetController],
-            //命令执行时，Controller 注入的 Translator 也使用同一种语言
+            //执行命令的 Controller 注入的 Translator 也使用同一种语言
             middlewares: [I18nMiddleware],
             //TOOL_LANG=zh-CN tool --help，或 LANG=zh_CN.UTF-8
             cli: commanderCLIEntrypoint({bin: 'tool', translate: commanderTranslator({environment: 'TOOL_LANG'})})
@@ -251,22 +251,22 @@ Application.run(() => ({
 - 键名（默认前缀 `cli.`，可用 `prefix` 选项修改）：
   - 程序：`description`；命令：`commands.<命令>.description`、`commands.<命令>.arguments.<参数>`、`commands.<命令>.options.<属性>`；
   - 帮助：`help.usage`、`help.arguments`、`help.options`、`help.commands`、`help.helpOption`、`help.helpCommand`、`help.versionOption`；
-  - 提示：`help.default`（`default: {value}`）、`help.choices`（`choices: {choices}`）、`help.hints`（` ({hints})`，提示在说明后的格式）、`help.separator`（`, `）、`help.negate`（`Turn off {flag}`）；
+  - 提示：`help.default`（`default: {value}`）、`help.choices`（`choices: {choices}`）、`help.hints`（` ({hints})`，说明后面附加提示的格式）、`help.separator`（`, `）、`help.negate`（`Turn off {flag}`）；
   - 提问：`prompt.json`（`Not a JSON object`）。
 - 没有消息的文字使用代码里的英文原文，所以只需要为其他语言提供消息。
-- 语言在适配器启动时确定一次：依次为 `environment` 选项指定的环境变量、环境（`LANGUAGE`、`LC_ALL`、`LC_MESSAGES`、`LANG`），最后是进程的语言，再与支持的语言协商。
-- 中文、日文、韩文的宽字符按两列计算，帮助的长行在字符之间换行，标点不放在行首。
+- 语言在适配器启动时确定一次：依次读取 `environment` 选项指定的环境变量、`LANGUAGE`、`LC_ALL`、`LC_MESSAGES`、`LANG`，最后是进程的语言，再与支持的语言协商。
+- 中文、日文、韩文的宽字符按两列计算；帮助里的长行可以在这些字符之间换行，并且不会让标点出现在行首。
 - 也可以直接给 `translate` 一个函数：`translate: () => (text) => messages[text.key] ?? text.text`。
 
 ## 校验错误的翻译
 
-配置了 `I18nMiddleware` 时，请求里的校验失败的消息都使用请求的语言：请求参数（`@HTTPAction`、`@CLIAction`、`@ServiceAction` 的 DTO），请求中调用的方法的参数和返回值（`@Accept`、`@Return`），以及代码里直接调用的 `DTO.validate`、`DTO.validateAsync`。
+配置了 `I18nMiddleware` 时，请求里校验失败的消息都使用请求的语言：请求参数（`@HTTPAction`、`@CLIAction`、`@ServiceAction` 的 DTO），请求中调用的方法的参数和返回值（`@Accept`、`@Return`），以及代码里直接调用的 `DTO.validate`、`DTO.validateAsync`。
 
 框架内置了 20 种语言的校验消息，组件启动时为它支持的每种语言注册（只加载用到的语言）：
 
 `en`、`zh-CN`、`zh-TW`、`ja`、`ko`、`fr`、`de`、`es`、`pt-BR`、`it`、`nl`、`pl`、`ru`、`uk`、`tr`、`vi`、`th`、`id`、`hi`、`ar`
 
-支持的语言使用最接近的内置语言：`zh`、`zh-Hans`、`zh-SG` 使用 `zh-CN`，`zh-Hant`、`zh-HK`、`zh-MO` 使用 `zh-TW`，其他语言按语言部分匹配（`pt-PT` 使用 `pt-BR`，`fr-CA` 使用 `fr`）。没有内置消息的语言使用它回退到的语言的，最后是英文。
+支持的语言使用最接近的内置语言：`zh`、`zh-Hans`、`zh-SG` 使用 `zh-CN`，`zh-Hant`、`zh-HK`、`zh-MO` 使用 `zh-TW`，其他语言按语言部分匹配（`pt-PT` 使用 `pt-BR`，`fr-CA` 使用 `fr`）。没有内置消息的语言，使用它回退到的语言的内置消息，最后是英文。
 
 应用可以在翻译里覆盖或补充校验消息：写在 `validation` 下，键是校验的错误码，消息使用校验的模板语法（`{{#label}}`、`{{#limit}}`），不是 ICU：
 
@@ -281,13 +281,13 @@ Application.run(() => ({
 
 - 某种语言的校验消息依次叠加：回退到的语言的内置消息和应用消息，再是它自己的内置消息和应用消息，后面的覆盖前面的。
 - `validationMessages: false` 不注册内置消息，只使用应用的 `validation` 消息。
-- 请求参数先按原来的方式校验；只有校验失败时，才按请求的语言再校验一次，取得该语言的消息。校验通过的请求不受任何影响。
-- 少数消息里有校验引擎填入的英文内容，例如排序方向（`ascending`）、引用错误的原因、自定义断言的消息，这些部分在各语言里仍是英文。
+- 请求参数照常校验；只有校验失败时，才按请求的语言再校验一次，取得这种语言的消息。校验通过的请求不受任何影响。
+- 少数消息里有校验库自己填入的英文内容，例如排序方向（`ascending`）、引用错误的原因、自定义断言的消息，这些部分在各语言里仍是英文。
 - 不使用 i18n 组件时，也可以直接用 `lakutata` 的函数：`loadValidationMessages(language)` 加载某种语言的内置消息，`registerValidationMessages(language, messages)` 注册，之后校验时用 `{errors: {language}}` 选项指定语言，或者用 `runInValidationLanguage(language, fn)` 让一段代码（包括其中的异步调用）里的所有校验都使用该语言。
 
 ## 异常消息的翻译
 
-配置了 `I18nMiddleware` 时，请求中抛出的异常如果在翻译里有对应的消息，它的消息会换成请求的语言。键名是 `errors.<异常的 errno>`，消息用异常的模板参数格式化：
+配置了 `I18nMiddleware` 时，如果请求中抛出的异常在翻译里有对应的消息，它的消息会换成请求的语言。键名是 `errors.<异常的 errno>`，消息用异常的模板参数格式化：
 
 ```typescript
 import {Exception} from 'lakutata'
@@ -305,14 +305,14 @@ throw new OrderNotFoundException('Order {id} not found', {id: 7})
 
 - 中文请求得到 `订单 7 不存在`，英文请求得到原来的 `Order 7 not found`；`errno` 等其他属性不变。
 - 逐个传入的参数（`new XxxException('{0} of {1}', a, b)`）在消息里用 `{0}`、`{1}` 引用。
-- 没有对应消息的异常保持原样；消息无法格式化时（比如缺少参数）也保持原样，并发出一次警告。
+- 在翻译里没有对应消息的异常保持原样；消息无法格式化时（比如缺少参数）也保持原样，并发出警告。
 - 不在请求里的地方，可以用 `exceptionParams(exception)`（来自 `lakutata`）取得异常的参数，自己翻译。
 
 ## 语言的协商与回退
 
-**协商**（`negotiate`）：依次看请求方的每一种语言，先找完全相同的标签，再找只有语言部分的标签（`en-GB` → `en`），再找同一语言的其他地区（`pt-PT` → `pt-BR`，按支持的语言的顺序）；都找不到时使用默认语言。
+**协商**（`negotiate`）：依次尝试请求方的每一种语言，先找完全相同的标签，再找只有语言部分的标签（`en-GB` → `en`），再找同一语言的其他地区（`pt-PT` → `pt-BR`，按支持的语言的顺序）；都找不到时使用默认语言。
 
-**回退**：在某种语言里找不到消息时，依次查找：它在 `fallback` 里配置的语言、去掉最后一段的标签（`zh-Hant-TW` → `zh-Hant` → `zh`）、默认语言。消息总是按**请求的语言**格式化：回退到英文的消息，在德语请求里数字仍然是 `1.000`。
+**回退**：在某种语言里找不到消息时，依次查找：它在 `fallback` 里配置的语言、去掉最后一段的标签（`zh-Hant-TW` → `zh-Hant` → `zh`）、默认语言。消息总是按**请求的语言**格式化：德语请求回退到英文消息时，数字仍然写成 `1.000`。
 
 ## 消息语法
 
@@ -331,7 +331,7 @@ throw new OrderNotFoundException('Order {id} not found', {id: 7})
 
 ## 键名的类型
 
-应用可以声明键名和它们的参数，之后写错键名或漏掉参数时编译就会报错。`lakutata i18n types` 根据默认语言的消息生成这份声明（见下文），也可以手写：
+应用可以声明键名和它们的参数，这样写错键名或漏掉参数时，编译就会报错。`lakutata i18n types` 根据默认语言的消息生成这份声明（见下文），也可以手写：
 
 ```typescript
 //src/i18n.d.ts
@@ -353,18 +353,18 @@ declare module 'lakutata/com/i18n' {
 
 | 命令 | 作用 |
 |---|---|
-| `lakutata i18n check` | 以默认语言（`--default`，默认 `en`）为准检查各语言的消息。错误：ICU 语法错误、默认语言没有的键、默认消息没有的参数、未知的校验错误码或不属于该错误码的变量；警告：缺少的消息（会回退）、没有用到的参数、和默认语言相同（可能还没翻译）。有错误时退出码非 0，`--strict` 时警告也算失败，适合放进 CI |
+| `lakutata i18n check` | 以默认语言（`--default`，默认 `en`）为准检查各语言的消息。错误：ICU 语法错误、默认语言没有的键、默认消息没有的参数、未知的校验错误码或不属于该错误码的变量；警告：缺少的消息（会回退）、没有用到的参数、与默认语言相同的消息（可能还没翻译）。有错误时退出码非 0，加上 `--strict` 时警告也算失败，适合放进 CI |
 | `lakutata i18n types` | 根据默认语言的消息生成键名和参数的类型声明（`--out`，默认 `src/i18n.d.ts`）；应用从 `@lakutata/i18n` 引入时加 `--module @lakutata/i18n` |
-| `lakutata i18n add <语言>` | 以默认语言的消息为模板新建一种语言（按默认语言的布局建文件或目录，不复制 `validation` 部分，新语言使用自己的内置校验消息），之后翻译它们 |
+| `lakutata i18n add <语言>` | 以默认语言的消息为模板新建一种语言，供之后翻译（按默认语言的布局建文件或目录，不复制 `validation` 部分，新语言使用自己的内置校验消息） |
 
-这些检查也可以在代码里使用：`loadCatalogs(directories)`、`checkCatalogs(catalogs, defaultLocale)`、`generateMessageTypes(catalogs, defaultLocale)`。
+这些检查也可以作为函数在代码里调用：`loadCatalogs(directories)`、`checkCatalogs(catalogs, defaultLocale)`、`generateMessageTypes(catalogs, defaultLocale)`。
 
 ## 异常
 
-| 异常 | 时机 |
+| 异常 | 什么时候 |
 |---|---|
 | `I18nCatalogException` | 翻译文件或配置无效：JSON 有误、文件名不是语言标签、目录不存在、别名无法解析 |
-| `I18nMessageSyntaxException` | 消息的语法错误 |
+| `I18nMessageSyntaxException` | 消息有语法错误 |
 | `I18nMissingKeyException` | 找不到键（`missing: 'throw'`） |
 | `I18nMissingParameterException` | 缺少参数（`missing: 'throw'`），或货币类消息没有可用的货币 |
-| `I18nTranslatorException` | 没有配置 `I18nMiddleware` 时，或在请求之外使用 `Translator` |
+| `I18nTranslatorException` | 没有配置 `I18nMiddleware`，或者在请求之外使用 `Translator` |