@tyno/tyno 2.1.3

package/example/app.ts

@@ -0,0 +1,173 @@
+import { Tyno, Router, Response, NotFound, RuntimeError, cors, requestId, compress, cache, response } from '../src/index.ts';
+import type { TynoRequest, NextFunction } from '../src/index.ts';
+
+// debug + body + cache 配置在构造函数中统一设置
+const app = new Tyno({
+    debug: true,
+    body: { limit: '2mb', uploadLimit: '20mb', keepExtensions: true, uploadBufferLimit: '512kb' },
+    cache: { driver: 'memory', prefix: 'app:', ttl: 60 }
+});
+
+// ==================== 事件系统 ====================
+
+// 请求到达
+app.on('request', (req: TynoRequest) => {
+    console.log(`[event] request: ${req.method} ${req.path}`);
+});
+
+// 响应发送前
+app.on('response', (req: TynoRequest, res: Response) => {
+    console.log(`[event] response: ${res.status} ${req.path}`);
+});
+
+// 异常发生时（有监听器才触发，否则静默处理）
+app.on('error', (err: unknown, req: TynoRequest) => {
+    console.error(`[event] error: ${(err as { message?: string }).message} at ${req.path}`);
+});
+
+// 服务启动成功
+app.on('ready', () => {
+    console.log('[event] ready: server is listening');
+});
+
+// 初始化器：在 listen() 启动服务前自动执行
+app.initialize(async (app) => {
+    console.log('[init] Initializing application...');
+    console.log('[init] Application initialized successfully.');
+});
+
+app.initialize(async () => {
+    console.log('[init] Cache pre-warming...');
+});
+
+// 请求 ID 中间件（自动注入 X-Request-Id）
+app.use(requestId());
+
+// 响应压缩中间件
+app.use(compress());
+
+// CORS
+app.use(cors({ origin: '*' }));
+
+// 全局日志中间件
+app.use(async (req: TynoRequest, next: NextFunction) => {
+    console.log(`--> ${req.method} ${req.path} [${req.requestId}]`);
+    const res = await next();
+    if (res instanceof Response) {
+        console.log(`<-- ${req.method} ${req.path} ${res.status} [${req.requestId}]`);
+    }
+    return res;
+});
+
+// 响应门面：预设 header / cookie，自动合并到最终响应
+app.use(async (req: TynoRequest, next: NextFunction) => {
+    response.header('X-Powered-By', 'tyno');
+    return next();
+});
+
+// 抛出 HttpError / RuntimeError
+app.use(async (req: TynoRequest, next: NextFunction) => {
+    if (req.path === '/error') throw new NotFound('资源不存在');
+    if (req.path === '/db-fail') {
+        throw new RuntimeError('数据库连接失败', { code: 'DB_FAIL', cause: new Error('ECONNREFUSED') });
+    }
+    return next();
+});
+
+// 用户路由（使用 Router 替代子应用挂载）
+const userRouter = new Router({ prefix: '/users' });
+userRouter.use(async (req: TynoRequest, next: NextFunction) => {
+    req.user = { id: 1, name: 'Alice' };
+    return next();
+});
+userRouter.get('/:id(\\d+)', (req: TynoRequest) => ({ id: req.params.id, user: req.user }));
+userRouter.post('/', async (req: TynoRequest) => ({ created: await req.body() }));
+userRouter.get('/*', (req: TynoRequest) => ({ wild: req.params['*'] }));
+app.use(userRouter.routes());
+
+// API 路由（使用 Router 替代子应用挂载）
+const apiRouter = new Router({ prefix: '/api' });
+apiRouter.use(async (req: TynoRequest, next: NextFunction) => {
+    return next();
+});
+apiRouter.get('/status', () => Response.json({ status: 'ok', from: 'api-router' }));
+apiRouter.get('/data', () => Response.json({ items: [1, 2, 3] }));
+app.use(apiRouter.routes());
+
+// 文件上传路由
+app.use(async (req: TynoRequest, next: NextFunction) => {
+    if (req.path === '/upload' && req.method === 'POST') {
+        const result = await req.files();
+        return Response.json({
+            fields: result.fields,
+            files: result.files.map(f => ({
+                name: f.filename, size: f.size, type: f.mimetype, path: f.filepath
+            }))
+        });
+    }
+    return next();
+});
+
+// SSE 流式响应
+app.use(async (req: TynoRequest, next: NextFunction) => {
+    if (req.path === '/stream') {
+        async function* gen() {
+            yield 'first';
+            await new Promise(r => setTimeout(r, 100));
+            yield { chunk: 2, time: Date.now() };
+            yield 'finished';
+        }
+        return gen();
+    }
+    return next();
+});
+
+// 静态文件服务（需要创建 public 目录）
+app.use(async (req: TynoRequest, next: NextFunction) => {
+    if (req.path === '/hello') return 'Hello World!';
+    if (req.path === '/json') return Response.json({ ok: true, framework: 'tyno' });
+    if (req.path === '/cookie-test') {
+        return Response.json({ cookie: req.getCookie('test_cookie') })
+            .setCookie('test_cookie', 'hello world', { httpOnly: true, maxAge: 3600 });
+    }
+    if (req.path === '/query-demo') {
+        return Response.json({
+            all: req.query(),
+            name: req.query('name'),
+            viaGet: req.get('name'),
+            missing: req.get('missing', 'default')
+        });
+    }
+    // 缓存 demo：使用全局门面 cache
+    if (req.path === '/cache-demo') {
+        let hits = await cache.get<number>('cache-demo-hits') ?? 0;
+        hits++;
+        await cache.set('cache-demo-hits', hits, 300);
+        return Response.json({ message: 'Hello from cache!', hits });
+    }
+    // remember demo：缓存 miss 时调用 factory
+    if (req.path === '/cache-remember') {
+        const data = await cache.remember('heavy:computation', 60, async () => {
+            // 模拟耗时计算
+            return { computed: true, ts: Date.now() };
+        });
+        return Response.json(data);
+    }
+    return next();
+});
+
+app.listen(4567, () => {
+    console.log('Server running at http://localhost:4567');
+    console.log('Routes:');
+    console.log('  GET /hello          - Plain text');
+    console.log('  GET /json           - JSON response');
+    console.log('  GET /api/status     - API router');
+    console.log('  GET /api/data       - API router');
+    console.log('  GET /users/123      - Route with param');
+    console.log('  POST /users         - POST route');
+    console.log('  GET /error          - HttpError demo');
+    console.log('  GET /db-fail        - RuntimeError demo');
+    console.log('  POST /upload        - File upload');
+    console.log('  GET /stream         - SSE stream');
+    console.log('  GET /cookie-test    - Cookie demo');
+});

package/example/public/index.html

@@ -0,0 +1 @@
+<html><body><h1>Hello</h1></body></html>

package/example/public/test.json

@@ -0,0 +1 @@
+{"status":"ok"}

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@tyno/tyno",
+  "version": "2.1.3",
+  "description": "A lightweight Node.js HTTP framework with onion model middleware, trie router, SSE, and TypeScript support.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/cjs/index.cjs"
+    },
+    "./facade": {
+      "types": "./dist/facade/index.d.ts",
+      "import": "./dist/facade/index.js",
+      "require": "./dist/cjs/facade/index.cjs"
+    },
+    "./middleware": {
+      "types": "./dist/middlewares/index.d.ts",
+      "import": "./dist/middlewares/index.js",
+      "require": "./dist/cjs/middlewares/index.cjs"
+    },
+    "./router": {
+      "types": "./dist/router/index.d.ts",
+      "import": "./dist/router/index.js",
+      "require": "./dist/cjs/router/index.cjs"
+    },
+    "./errors": {
+      "types": "./dist/errors/index.d.ts",
+      "import": "./dist/errors/index.js",
+      "require": "./dist/cjs/errors/index.cjs"
+    },
+    "./cache": {
+      "types": "./dist/cache/index.d.ts",
+      "import": "./dist/cache/index.js",
+      "require": "./dist/cjs/cache/index.cjs"
+    },
+    "./response": {
+      "types": "./dist/response.d.ts",
+      "import": "./dist/response.js",
+      "require": "./dist/cjs/response.cjs"
+    },
+    "./types": {
+      "types": "./dist/types.d.ts",
+      "import": "./dist/types.js",
+      "require": "./dist/cjs/types.cjs"
+    }
+  },
+  "scripts": {
+    "dev": "tsx watch example/app.ts",
+    "build": "node scripts/build.mjs",
+    "typecheck": "tsc --noEmit"
+  },
+  "author": "weberzhang",
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^20.11.0",
+    "tsx": "^4.7.0",
+    "typescript": "^5.3.0"
+  }
+}

package/scripts/build.mjs

@@ -0,0 +1,97 @@
+/**
+ * Build script: generates ESM (.js) and CJS (.cjs) + declarations.
+ * Uses esbuild per-file, then rewrites .ts → .js/.cjs in import specifiers.
+ */
+import { build } from 'esbuild';
+import { execSync } from 'node:child_process';
+import { readdirSync, statSync, existsSync, mkdirSync, rmSync, readFileSync, writeFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+
+const srcDir = join(process.cwd(), 'src');
+const distDir = join(process.cwd(), 'dist');
+const distCjsDir = join(distDir, 'cjs');
+
+function walk(dir, entries) {
+    for (const entry of readdirSync(dir)) {
+        const full = join(dir, entry);
+        if (statSync(full).isDirectory()) {
+            walk(full, entries);
+        } else if (entry.endsWith('.ts') && !entry.endsWith('.d.ts')) {
+            entries.push(full);
+        }
+    }
+}
+
+/** Replace .ts extensions in import/export/require specifiers */
+function fixExtensions(dir, newExt) {
+    function fix(filePath) {
+        if (statSync(filePath).isDirectory()) {
+            for (const e of readdirSync(filePath)) fix(join(filePath, e));
+        } else if (filePath.endsWith('.js') || filePath.endsWith('.cjs')) {
+            let content = readFileSync(filePath, 'utf-8');
+            // import/export from '.../xxx.ts'
+            content = content.replace(/((?:from|import)\s+['"])(\.\.?\/[^'"]+)(\.ts)(['"])/g, `$1$2${newExt}$4`);
+            // require('.../xxx.ts')  — both var x = require(...) and bare require(...)
+            content = content.replace(/(require\s*\(\s*['"])(\.\.?\/[^'"]+)(\.ts)(['"])/g, `$1$2${newExt}$4`);
+            writeFileSync(filePath, content);
+        }
+    }
+    fix(dir);
+}
+
+async function main() {
+    if (existsSync(distDir)) rmSync(distDir, { recursive: true });
+    mkdirSync(distDir, { recursive: true });
+    mkdirSync(distCjsDir, { recursive: true });
+
+    const entries = [];
+    walk(srcDir, entries);
+    console.log(`[build] Found ${entries.length} source files`);
+
+    // 1. ESM build
+    console.log('[build] Building ESM...');
+    for (const entry of entries) {
+        const outfile = entry.replace(srcDir, distDir).replace(/\.ts$/, '.js');
+        mkdirSync(dirname(outfile), { recursive: true });
+        await build({
+            entryPoints: [entry],
+            outfile,
+            format: 'esm',
+            platform: 'node',
+            target: 'node20',
+            bundle: false,
+            sourcemap: true,
+        });
+    }
+    fixExtensions(distDir, '.js');
+    console.log('[build] ESM extensions fixed');
+
+    // 2. CJS build
+    console.log('[build] Building CJS...');
+    for (const entry of entries) {
+        const outfile = entry.replace(srcDir, distCjsDir).replace(/\.ts$/, '.cjs');
+        mkdirSync(dirname(outfile), { recursive: true });
+        await build({
+            entryPoints: [entry],
+            outfile,
+            format: 'cjs',
+            platform: 'node',
+            target: 'node20',
+            bundle: false,
+            sourcemap: true,
+        });
+    }
+    fixExtensions(distCjsDir, '.cjs');
+    console.log('[build] CJS extensions fixed');
+
+    // 3. Declarations via tsc
+    console.log('[build] Generating declarations...');
+    execSync('npx tsc -p tsconfig.build.json --emitDeclarationOnly', { stdio: 'inherit' });
+
+    console.log('[build] Done!');
+}
+
+main().catch(err => {
+    console.error('[build] Failed:', err);
+    process.exit(1);
+});

package/scripts/rename-cjs.mjs

@@ -0,0 +1,23 @@
+/**
+ * 将 dist/cjs/ 中的 .js 文件重命名为 .cjs，并修复内部 import 路径。
+ * TypeScript 不直接支持输出 .cjs 扩展名，需要后处理。
+ */
+import { readdirSync, renameSync, readFileSync, writeFileSync, statSync } from 'node:fs';
+import { join, extname } from 'node:path';
+
+const cjsDir = join(process.cwd(), 'dist/cjs');
+
+function walk(dir) {
+    for (const entry of readdirSync(dir)) {
+        const full = join(dir, entry);
+        if (statSync(full).isDirectory()) {
+            walk(full);
+        } else if (entry.endsWith('.js')) {
+            const newPath = full.replace(/\.js$/, '.cjs');
+            renameSync(full, newPath);
+        }
+    }
+}
+
+walk(cjsDir);
+console.log('[build] CJS files renamed to .cjs');

package/src/application.ts

@@ -0,0 +1,304 @@
+import http from 'node:http';
+import https from 'node:https';
+import { Readable, PassThrough } from 'node:stream';
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { EventEmitter } from 'node:events';
+import { Request, DATA_KEY } from './request/index.ts';
+import { Response } from './response.ts';
+import { requestStore } from './context.ts';
+import { compose } from './compose.ts';
+import { AppError } from './errors/index.ts';
+import { createErrorPageHandler } from './middlewares/error-page.ts';
+import { CacheManager } from './cache/index.ts';
+import type { CacheConfig } from './cache/types.ts';
+import type { AnyMiddleware, InitializerFn, ListenOptions, RequestHandler, TynoRequest, InjectOptions, InjectResult, ApplicationOptions, BodyParserConfig } from './types.ts';
+
+function createRequestProxy(nodeReq: IncomingMessage, bodyConfig: BodyParserConfig): TynoRequest {
+    const realReq = new Request(nodeReq, bodyConfig);
+    return new Proxy(realReq, {
+        get(target: Request, prop: string | symbol, receiver: unknown): unknown {
+            if (prop in target) {
+                const value = Reflect.get(target, prop, receiver);
+                if (typeof value === 'function') return value.bind(target);
+                return value;
+            }
+            return target[DATA_KEY][prop as string];
+        },
+        set(target: Request, prop: string | symbol, value: unknown): boolean {
+            if (prop in target) return false;
+            target[DATA_KEY][prop as string] = value;
+            return true;
+        },
+        deleteProperty(target: Request, prop: string | symbol): boolean {
+            if (prop in target) return false;
+            delete target[DATA_KEY][prop as string];
+            return true;
+        }
+    }) as unknown as TynoRequest;
+}
+
+async function sendResponse(nodeRes: ServerResponse, res: Response): Promise<void> {
+    const { status, headers, body } = res;
+    if (res._cookies && res._cookies.length) {
+        (headers as Record<string, unknown>)['Set-Cookie'] = res._cookies;
+    }
+    // 使用 Response.get() 的大小写不敏感查找
+    const contentType = res.get('Content-Type') || '';
+    const isSSE = contentType.startsWith('text/event-stream');
+
+    if (isSSE && body && typeof (body as AsyncIterable<unknown>)[Symbol.asyncIterator] === 'function') {
+        nodeRes.writeHead(status, headers);
+        try {
+            for await (const chunk of body as AsyncIterable<unknown>) {
+                if (nodeRes.writableEnded) break;
+                const data = typeof chunk === 'string' ? chunk : JSON.stringify(chunk);
+                nodeRes.write(`data: ${data.replace(/\n/g, '\ndata: ')}\n\n`);
+            }
+        } catch (err: unknown) {
+            if (!nodeRes.writableEnded) nodeRes.write(`event: error\ndata: ${(err as Error).message}\n\n`);
+        } finally {
+            if (!nodeRes.writableEnded) nodeRes.end();
+        }
+        return;
+    }
+
+    nodeRes.writeHead(status, headers);
+    if (body == null) {
+        nodeRes.end();
+    } else if (typeof (body as NodeJS.ReadableStream).pipe === 'function') {
+        (body as NodeJS.ReadableStream).pipe(nodeRes);
+    } else {
+        nodeRes.end(body as string | Buffer);
+    }
+}
+
+function buildErrorResponse(err: unknown, debug: boolean): Response {
+    if (err instanceof AppError) {
+        const status = err.status;
+        const message = err.expose ? err.message : 'Internal Server Error';
+        const body: Record<string, unknown> = { error: message, status };
+        if (err.code != null) body.code = err.code;
+        if (debug) { body.stack = err.stack; body.name = err.name; if (err.cause) body.cause = (err.cause as Error).message; }
+        return Response.json(body, status);
+    }
+    const e = err as Error;
+    const body: Record<string, unknown> = { error: 'Internal Server Error', status: 500 };
+    if (debug) { body.stack = e.stack; body.name = e.name; }
+    return Response.json(body, 500);
+}
+
+/** 将 response 门面中预设的 header/cookie 合并到响应 */
+function mergeResponseFacade(finalRes: Response): void {
+    const pending = Response._getPending();
+    if (!pending) return;
+    for (const [k, v] of Object.entries(pending.headers)) {
+        if (!finalRes.get(k)) finalRes.set(k, v);
+    }
+    if (pending.cookies.length) {
+        finalRes._cookies = [...pending.cookies, ...finalRes._cookies];
+    }
+}
+
+function logError(err: unknown): void {
+    const e = err as Record<string, unknown>;
+    const status = (e.status as number) || 500;
+    if (status >= 500) {
+        const cause = e.cause ? `\n  caused by: ${(e.cause as Error).stack || (e.cause as Error).message || String(e.cause)}` : '';
+        console.error(`[tyno] ${e.name || 'Error'}: ${e.message}${cause}`);
+    }
+}
+
+export class Application extends EventEmitter {
+    middlewares: AnyMiddleware[] = [];
+    server: http.Server | https.Server | null = null;
+    debug: boolean;
+    bodyConfig: BodyParserConfig;
+    private _shutdownHandlers: (() => unknown | Promise<unknown>)[] = [];
+    private _initializers: InitializerFn[] = [];
+    private _initialized = false;
+    private _cache: CacheManager | null = null;
+    private cacheConfig: CacheConfig;
+
+    constructor(options: ApplicationOptions = {}) {
+        super();
+        this.debug = options.debug ?? (process.env.NODE_ENV !== 'production');
+        this.bodyConfig = options.body ?? {};
+        this.cacheConfig = options.cache ?? {};
+    }
+
+    /**
+     * 获取缓存实例（懒加载，首次调用时初始化驱动）。
+     *
+     * @example
+     * await app.cache().set('key', 'value', 60);
+     * const val = await app.cache().get('key');
+     */
+    cache(): CacheManager {
+        if (!this._cache) {
+            this._cache = new CacheManager(this.cacheConfig);
+        }
+        return this._cache;
+    }
+
+    /**
+     * 注册初始化器。初始化器在 listen() 启动服务前按注册顺序自动执行。
+     */
+    initialize(fn: InitializerFn): this {
+        if (this._initialized) {
+            console.warn('[tyno] initialize() called after server has started, initializer will not run automatically. Consider registering initializers before listen().');
+        }
+        this._initializers.push(fn);
+        return this;
+    }
+
+    /**
+     * 注册中间件。支持单个函数或函数数组，按顺序依次执行。
+     */
+    use(fn: AnyMiddleware | AnyMiddleware[]): this {
+        if (Array.isArray(fn)) {
+            for (const f of fn) this.middlewares.push(f);
+        } else if (typeof fn === 'function') {
+            this.middlewares.push(fn);
+        }
+        return this;
+    }
+
+    /** `use()` 的别名 */
+    middleware(fn: AnyMiddleware | AnyMiddleware[]): this {
+        return this.use(fn);
+    }
+
+    /**
+     * 获取请求处理函数。
+     */
+    callback(): RequestHandler {
+        const middlewares = this.debug
+            ? [...this.middlewares, createErrorPageHandler({ dev: true })]
+            : this.middlewares;
+        return async (nodeReq: IncomingMessage, nodeRes: ServerResponse) => {
+            const reqProxy = createRequestProxy(nodeReq, this.bodyConfig);
+            // 将 CacheManager 注入请求上下文，供 cache 门面使用
+            if (Object.keys(this.cacheConfig).length > 0 || this._cache) {
+                (reqProxy as unknown as Record<string, unknown>)['_tyno_cache'] = this.cache();
+            }
+            await requestStore.run(reqProxy, async () => {
+                this.emit('request', reqProxy);
+                try {
+                    const finalResponse = await compose(reqProxy, middlewares);
+                    mergeResponseFacade(finalResponse);
+                    this.emit('response', reqProxy, finalResponse);
+                    await sendResponse(nodeRes, finalResponse);
+                    this.emit('response:sent', reqProxy, finalResponse);
+                } catch (err: unknown) {
+                    if (this.listenerCount('error') > 0) this.emit('error', err, reqProxy);
+                    if (!nodeRes.headersSent) {
+                        const errorResponse = buildErrorResponse(err, this.debug);
+                        mergeResponseFacade(errorResponse);
+                        await sendResponse(nodeRes, errorResponse);
+                        this.emit('response:sent', reqProxy, errorResponse);
+                    }
+                    logError(err);
+                }
+            });
+        };
+    }
+
+    /**
+     * 启动服务。
+     */
+    listen(portOrOptions: number | ListenOptions, callback?: () => void): http.Server | https.Server {
+        const options: ListenOptions = typeof portOrOptions === 'object' ? portOrOptions : { port: portOrOptions };
+        const handler = this.callback();
+        this.server = options.tls ? https.createServer(options.tls as https.ServerOptions, handler) : http.createServer(handler);
+
+        // 启动前自动执行初始化器
+        if (!this._initialized && this._initializers.length > 0) {
+            const init = async () => {
+                for (const fn of this._initializers) {
+                    await fn(this);
+                }
+                this._initialized = true;
+                this.server!.listen(options.port, options.host, () => {
+                    this.emit('ready');
+                    callback?.();
+                });
+            };
+            init().catch((err) => {
+                console.error('[tyno] Initializer failed:', err);
+                process.exit(1);
+            });
+        } else {
+            this._initialized = true;
+            this.server.listen(options.port, options.host, () => {
+                this.emit('ready');
+                callback?.();
+            });
+        }
+        if (options.gracefulShutdown !== false) {
+            const shutdown = () => this.close();
+            process.once('SIGINT', shutdown);
+            process.once('SIGTERM', shutdown);
+        }
+        return this.server;
+    }
+
+    close(callback?: () => void): void {
+        if (!this.server) return;
+        this._cache?.close().catch(() => {});
+        Promise.all(this._shutdownHandlers.map(fn => fn())).catch(() => {});
+        this.server.close(callback);
+    }
+
+    onShutdown(fn: () => unknown | Promise<unknown>): this {
+        if (typeof fn === 'function') this._shutdownHandlers.push(fn);
+        return this;
+    }
+
+    async inject(options: InjectOptions = {}): Promise<InjectResult> {
+        const { method = 'GET', url = '/', headers = {}, body } = options;
+        const rawBody = body ? (typeof body === 'string' ? body : Buffer.isBuffer(body) ? body.toString() : JSON.stringify(body)) : null;
+        const bodyBuf = rawBody ? Buffer.from(rawBody) : null;
+        const mockReq = Readable.from(bodyBuf ? [bodyBuf] : []) as unknown as IncomingMessage;
+        mockReq.method = method.toUpperCase();
+        mockReq.url = url;
+        mockReq.headers = {};
+        for (const [k, v] of Object.entries(headers)) mockReq.headers[k.toLowerCase()] = v;
+        if (options.cookies) {
+            const cookieStr = Object.entries(options.cookies).map(([k, v]) => `${k}=${v}`).join('; ');
+            if (cookieStr) mockReq.headers['cookie'] = cookieStr;
+        }
+        (mockReq as unknown as Record<string, unknown>).socket = { remoteAddress: '127.0.0.1' };
+
+        const chunks: Buffer[] = [];
+        const mockPassthrough = new PassThrough();
+        mockPassthrough.on('data', (chunk: Buffer) => chunks.push(chunk));
+        const mockRes = mockPassthrough as unknown as Record<string, unknown>;
+        mockRes.statusCode = 200;
+        mockRes.headers = {};
+        mockRes.headersSent = false;
+        mockRes.writeHead = function (status: number, statusMsgOrHeaders?: unknown, headers?: Record<string, unknown>) {
+            this.statusCode = status;
+            const h = typeof statusMsgOrHeaders === 'string' ? headers : (statusMsgOrHeaders as Record<string, unknown>);
+            if (h) {
+                // 归一化 header 名为小写
+                for (const [k, v] of Object.entries(h)) {
+                    (this.headers as Record<string, unknown>)[k.toLowerCase()] = v;
+                }
+            }
+            this.headersSent = true;
+        };
+
+        const handler = this.callback();
+        await handler(mockReq, mockRes as unknown as ServerResponse);
+        if (!mockRes.writableEnded) await new Promise<void>(resolve => mockPassthrough.on('finish', () => resolve()));
+        await new Promise<void>(resolve => setImmediate(resolve));
+
+        const bodyStr = Buffer.concat(chunks).toString();
+        return {
+            status: mockRes.statusCode as number,
+            headers: mockRes.headers as Record<string, unknown>,
+            body: bodyStr,
+            json<T = unknown>(): T { return JSON.parse(bodyStr) as T; }
+        };
+    }
+}