@tyno/tyno 2.1.3

package/README-zh.md

@@ -0,0 +1,572 @@
+# tyno
+
+零外部依赖的轻量级 Node.js HTTP 框架，TypeScript 编写，原生 `http` 模块。融合 Koa 洋葱模型与 ThinkPHP/Laravel 请求取值风格。
+
+```ts
+import { Tyno } from '@tyno/tyno'
+
+const app = new Tyno()
+app.use((req) => `Hello ${req.query('name') || 'World'}`)
+app.listen(3000)
+```
+
+```ts
+import { Tyno } from '@tyno/tyno'
+import { Router } from '@tyno/tyno/router'
+
+const app = new Tyno()
+const r = new Router()
+r.get('/users/:id', (req) => ({ id: req.params.id }))
+app.use(r.routes()).listen(3000)
+```
+
+## 特性
+
+- **洋葱模型中间件**：返回值自动归一化，异步压缩
+- **前缀树路由**：静态/参数 `:id`/正则 `:id(\d+)`/通配符 `*`，HEAD，分组 `group()`，`fallback()`
+- **请求取值**：`query()` / `post()` / `param()` / `input()`
+- **文件上传**：流式 multipart 状态机解析，buffer/磁盘双模
+- **Response 构建**：静态工厂 `json/text/empty/redirect/image`，链式 `set/type/setStatus/setCookie/attachment`
+- **全局门面**：`req/res`（Request/Response 别名）/ `request`（读入站）/ `Cache`（缓存）
+- **错误体系**：`HttpError` / `RuntimeError` + 错误中间件 + Symbol 标记
+- **事件系统**：`request` / `response` / `response:sent` / `error` / `ready`
+- **缓存**：内存/文件/Redis，`get/set/has/delete/clear/remember`
+- **内置中间件**：CORS、异步压缩、Range 静态文件、请求 ID
+- **测试**：`app.inject()` 无需启动服务器
+
+## 模块结构
+
+```ts
+// 主入口
+import { Tyno, Response, res, Request, req } from '@tyno/tyno'
+
+// 门面
+import { request, Cache } from '@tyno/tyno/facade'
+
+// 中间件
+import { cors, compress, serveStatic, requestId } from '@tyno/tyno/middleware'
+
+// 路由
+import { Router } from '@tyno/tyno/router'
+
+// 错误
+import { HttpError, NotFound, RuntimeError } from '@tyno/tyno/errors'
+
+// 缓存
+import { CacheManager, MemoryDriver } from '@tyno/tyno/cache'
+```
+
+---
+
+## 核心模块
+
+### 中间件
+
+```ts
+// 洋葱模型
+app.use(async (req, next) => {
+    const start = Date.now()
+    const res = await next()
+    console.log(`${req.method} ${req.path} ${res.status} ${Date.now() - start}ms`)
+    return res
+})
+
+// 终端中间件（不接收 next）
+app.use((req) => ({ hello: 'world' }))
+
+// 错误中间件（3 个参数或 Symbol 标记）
+app.use(async (err, req, next) => {
+    return Response.json({ error: err.message }, err.status || 500)
+})
+
+// 批量注册（数组），依次执行
+app.use([logger, auth, compress])
+app.middleware([cors, requestId])   // middleware 是 use 的别名
+
+// Router 同样支持
+const r = new Router()
+r.middleware([auth, adminCheck])
+```
+
+**返回值自动归一整表**：
+
+| 返回类型 | 自动转换 | Content-Type | 状态码 |
+|---------|---------|-------------|--------|
+| `Response` 实例 | 原样使用 | 已有 | 已有 |
+| `string` | `Response.text(str)` | `text/plain; charset=utf-8` | 200 |
+| `Buffer` | `Response.text(buf)` | `text/plain; charset=utf-8` | 200 |
+| `object`（普通对象） | `Response.json(obj)` | `application/json; charset=utf-8` | 200 |
+| `number` / `boolean` | `Response.text(String(v))` | `text/plain; charset=utf-8` | 200 |
+| `ReadableStream`（有 `pipe`） | 流式输出 | 无（透传） | 200 |
+| `AsyncIterable` / `Generator` | SSE 流式输出 | `text/event-stream` | 200 |
+| `null` / `undefined` | `Response.empty()` | 无 | 204 |
+| `Image Buffer`（手动） | `Response.image(buf, 'png')` | `image/png` | 200 |
+
+> 返回图片需显式调用 `Response.image()`，框架不会自动区分 Buffer 是文本还是图片。
+
+### Request
+
+Proxy 封装原生 `IncomingMessage`，内置属性只读，自定义属性写入 `DATA_KEY`。
+
+```ts
+// 基本信息
+req.method          // GET / POST
+req.path            // 不含 query string
+req.url             // 含 query string
+req.ip              // 优先 X-Forwarded-For
+req.protocol        // http / https
+req.secure          // 是否 HTTPS
+req.fullUrl         // protocol://host/url
+req.httpVersion     // 1.1 / 2.0
+req.host            // 含端口
+req.hostname        // 不含端口
+req.userAgent       // User-Agent
+req.isAjax()        // X-Requested-With 判断
+req.wantsJSON()     // Accept 头判断
+
+// Query
+req.query()             // → { id: '1', name: 'Alice' }
+req.query('id')         // → '1'
+req.query('x', 'def')   // → 'def' 带默认值
+req.get('id')           // 别名
+req.getQuery('id')      // 别名
+
+// Body（惰性解析，结果缓存）
+await req.body()                 // JSON / urlencoded / text 自动识别
+await req.post('title')          // 取 POST 字段
+await req.param('id')            // GET 优先，fallback POST
+await req.input('id', 0, parseInt) // 带 filter
+
+// Header / Cookie
+req.header('authorization')      // 大小写不敏感
+req.cookies                      // 含 URL 解码
+req.getCookie('sessionId')
+
+// 文件上传（流式 multipart）
+await req.files()               // → { fields, files }
+await req.file('avatar')        // → 单个 UploadedFile | null
+// UploadedFile: { fieldname, filename, mimetype, filepath, size, buffer? }
+```
+
+**Body 配置**：
+
+```ts
+const app = new Tyno({
+    body: {
+        limit: '2mb',              // JSON/urlencoded/text 大小限制
+        uploadLimit: '20mb',       // 文件上传总大小限制
+        uploadBufferLimit: '512kb',// 文件内存阈值，超过流式写磁盘
+        uploadDir: '/tmp',
+        keepExtensions: true
+    }
+})
+```
+
+### Response
+
+实例构造 + 静态工厂 + 静态门面（预设 header/cookie），三位一体。
+
+**别名**：`Response`（类名）= `response` = `res`
+
+```ts
+import { Response, res } from '@tyno/tyno'
+
+// —— 静态工厂 ——
+Response.json({ ok: true })          // 200  application/json; charset=utf-8
+Response.json(data, 201)             // 自定义状态码
+Response.text('hello')               // 200  text/plain; charset=utf-8
+Response.empty()                     // 204  无 Content-Type
+Response.empty(201)                  // 201
+Response.redirect('/new')            // 302  Location: /new
+Response.redirect('/new', 301)       // 301
+Response.image(buf)                  // 200  image/png
+Response.image(buf, 'jpeg')          // 200  image/jpeg
+Response.image(buf, 'image/webp')    // 200  image/webp
+Response.image(buf, 'svg', 201)      // 201  image/svg+xml
+
+// —— 实例构造 ——
+new Response(200, { 'X-Custom': 'yes' }, 'body')
+new Response(404, {}, 'Not Found')
+
+// —— 链式修改 ——
+Response.json({ ok: true })
+    .set('X-Request-Id', 'abc')
+    .type('json')
+    .setStatus(201)
+    .setCookie('token', 'xxx', { httpOnly: true, maxAge: 3600, sameSite: 'Lax' })
+    .clearCookie('old_session')
+    .attachment('report.txt')     // Content-Disposition: attachment
+
+// —— 静态门面（预设，final 优先） ——
+app.use(async (req, next) => {
+    Response.header('X-Powered-By', 'tyno')
+    Response.setCookie('track', 'abc', { httpOnly: true })
+    return next()
+})
+```
+
+**Response 输出类型完整参考**：
+
+| 工厂方法 | Content-Type | 默认状态码 | body 类型 |
+|---------|-------------|-----------|----------|
+| `json(data, status?)` | `application/json; charset=utf-8` | 200 | `string` (JSON) |
+| `text(data, status?)` | `text/plain; charset=utf-8` | 200 | `string` |
+| `empty(status?)` | 无 | 204 | `null` |
+| `redirect(url, status?)` | 无 (`Location` 头) | 302 | `null` |
+| `image(data, type?, status?)` | `image/*` | 200 | `Buffer \| string` |
+| `new Response(s, h, b)` | 手动指定 | 手动指定 | `ResponseBody` |
+
+| `ResponseBody` 类型 | 输出行为 |
+|-------------------|---------|
+| `string` | `nodeRes.end(body)` |
+| `Buffer` | `nodeRes.end(body)` |
+| `NodeJS.ReadableStream` | `body.pipe(nodeRes)` |
+| `AsyncIterable` | SSE 流式逐块写入 |
+| `null` | `nodeRes.end()` |
+
+### 路由
+
+前缀树实现，支持参数约束、通配符、路由分组和 fallback。
+
+```ts
+import { Router } from '@tyno/tyno/router'
+
+const r = new Router({ prefix: '/api' })
+
+// 路由级中间件（支持单个或数组，use / middleware 等价）
+r.use(async (req, next) => {
+    req.user = { id: 1 }
+    return next()
+})
+r.middleware([auth, adminCheck])  // 数组批量注册
+})
+
+// 方法注册
+r.get('/users/:id(\\d+)', (req) => ({ id: req.params.id }))
+r.head('/health', () => Response.empty(200))
+r.post('/users', async (req) => ({ created: await req.body() }))
+r.put('/users/:id', async (req) => Response.empty(204))
+r.delete('/users/:id', () => Response.empty(204))
+r.patch('/users/:id', async (req) => 'ok')
+r.all('/any', (req) => `${req.method} matched`)
+r.get('/*', (req) => ({ wild: req.params['*'] }))
+
+// 路由分组
+r.group('/admin', (admin) => {
+    admin.get('/dashboard', () => 'Admin Panel')
+    admin.get('/users', () => 'User List')
+    // 等价于 /api/admin/dashboard、/api/admin/users
+})
+
+// fallback：所有路由都不匹配时调用
+r.fallback((req) => Response.json({ error: 'Not Found' }, 404))
+
+app.use(r.routes())
+```
+
+**路径模式**：
+
+| 模式 | 含义 | 匹配 |
+|------|------|------|
+| `users` | 静态段 | `/api/users` |
+| `:id` | 参数段 | `/api/123` |
+| `:id(\d+)` | 正则约束 | `/api/123` |
+| `*` | 通配符 | `/api/a/b/c` |
+
+优先级：**静态 > 参数 > 通配符**。支持 `get/head/post/put/delete/patch/all`。
+
+---
+
+## 错误 & 事件
+
+### 错误处理
+
+```ts
+import { HttpError, NotFound, RuntimeError, isRuntimeError } from '@tyno/tyno/errors'
+
+// HttpError：4xx 默认 expose，5xx 默认隐藏
+throw new NotFound('资源不存在')
+throw new HttpError(401, '请先登录')
+
+// RuntimeError：默认 500 不暴露，带 cause 链
+throw new RuntimeError('数据库连接失败', {
+    code: 'DB_FAIL',
+    cause: new Error('ECONNREFUSED')
+})
+```
+
+**快捷类**：`BadRequest`、`Unauthorized`、`Forbidden`、`NotFound`、`Conflict`、`PayloadTooLarge`、`TooManyRequests`、`InternalServerError`。
+
+**错误中间件**（参数 >= 3 或 `IS_ERROR_MIDDLEWARE` 标记，按注册顺序串联）：
+
+```ts
+import { asErrorMiddleware } from '@tyno/tyno'
+
+app.use(async (err, req, next) => {
+    if (isRuntimeError(err)) {
+        return Response.json({ error: '服务不可用', code: err.code }, 500)
+    }
+    return Response.json({ error: err.message }, err.status || 500)
+})
+```
+
+### 事件系统
+
+Application 继承 EventEmitter，完整生命周期事件：
+
+| 事件 | 触发时机 | 参数 |
+|------|---------|------|
+| `request` | 请求到达，compose 之前，`AsyncLocalStorage` 就绪 | `(req)` |
+| `response` | compose 完成，响应发送**前** | `(req, res)` |
+| `response:sent` | 响应发送**后** | `(req, res)` |
+| `error` | 异常发生（有监听器时触发） | `(err, req)` |
+| `ready` | 服务启动成功 | `()` |
+
+```ts
+import { Tyno } from '@tyno/tyno'
+const app = new Tyno({ debug: true })
+
+app.on('request', (req) => {
+    console.log(`→ ${req.method} ${req.path}`)
+})
+
+app.on('response', (req, res) => {
+    // 响应发送前：可记录日志
+    console.log(`← ${req.path} ${res.status}`)
+})
+
+app.on('response:sent', (req, res) => {
+    // 响应已发送：可记录耗时、清理资源
+    console.log(`✓ ${req.path} ${res.status} done`)
+})
+
+app.on('error', (err, req) => {
+    // 需注册监听器才触发，遵循 Node.js EventEmitter 语义
+    logger.error({ err, path: req.path })
+})
+
+app.on('ready', () => {
+    console.log('Server ready')
+})
+```
+
+---
+
+## 内置中间件
+
+```ts
+import { cors, compress, serveStatic, requestId } from '@tyno/tyno/middleware'
+
+// CORS
+app.use(cors())
+app.use(cors({ origin: ['https://a.com'], credentials: true, maxAge: 86400 }))
+
+// 异步压缩（gzip/deflate），支持流式响应，跳过图片/视频
+app.use(compress())
+app.use(compress({ threshold: 2048, level: 6 }))
+
+// 静态文件：ETag/304、Range/206、路径穿越防护
+app.use(serveStatic('./public', { prefix: '/static', maxAge: 3600 }))
+
+// 请求 ID：自动注入 req.requestId，写入响应头
+app.use(requestId())
+app.use(requestId({ readFromHeader: false }))
+
+// 开发错误页
+new Tyno({ debug: true })  // 自动附加，显示堆栈和 cause，支持 JSON/HTML
+```
+
+---
+
+## 缓存
+
+内存 / 文件 / Redis 三种驱动，统一 `get/set/has/delete/clear/remember` API。
+
+**别名**：`Cache`（首字母大写）= `cache`（小写）
+
+```ts
+import { Cache } from '@tyno/tyno/facade'
+
+const app = new Tyno({ cache: { driver: 'memory', prefix: 'my:', ttl: 3600 } })
+
+// 通过 app
+await app.cache().set('user:1', { name: 'Alice' }, 60)
+const user = await app.cache().get('user:1')
+
+// remember：不存在时调用 factory
+const config = await app.cache().remember('config', 3600, loadConfig)
+
+// 全局门面（中间件内）
+app.use(async () => {
+    await Cache.set('key', 'value')
+    return Response.json({ ok: true })
+})
+```
+
+**文件驱动**：`{ driver: 'file', file: { path: './storage/cache' } }`
+
+**Redis 驱动**：需 `npm install redis`，`{ driver: 'redis', redis: { host, port } }`
+
+---
+
+## 其他
+
+### 初始化器
+
+```ts
+app.initialize(async (app) => { await db.connect() })
+app.listen(4567)  // 自动先执行
+```
+
+### HTTPS
+
+```ts
+app.listen({ port: 443, tls: { key, cert } })
+```
+
+### 测试
+
+```ts
+const res = await app.inject({ method: 'GET', url: '/?name=alice' })
+res.status   // 200
+res.json()   // { hello: 'alice' }
+```
+
+### SSE
+
+```ts
+async function* gen() { yield 'chunk1'; yield 'chunk2' }
+return gen()
+```
+
+---
+
+## API 速览
+
+### Application
+
+| 方法 | 说明 |
+|------|------|
+| `new Tyno({ debug?, body?, cache? })` | 创建应用 |
+| `use(fn\|[...fn])` / `middleware(fn\|[...fn])` | 注册中间件，支持数组 |
+| `initialize(fn)` | 注册初始化器 |
+| `listen(port\|opts)` | 启动 HTTP/HTTPS |
+| `close()` | 优雅关闭 |
+| `inject(opts)` | 测试请求 |
+| `cache()` | 缓存实例 |
+| `on/emit/once` | EventEmitter |
+
+### Router
+
+| 方法 | 说明 |
+|------|------|
+| `new Router({ prefix? })` | 创建路由 |
+| `use(fn\|[...fn])` / `middleware(fn\|[...fn])` | 路由级中间件，支持数组 |
+| `get/head/post/put/delete/patch/all(path, ...h)` | 注册路由 |
+| `group(prefix, fn)` | 路由分组 |
+| `fallback(handler)` | 未匹配时的回退处理 |
+| `routes()` | 返回中间件 |
+
+### Request
+
+| 别名 | 导出来源 |
+|------|---------|
+| `Request`（类名）= `req` | `tyno` |
+| `request`（全局门面） | `tyno/facade` |
+
+| 方法 | 说明 |
+|------|------|
+| `query()/query(k)/get(k)` | Query 参数 |
+| `body()/post/param/input` | Body 取值 |
+| `files()/file(name)` | 文件上传 |
+| `header/cookies/getCookie` | 请求头 |
+
+### Response
+
+| 别名 | 导出来源 |
+|------|---------|
+| `Response`（类名）= `response` = `res` | `tyno` |
+
+| 静态工厂 | Content-Type | 状态码 |
+|---------|-------------|--------|
+| `json(data, status?)` | `application/json` | 200 |
+| `text(data, status?)` | `text/plain` | 200 |
+| `empty(status?)` | — | 204 |
+| `redirect(url, status?)` | `Location` 头 | 302 |
+| `image(data, type?, status?)` | `image/*` | 200 |
+
+| 实例/静态方法 | 说明 |
+|-------------|------|
+| `set/setHeader/type/setStatus` | 链式修改 |
+| `setCookie/clearCookie/attachment` | Cookie + 下载 |
+| `get(name)` | 读取响应头 |
+| `static header(name, value)` | 预设响应头（门面） |
+| `static setCookie(name, value, options?)` | 预设 Cookie（门面） |
+
+### 错误类
+
+| 类 | 说明 |
+|----|------|
+| `AppError` | 基类 |
+| `HttpError(status, msg?, props?)` | HTTP 错误 |
+| `RuntimeError(msg, opts?)` | 运行时错误 |
+| `NotFound/Forbidden/...` | 快捷子类 |
+
+### 全局门面
+
+| 导出 | 来源 | 说明 |
+|------|------|------|
+| `req` | `tyno` | Request 类别名 |
+| `res` | `tyno` | Response 类别名 |
+| `request` | `tyno/facade` | 读取当前请求 |
+| `Cache / cache` | `tyno/facade` | 缓存操作 |
+
+---
+
+## 项目结构
+
+```
+tyno/
+├── src/
+│   ├── index.ts                # 主入口
+│   ├── application.ts          # Application (EventEmitter)
+│   ├── compose.ts              # 洋葱模型 + 错误处理
+│   ├── context.ts              # AsyncLocalStorage
+│   ├── types.ts                # 类型定义
+│   ├── response.ts             # Response 类
+│   ├── response/sse.ts         # SSEStream
+│   ├── request/
+│   │   ├── index.ts            # Request 类
+│   │   ├── body-parser.ts      # BodyParser
+│   │   └── multipart-parser.ts # 流式 multipart
+│   ├── router/
+│   │   ├── index.ts            # Router + group + fallback
+│   │   ├── node.ts             # TrieNode
+│   │   └── parse-path.ts       # 路径解析
+│   ├── errors/
+│   │   ├── app-error.ts        # AppError
+│   │   ├── http-error.ts       # HttpError
+│   │   └── runtime-error.ts    # RuntimeError
+│   ├── middlewares/
+│   │   ├── index.ts            # 子路径导出
+│   │   ├── cors.ts             # CORS
+│   │   ├── compress.ts         # 异步压缩
+│   │   ├── static.ts           # 静态文件 + Range
+│   │   ├── request-id.ts       # 请求 ID
+│   │   └── error-page.ts       # 开发错误页
+│   ├── cache/
+│   │   ├── index.ts / manager.ts / types.ts
+│   │   └── drivers/ (memory / file / redis)
+│   ├── facade/                 # 门面子路径导出
+│   ├── request-global.ts       # 全局 request
+│   ├── cache-facade.ts         # 全局 cache
+│   └── mime.ts
+├── example/app.ts
+├── test/functional.test.ts
+├── package.json
+└── tsconfig.json
+```
+
+## License
+
+MIT