test: 补充 wrapWithEnvelope/compose 单测 + envelope response schema 校验覆盖

在现有测试文件补充（不新建）：
- test-envelope.ts: wrapWithEnvelope 6 分支单测（零开销退化/success包装/不二次包装/
  error包装/re-throw/undefined）+ enveloper 模式下 response schema 校验（通过+失败）
- test-router.ts: compose 洋葱模型 6 单测（顺序/终止/reject/同步抛错/重复next/空链）

lib/adapters/utils.ts 覆盖率 27.77% → 100%，整体 92.33% 达标。

Author: yourtion

src/test/test-envelope.ts

@@ -5,9 +5,41 @@
 import express from "express";
 import { expressAdapter } from "./adapters";
 import { httpReq as request } from "./http-req";
-import { afterAll, describe, expect, it } from "vitest";
+import { afterAll, describe, expect, it, vi } from "vitest";
+import { z } from "zod";
+import { wrapWithEnvelope } from "../lib/adapters/utils.js";
+import type { Context } from "../lib/adapters/types.js";
 import lib from "./lib";
 
+/** 构造最小 Context mock（state 可读写，reply 记录调用） */
+function mockCtx(): Context & {
+  __returned?: boolean;
+  __returnValue?: unknown;
+  reply: {
+    status: ReturnType<typeof vi.fn>;
+    json: ReturnType<typeof vi.fn>;
+    send: ReturnType<typeof vi.fn>;
+    raw: unknown;
+  };
+} {
+  const reply = {
+    status: vi.fn(() => reply),
+    json: vi.fn(),
+    send: vi.fn(),
+    raw: {},
+  };
+  return {
+    method: "GET",
+    path: "/",
+    headers: {},
+    params: {},
+    query: {},
+    body: {},
+    state: {},
+    reply,
+  } as Context & { __returned?: boolean; __returnValue?: unknown; reply: typeof reply };
+}
+
 describe("全局 response envelope（registerTyped return 模式）", () => {
   const envelopers = {
     success: (data: unknown) => ({ success: true, data }),
@@ -80,6 +112,114 @@ describe("全局 response envelope（registerTyped return 模式）", () => {
     expect(res.status).toBe(200);
     expect(res.body).toEqual({ success: true, data: undefined });
   });
+
+  it("enveloper 模式 + response schema → 校验 return 值后再包装", async () => {
+    const app = express();
+    app.use(express.json());
+    const apiService = lib({ basePath: "" });
+    apiService.setResponseEnvelopers(envelopers);
+
+    apiService.api
+      .get("/env-schema")
+      .group("Index")
+      .title("env-schema")
+      .registerTyped(
+        { response: z.object({ id: z.number() }) },
+        async () => ({ id: 7 }) // return 值会先经 response schema 校验，再经 enveloper 包装
+      );
+
+    apiService.bind({ adapter: expressAdapter, router: app });
+    const res = await request(app).get("/env-schema");
+    expect(res.status).toBe(200);
+    expect(res.body).toEqual({ success: true, data: { id: 7 } });
+  });
+
+  it("enveloper 模式 + response schema → return 值不合 schema 时抛错（走 error enveloper）", async () => {
+    const app = express();
+    app.use(express.json());
+    const apiService = lib({ basePath: "" });
+    apiService.setResponseEnvelopers(envelopers);
+
+    apiService.api
+      .get("/env-schema-bad")
+      .group("Index")
+      .title("env-schema-bad")
+      .registerTyped(
+        { response: z.object({ id: z.number() }) },
+        async () => ({ id: "not-a-number" }) as never // 类型撒谎：实际返回 string
+      );
+
+    apiService.bind({ adapter: expressAdapter, router: app });
+    const res = await request(app).get("/env-schema-bad");
+    // response schema 校验失败 → 抛 ZodError → error enveloper 包装
+    expect(res.status).toBe(500);
+    expect(res.body.success).toBe(false);
+  });
+});
+
+// wrapWithEnvelope 直接单测（不经子包 dist，确保 coverage 统计到 src/lib/adapters/utils）
+describe("wrapWithEnvelope 单元测试", () => {
+  it("未注册任何 enveloper 时零开销退化（返回原 dispatch）", () => {
+    const dispatch = vi.fn();
+    const wrapped = wrapWithEnvelope(dispatch as never, {});
+    expect(wrapped).toBe(dispatch); // 直接返回原 dispatch，不包装
+  });
+
+  it("handler return data → successEnveloper 包装写入 reply.json", async () => {
+    const ctx = mockCtx();
+    ctx.__returned = true;
+    ctx.__returnValue = { id: 1 };
+    const success = vi.fn((data: unknown) => ({ success: true, data }));
+
+    await wrapWithEnvelope(async () => Promise.resolve(), { success })(ctx);
+
+    expect(success).toHaveBeenCalledWith({ id: 1 }, ctx);
+    expect(ctx.reply.json).toHaveBeenCalledWith({ success: true, data: { id: 1 } });
+  });
+
+  it("handler 未置 __returned（自行调 ctx.reply）→ 不二次包装", async () => {
+    const ctx = mockCtx();
+    const success = vi.fn();
+
+    await wrapWithEnvelope(async () => Promise.resolve(), { success })(ctx);
+
+    expect(success).not.toHaveBeenCalled();
+    expect(ctx.reply.json).not.toHaveBeenCalled();
+  });
+
+  it("handler 抛错 → errorEnveloper 包装 status + body", async () => {
+    const ctx = mockCtx();
+    const boom = Object.assign(new Error("not found"), { statusCode: 404 });
+    const error = vi.fn(() => ({ body: { fail: true }, status: 404 }));
+
+    await wrapWithEnvelope(async () => Promise.reject(boom), { error })(ctx);
+
+    expect(error).toHaveBeenCalledWith(boom, ctx);
+    expect(ctx.reply.status).toHaveBeenCalledWith(404);
+    expect(ctx.reply.json).toHaveBeenCalledWith({ fail: true });
+  });
+
+  it("仅注册 success enveloper 时，抛错 re-throw（不吞错）", async () => {
+    const ctx = mockCtx();
+    const success = vi.fn();
+
+    await expect(wrapWithEnvelope(async () => Promise.reject(new Error("escape")), { success })(ctx)).rejects.toThrow(
+      "escape"
+    );
+    expect(success).not.toHaveBeenCalled();
+  });
+
+  it("__returned=true 但 returnValue=undefined → successEnveloper 仍被调用", async () => {
+    const ctx = mockCtx();
+    ctx.__returned = true;
+    ctx.__returnValue = undefined;
+    const success = vi.fn((data: unknown) => ({ ok: true, data }));
+
+    await wrapWithEnvelope(async () => Promise.resolve(), { success })(ctx);
+
+    expect(success).toHaveBeenCalledWith(undefined, ctx);
+    expect(ctx.reply.json).toHaveBeenCalled();
+  });
 });
 
 afterAll(() => {});

src/test/test-router.ts

@@ -9,6 +9,8 @@ import { expressAdapter, koaAdapter, leizmwebAdapter } from "./adapters";
 import express from "express";
 import { describe, expect, test } from "vitest";
 import { z } from "zod";
+import { compose } from "../lib/adapters/utils.js";
+import type { Context } from "../lib/adapters/types.js";
 import { commonSchemas, createAllCrudApis, createGetApi, createPostApi } from "./utils/api-helpers";
 import { assertApiRegistered, assertThrowsWithMessage } from "./utils/assertion-helpers";
 import { createMockHook, createStandardHooks } from "./utils/mock-factories";
@@ -661,3 +663,79 @@ describe("Router - Unified bind() Method", () => {
     });
   });
 });
+
+// compose 洋葱模型单元测试（bind 路由的中间件链核心，直接 import 源码确保 coverage）
+describe("compose 洋葱模型", () => {
+  /** 构造最小 Context */
+  function mockCtx(): Context {
+    return {
+      method: "GET",
+      path: "/",
+      headers: {},
+      params: {},
+      query: {},
+      body: {},
+      state: {},
+      reply: { status: () => undefined, json: () => undefined, send: () => undefined, raw: {} },
+    } as Context;
+  }
+
+  test("按顺序执行中间件链（洋葱：next 前后）", async () => {
+    const order: string[] = [];
+    const mws = [
+      (ctx: Context, next: () => Promise<void>) => {
+        order.push("a-before");
+        return next().then(() => order.push("a-after"));
+      },
+      (_ctx: Context, next: () => Promise<void>) => {
+        order.push("b");
+        return next();
+      },
+    ];
+    await compose(mws)(mockCtx());
+    expect(order).toEqual(["a-before", "b", "a-after"]);
+  });
+
+  test("不调 next 则终止后续链", async () => {
+    const order: string[] = [];
+    const mws = [
+      () => {
+        order.push("a");
+      },
+      () => {
+        order.push("b");
+      },
+    ];
+    await compose(mws)(mockCtx());
+    expect(order).toEqual(["a"]);
+  });
+
+  test("中间件 reject 向上抛", async () => {
+    const mws = [() => Promise.reject(new Error("boom"))];
+    await expect(compose(mws)(mockCtx())).rejects.toThrow("boom");
+  });
+
+  test("中间件同步抛错也 reject", async () => {
+    const mws = [
+      () => {
+        throw new Error("sync-boom");
+      },
+    ];
+    await expect(compose(mws)(mockCtx())).rejects.toThrow("sync-boom");
+  });
+
+  test("next 重复调用时报错（防循环）", async () => {
+    const mws = [
+      async (_ctx: Context, next: () => Promise<void>) => {
+        await next();
+        await next();
+      },
+    ];
+    await expect(compose(mws)(mockCtx())).rejects.toThrow("next() called multiple times");
+  });
+
+  test("空中间件链直接完成", async () => {
+    const ret = await compose([])(mockCtx());
+    expect(ret).toBeUndefined();
+  });
+});