@taicode/common-server 3.8.0 → 4.0.0-beta.10

package/output/core/test-support/environment.d.ts

@@ -0,0 +1,38 @@
+import type { ConfigEnv } from '../env.js';
+/**
+ * **工具进程**的环境出口。
+ *
+ * `startServer` / `createTestServer` 覆盖不到的进程（`prisma.config.ts`、`scripts/*.ts`、以及被
+ * 它们静态 import 的配置模块）只能自己开口要 env：ES 模块顶层求值早于入口函数执行，所以
+ * 「入口里加载 env」救不了这些文件。
+ *
+ * 只加载、不做任何闸门——运行期配置不该带上测试闸门，那会给正常启动平白加一道无关检查。
+ * 幂等：重复调用只是重复读 `dotenv`。
+ */
+export declare function loadRuntimeEnvironment(): ConfigEnv;
+/**
+ * 结算**测试**数据库目标：加载测试层 → 闸门 → 结算 → 把测试连接串注入返回的 env 快照。
+ *
+ * **`createTestServer` 的私有步骤，不对外导出。** 导出它等于让调用方自己决定「什么时候跑
+ * 闸门、按什么顺序」，而顺序本身就是安全前提。
+ *
+ * 顺序（固定，不开放重排）：
+ * ```
+ * 加载 .env.dev < .env < .env.local < .env.test < .env.test.local（ENV 未给时兜底 test）
+ *   → 环境闸门（ENV 必须可清理）
+ *   → 结算（显式 TEST_DATABASE_URL 优先，否则由 DATABASE_URL 派生 +_test，幂等）
+ *   → schema 闸门（必须以 _test 结尾）
+ *   → 把测试连接串写进**返回的 env 快照**（不碰全局 process.env）
+ * ```
+ *
+ * **为什么不再改写 `process.env.DATABASE_URL`**：那是进程级副作用——同一进程里并行跑多个
+ * `createTestServer`（或测试与被测代码共享进程）时会互相覆写，谁最后写谁赢。测试目标应当
+ * 只属于**本次装配**：框架把它注入到返回的 `env` 快照里，`resources` 槽位从 `ctx.env.DATABASE_URL`
+ * 读取（框架契约：资源只读 `ctx.env`，不读 `process.env`），因此每个实例各连各的，互不干扰。
+ *
+ * 隔离比较不在这里：返回的 `env.DATABASE_URL` 此时就是测试目标，比对恒等于「自比自」。
+ * 防止测试清空应用数据靠的是**派生 + `_test` schema 闸门**——派生只会追加后缀，schema 闸门
+ * 只放行 `*_test`，所以测试目标结构上不可能是应用目标。
+ */
+export declare function prepareTestDatabase(): ConfigEnv;
+//# sourceMappingURL=environment.d.ts.map

package/output/core/test-support/environment.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"environment.d.ts","sourceRoot":"","sources":["../../../source/core/test-support/environment.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAA;AAE1C;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,IAAI,SAAS,CAElD;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,mBAAmB,IAAI,SAAS,CAO/C"}

package/output/core/test-support/environment.js

@@ -0,0 +1,45 @@
+import { loadEnvironment, resolveConfigEnv } from '../env.js';
+import { resolveTestDatabase } from './database.js';
+/**
+ * **工具进程**的环境出口。
+ *
+ * `startServer` / `createTestServer` 覆盖不到的进程（`prisma.config.ts`、`scripts/*.ts`、以及被
+ * 它们静态 import 的配置模块）只能自己开口要 env：ES 模块顶层求值早于入口函数执行，所以
+ * 「入口里加载 env」救不了这些文件。
+ *
+ * 只加载、不做任何闸门——运行期配置不该带上测试闸门，那会给正常启动平白加一道无关检查。
+ * 幂等：重复调用只是重复读 `dotenv`。
+ */
+export function loadRuntimeEnvironment() {
+    return loadEnvironment();
+}
+/**
+ * 结算**测试**数据库目标：加载测试层 → 闸门 → 结算 → 把测试连接串注入返回的 env 快照。
+ *
+ * **`createTestServer` 的私有步骤，不对外导出。** 导出它等于让调用方自己决定「什么时候跑
+ * 闸门、按什么顺序」，而顺序本身就是安全前提。
+ *
+ * 顺序（固定，不开放重排）：
+ * ```
+ * 加载 .env.dev < .env < .env.local < .env.test < .env.test.local（ENV 未给时兜底 test）
+ *   → 环境闸门（ENV 必须可清理）
+ *   → 结算（显式 TEST_DATABASE_URL 优先，否则由 DATABASE_URL 派生 +_test，幂等）
+ *   → schema 闸门（必须以 _test 结尾）
+ *   → 把测试连接串写进**返回的 env 快照**（不碰全局 process.env）
+ * ```
+ *
+ * **为什么不再改写 `process.env.DATABASE_URL`**：那是进程级副作用——同一进程里并行跑多个
+ * `createTestServer`（或测试与被测代码共享进程）时会互相覆写，谁最后写谁赢。测试目标应当
+ * 只属于**本次装配**：框架把它注入到返回的 `env` 快照里，`resources` 槽位从 `ctx.env.DATABASE_URL`
+ * 读取（框架契约：资源只读 `ctx.env`，不读 `process.env`），因此每个实例各连各的，互不干扰。
+ *
+ * 隔离比较不在这里：返回的 `env.DATABASE_URL` 此时就是测试目标，比对恒等于「自比自」。
+ * 防止测试清空应用数据靠的是**派生 + `_test` schema 闸门**——派生只会追加后缀，schema 闸门
+ * 只放行 `*_test`，所以测试目标结构上不可能是应用目标。
+ */
+export function prepareTestDatabase() {
+    const loaded = loadEnvironment({ mode: 'test' });
+    const databaseUrl = resolveTestDatabase({ env: loaded.ENV });
+    // 只注入到本次装配的 env 快照，**不改写全局 process.env.DATABASE_URL**（避免进程级串扰）
+    return { ...resolveConfigEnv(), DATABASE_URL: databaseUrl };
+}

package/output/core/test-support/service-context.d.ts

@@ -0,0 +1,64 @@
+import type { ClientsView, LoggerLike, ResourcesView, ServiceContext } from '../types.js';
+/**
+ * `createTestServiceContext()` —— **单元级**测试构造 `services` 槽位入参的唯一方式。
+ *
+ * ## 为什么框架要给这个出口
+ *
+ * `createTestServer()` 是**集成**测试的唯一入口：它跑全量装配（resources → config →
+ * clients → services → routers），代价是「每条用例都要连真库、装全部路由」。只想验一个
+ * service 函数的判断逻辑时，这个代价与收益不成比例——于是各仓各自写了一份
+ * `createServiceContext(fakeDb, { ... })`，还都带着同一句
+ * `as unknown as AccountServiceContext`：**同一个绕过动作被抄了四遍**，说明缺的是
+ * 框架能力，不是各仓的疏忽。
+ *
+ * 这里的取舍是明确的：**不伪造能力，只允许缺省能力**。
+ * - 传进来的 `resources` / `clients` 是**真实对象**（真 reader、真 db 客户端、注入式
+ *   替身），不是 mock 框架的代理——本函数不生成任何行为，只做装配。
+ * - 没传的能力被访问时**抛错**（错误信息点名是哪个键），而不是返回 `undefined` 让调用方
+ *   的 `undefined.xxx` 在更远处炸开。这区分了「这个单元不该碰数据库」与「忘了给数据库」
+ *   两种完全不同的失败。
+ *
+ * ## 为什么不干脆把 `ctx` 收窄成「这个服务用到的字段」
+ *
+ * 那会让「服务工厂第一参数恒为 ctx」这条约定退化：每个工厂的入参类型各不相同，装配层
+ * 就无法把一份 ctx 原样传下去（`createServices` 得为每个服务裁一次类型）。约定要留，
+ * 代价就由本函数承担——它给出**形状完整、能力可缺省**的 ctx。
+ *
+ * ## `resources.<key>` 为什么用 Proxy 而不是浅合并空对象
+ *
+ * 浅合并只能发现问题的一半：`resources.database` 变成了 `undefined`，错误发生在
+ * `undefined.user.findMany()` 上，栈里全都是业务代码，看不出根因是「这份 ctx 没给
+ * database」。Proxy 让错误在**取字段的那一行**抛出并点名，测试写错时的定位成本从
+ * 「翻业务代码」降到「看一行错误」。
+ */
+export interface TestServiceContextOptions<Resources, Config, Clients> {
+    /**
+     * 提供被测单元**实际读到**的资源能力（其余键访问即抛错）。
+     *
+     * 传真实实例：真 `PrismaClient`、`createSystemConfigReader(db)`，或对**外部 I/O
+     * 边界**（第三方 HTTP、邮件网关）注入的替身。不要替身框架自己的装配。
+     */
+    resources?: Partial<ResourcesView<Resources>>;
+    /** 提供被测单元**实际读到**的客户端（其余键访问即抛错） */
+    clients?: Partial<ClientsView<Clients>>;
+    /** `config` 产物；被测单元按契约不读它时省略（读取会抛错，不会拿到 `undefined`） */
+    config?: Awaited<Config>;
+    /** 日志出口覆盖（缺省为静默 no-op；断言日志时传 `vi.fn()` 组成的实现） */
+    log?: Partial<LoggerLike>;
+}
+/**
+ * 构造 `services` 槽位的测试入参（`ServiceContext`）。
+ *
+ * ```ts
+ * const ctx = createTestServiceContext<AccountResources, AccountConfig>({
+ *   resources: { systemConfig: fakeReader },
+ *   log: { warn: warnSpy },
+ * })
+ * const service = createRuntimeConfigService(ctx)
+ * ```
+ *
+ * 返回的 `disposer` 是**真实** `Disposer`：被测单元登记的释放函数会真的被收集，
+ * 测试可以用 `await ctx.disposer.dispose()` 验证「服务自己登记了释放」这条契约。
+ */
+export declare function createTestServiceContext<Resources, Config, Clients = unknown>(options?: TestServiceContextOptions<Resources, Config, Clients>): ServiceContext<Resources, Config, Clients>;
+//# sourceMappingURL=service-context.d.ts.map

package/output/core/test-support/service-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service-context.d.ts","sourceRoot":"","sources":["../../../source/core/test-support/service-context.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAEzF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,WAAW,yBAAyB,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO;IACnE;;;;;OAKG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,SAAS,CAAC,CAAC,CAAA;IAC7C,mCAAmC;IACnC,OAAO,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC,CAAA;IACvC,wDAAwD;IACxD,MAAM,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,CAAA;IACxB,iDAAiD;IACjD,GAAG,CAAC,EAAE,OAAO,CAAC,UAAU,CAAC,CAAA;CAC1B;AAUD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,wBAAwB,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,GAAG,OAAO,EAC3E,OAAO,GAAE,yBAAyB,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,CAAM,GAClE,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,CAoB5C"}

package/output/core/test-support/service-context.js

@@ -0,0 +1,63 @@
+import { Disposer } from '@taicode/common-base';
+/** 缺省日志：静默。测试不该因为「服务打了一行 info」而需要准备 logger。 */
+const SILENT_LOG = {
+    debug: () => undefined,
+    info: () => undefined,
+    warn: () => undefined,
+    error: () => undefined,
+};
+/**
+ * 构造 `services` 槽位的测试入参（`ServiceContext`）。
+ *
+ * ```ts
+ * const ctx = createTestServiceContext<AccountResources, AccountConfig>({
+ *   resources: { systemConfig: fakeReader },
+ *   log: { warn: warnSpy },
+ * })
+ * const service = createRuntimeConfigService(ctx)
+ * ```
+ *
+ * 返回的 `disposer` 是**真实** `Disposer`：被测单元登记的释放函数会真的被收集，
+ * 测试可以用 `await ctx.disposer.dispose()` 验证「服务自己登记了释放」这条契约。
+ */
+export function createTestServiceContext(options = {}) {
+    // 释放器是真实的：登记 / 逆序执行都是被测契约的一部分，不能替身掉
+    const disposer = new Disposer({ label: 'test-service-context', log: SILENT_LOG });
+    return {
+        log: { ...SILENT_LOG, ...options.log },
+        disposer,
+        resources: requireProvided(options.resources, 'resources'),
+        clients: requireProvided(options.clients, 'clients'),
+        get config() {
+            if (options.config === undefined) {
+                throw new Error('[test-service-context] 这份 ctx 没有提供 config：' +
+                    '被测单元按契约不读 config（运行期配置一律经 resources.systemConfig）。' +
+                    '若确实要读，请通过 createTestServiceContext({ config }) 显式给出。');
+            }
+            return options.config;
+        },
+    };
+}
+/**
+ * 把「部分提供」包装成「形状完整、缺省即抛错」的视图。
+ *
+ * 只在**读取被缺省的键**时抛错：传了的键行为与真实视图完全一致（同一个对象、同一份
+ * 引用），所以注入式替身与真实例都照常工作。
+ */
+function requireProvided(provided, label) {
+    const source = provided ?? {};
+    return new Proxy(source, {
+        get(target, key, receiver) {
+            // Symbol（`Symbol.toStringTag`、`then` 探测等）与 `in` 都按普通对象处理
+            if (typeof key === 'symbol') {
+                return Reflect.get(target, key, receiver);
+            }
+            if (!(key in target)) {
+                throw new Error(`[test-service-context] 这份 ctx 没有提供 ${label}.${key}：` +
+                    `被测单元读到了它，说明它确实依赖这项能力——请通过 createTestServiceContext({ ${label}: { ${key}: … } }) 给出` +
+                    '（真实实例或对外部 I/O 边界的替身，不要替身框架自身的装配）。');
+            }
+            return Reflect.get(target, key, receiver);
+        },
+    });
+}

package/output/core/test-support/service-context.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=service-context.test.d.ts.map

package/output/core/test-support/service-context.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service-context.test.d.ts","sourceRoot":"","sources":["../../../source/core/test-support/service-context.test.ts"],"names":[],"mappings":""}

package/output/core/test-support/service-context.test.js

@@ -0,0 +1,55 @@
+import { describe, expect, it, vi } from 'vitest';
+import { createTestServiceContext } from './service-context.js';
+describe('createTestServiceContext', () => {
+    it('提供的资源与客户端原样可用（同一个引用，不做拷贝）', () => {
+        const database = { user: { count: async () => 3 } };
+        const cache = { get: () => undefined };
+        const ctx = createTestServiceContext({
+            resources: { database },
+            clients: { cache },
+        });
+        expect(ctx.resources.database).toBe(database);
+        expect(ctx.clients.cache).toBe(cache);
+    });
+    it('读取被缺省的能力时当场抛错，错误点名是哪个键', () => {
+        const ctx = createTestServiceContext({
+            resources: { database: { user: { count: async () => 0 } } },
+        });
+        // 提供的键正常
+        expect(ctx.resources.database).toBeDefined();
+        // 未提供的键：取字段那一步就抛，而不是返回 undefined 留到业务代码里炸
+        expect(() => ctx.resources.systemConfig).toThrowError(/resources\.systemConfig/);
+    });
+    it('缺省能力抛错信息里给出补法（createTestServiceContext({ resources: { … } })）', () => {
+        const ctx = createTestServiceContext();
+        expect(() => ctx.clients.anything).toThrowError(/createTestServiceContext\(\{ clients: \{ anything: … \} \}\)/);
+    });
+    it('未给 config 时读取抛错（不会拿到 undefined）', () => {
+        const ctx = createTestServiceContext();
+        expect(() => ctx.config).toThrowError(/没有提供 config/);
+    });
+    it('给了 config 时按传入值返回', () => {
+        const ctx = createTestServiceContext({
+            config: { featureEnabled: true },
+        });
+        expect(ctx.config).toEqual({ featureEnabled: true });
+    });
+    it('disposer 是真实的：登记的清理会被收集并按逆序执行', async () => {
+        const ctx = createTestServiceContext();
+        const order = [];
+        // 模拟「服务在构造期自己登记释放」这条契约
+        ctx.disposer.add(() => order.push('first'));
+        ctx.disposer.add(() => order.push('second'));
+        await ctx.disposer.dispose();
+        expect(order).toEqual(['second', 'first']);
+    });
+    it('日志缺省静默；覆盖后能断言调用', () => {
+        const warn = vi.fn();
+        const silent = createTestServiceContext();
+        const spying = createTestServiceContext({ log: { warn } });
+        // 缺省实现不抛错（pino 之外不要强制测试准备 logger）
+        expect(() => silent.log.warn({ a: 1 }, 'hello')).not.toThrow();
+        spying.log.warn({ a: 1 }, 'hello');
+        expect(warn).toHaveBeenCalledWith({ a: 1 }, 'hello');
+    });
+});

package/output/core/test-support/test-server.d.ts

@@ -0,0 +1,154 @@
+import type { AppEnv, ClientsView, LoggerLike, ResourcesView, Server } from '../types.js';
+import type { FastifyInstance } from 'fastify';
+/**
+ * `createTestServer()` ——**测试对象的唯一构造方式**。
+ *
+ * ## 它是唯一的一个，不是「又一个」入口
+ *
+ * 这里有一个硬性约束：**测试必须跑在生产的同一套装配上**。请求链、响应信封、错误码映射、
+ * `request.ctx`、关闭流程，只要测试里另有一套实现，它就会在生产之外漂移，而漂移只在线暴露。
+ *
+ * 因此测试对象的构造只有一个入口，它**不接受任何槽位覆盖**：没有 `resources` 参数、没有
+ * `services` 参数、没有 `overrideXxx`。覆盖面一开，测试就能绕开生产接线，这个入口随即失去
+ * 全部证明力——那还不如直接写个假 app。
+ *
+ * 需要「只测一个模块」时，**组合定义**，而不是覆盖槽位：
+ *
+ * ```ts
+ * const moduleServer = defineServer({
+ *   ...server,
+ *   routers: ({ app }) => app.register(createUserRouter(stub)),
+ * })
+ * const testServer = await createTestServer(moduleServer)
+ * ```
+ *
+ * 组合用的是同一个 `defineServer` 产物、同一套装配，只是把另一个模块的接线换掉。
+ *
+ * ## 与 `startServer` 的唯一差别
+ *
+ * `startServer` 会 listen 并装信号处理器；测试用 `app.inject()`，且 vitest worker 收不到
+ * SIGTERM。除此之外（env 分层 → resources → config → clients → services → `init()` →
+ * middlewares → 系统路由 → routers、八步关闭）**逐行相同**。
+ *
+ * ## 参数就是那个 `Server`，没有第二个参数
+ *
+ * 连接串结算、闸门、改写 `DATABASE_URL` 全部固定（见 `prepareTestDatabase()`）。
+ * 没有「用哪个连接串」这类开关：测试对象的身份就是测试，让它可以被配置成「有点像测试」
+ * 是把安全前提变成调用方的责任。
+ *
+ * ## 返回值：`TestServer` 就是测试要的一切
+ *
+ * 测试要断言的对象往往不是 HTTP 响应，而是**装配出来的东西本身**：`resources.database` 连的
+ * 是不是 `*_test`、某个 service 有没有被 `dispose`、`config` 里那个开关有没有生效。
+ * 因此返回装配期**已经构造完成**的各槽位产物，而不是让调用方重新跑一遍工厂——重新构造就等于
+ * 测试里又拼了一份，与生产接线脱钩。
+ *
+ * **不包同义方法**：没有 `close()`、没有 `getDatabase()`。`app` 就是原生 `FastifyInstance`，
+ * 关闭就是 `await app.close()`，走同一套八步流程；连接串就是 `env.DATABASE_URL`。多包一层
+ * `close()` 只是在已有接口上再加一个同义名，反而让「用哪个」变成需要记的事。
+ *
+ * **唯一的例外是 `reprovision()`**：它不是现有接口的同义名，生产入口没有对应物——
+ * 「用例之间要一份干净基线」只有测试知道。
+ */
+export interface TestServer<Resources, Config, Clients, Services, Env> {
+    /** 原生 Fastify 实例（已 `ready()`，用 `inject` 发请求；关闭用 `app.close()`） */
+    readonly app: FastifyInstance;
+    /**
+     * 装配后的 env 快照（框架固定约定 + 应用声明的扩展字段 `Env`，`AppEnv<Env>`）。
+     *
+     * **测试断言「连的是哪个库」就看这里**：`env.DATABASE_URL` 在装配前已结算成 `*_test`
+     * 目标，它就是本次实际连的连接串。不额外给一个 `databaseUrl` 字段——同一份事实出现两次，
+     * 迟早会有人读到另一个。应用扩展的 env（如 `REDIS_KEY_PREFIX`）也在这里、且有类型。
+     */
+    readonly env: AppEnv<Env>;
+    /** `resources` 槽位产物（`false` 键已按 `Live<Value>` 剔除） */
+    readonly resources: ResourcesView<Resources>;
+    /** `config` 槽位产物（`Awaited<>` 归一） */
+    readonly config: Awaited<Config>;
+    /** `clients` 槽位产物 */
+    readonly clients: ClientsView<Clients>;
+    /** `services` 槽位产物（已 `init()` 过；测试直接拿它调方法，不 mock） */
+    readonly services: Awaited<Services>;
+    /** 日志器（与 `app.log` 同一个；关闭阶段仍可用） */
+    readonly log: LoggerLike;
+    /**
+     * **重新装配一个新的实例**：清掉旧实例的数据 → 关掉旧实例 → 按同一份 `env` 快照重跑一遍装配。
+     *
+     * 返回的是一份**新对象**，不是原地重启：
+     *
+     * ```ts
+     * let server = await createTestServer(server)
+     * beforeEach(async () => {
+     *   server = await server.reprovision()
+     * })
+     * ```
+     *
+     * 旧对象上的一切（`app` / `resources` / `services`）**已经失效**：连接已断、`app` 已 `close()`。
+     * 还在引用旧实例的 `describe` 报错时不要奇怪——它的名字就叫“旧装配”。
+     *
+     * ## 为什么是「重新装配」而不是「复位」
+     *
+     * 状态有两类，而只有一类能被「复位」：
+     *
+     * | 状态 | 在哪 | 能不能拨回去 |
+     * | --- | --- | --- |
+     * | 库里的行 / 队列 key / 临时文件 | 外部 | 能（`clean()`） |
+     * | 限流桶、进程内缓存、连接级状态 | 内存 | **不能可靠地拨回** |
+     *
+     * 第二类覆盖地方、无法可靠拨回（漏清一处就是偶发红），而重新装配不需要「谁记得清」：
+     * `init()` 重跑一次，内存态天然就是初始值。
+     *
+     * 另一层原因在 Fastify：`ready()` 是一次性的，同一实例上无法重跑注册流程。想「不换实例而重跑
+     * 装配」在结构上就不成立。
+     *
+     * ## 四个步骤（顺序不可换）
+     *
+     * 1. **闸门**：`ENV` 必须可清理（`development` / `test`），否则直接抛错；
+     * 2. **`clean()`**：由 boot 层的 `cleanServerUnits()` 编排——资源声明序逐项清（数据库那个
+     *    必须在最前，它持有 `TRUNCATE`），再服务声明序逐项清；**必须在 `app.close()` 之前**——
+     *    关完之后连接就没了；
+     * 3. **`app.close()`**：走完整八步关闭（逐单元 `dispose()` 会在这里顺带把缓冲落盘）；
+     * 4. **重新装配**：复用同一份 `env` 快照（**不重跑** `prepareTestDatabase()`），重建
+     *    `resources` → `config` → `clients` → `services` → `init()` → 路由 → `ready()` → `loadTestData()`。
+     *
+     * ## 失败语义
+     *
+     * - `clean()` 失败**冒泡**：没清干净就去装配，后面全是伪绿；
+     * - `app.close()` 失败**不阻断**（八步关闭本来就是逐步骤聚合、失败只 `log.error`）：
+     *   旧实例释放不完美不应该阻止下一条用例。
+     *
+     * ## 耗时
+     *
+     * 一次完整装配 = 一次 `setup()` + 一次 `init()`。这是**故意的约束**：`setup()` 必须保持在
+     * 几十毫秒量级（只做连接 / 预执 / 极小的结构检查），跑 `prisma migrate` 这类事归 npm script——
+     * `reprovision()` 是**逐用例**跑的，装配慢就等于整个测试套件慢。
+     */
+    reprovision(): Promise<TestServer<Resources, Config, Clients, Services, Env>>;
+}
+/**
+ * 构造测试对象。
+ *
+ * 固定顺序（安全闸门全部在装配之前，`resources` 一行代码都还没跑）：
+ * ```
+ * prepareTestDatabase()：
+ *   加载 env（强制叠加 .env.test / .env.test.local，ENV 未给时兜底 test）
+ *     → 环境闸门（ENV 必须可清理）
+ *     → 结算测试连接串（显式 TEST_DATABASE_URL 优先，否则派生 +_test，幂等）
+ *     → schema 闸门（必须以 _test 结尾）
+ *     → 回写 process.env.DATABASE_URL
+ * → resources → core → config → clients → services → init() → middlewares
+ *   → 系统路由 → routers → 关闭钩子 → ready()
+ *   → 装载 testdata/ 脚本并整体 load(ctx)
+ * ```
+ *
+ * `testdata/` 的 `load()` 排在 `ready()` 之后：脚本拿到的是装配好的 `ctx`（`env` + `resources` +
+ * `log`），所以它写数据用的就是被测服务读数据的那份连接——两套连接写/读同一张表而看不到对方
+ * 写入（缓存 / 连接级状态）这类问题从结构上不会发生。排在最后也让失败语义最干净：装载失败时
+ * 装配已完成、可正常 `app.close()` 释放。
+ *
+ * 不会再拿应用目标跟测试目标比对：本进程读到的 `DATABASE_URL` 此时已经是测试目标，比对恒等于
+ * 「自比自」。真正拦住「测试清空应用库」的是派生 + schema 闸门——派生只会给 schema 追加
+ * `_test`，schema 闸门只放行 `*_test`，所以测试目标结构上不可能是应用目标。
+ */
+export declare function createTestServer<Resources, Config, Clients, Services, Env>(server: Server<Resources, Config, Clients, Services, Env>): Promise<TestServer<Resources, Config, Clients, Services, Env>>;
+//# sourceMappingURL=test-server.d.ts.map

package/output/core/test-support/test-server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-server.d.ts","sourceRoot":"","sources":["../../../source/core/test-support/test-server.ts"],"names":[],"mappings":"AAoBA,OAAO,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AAEzF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAA;AAE9C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AACH,MAAM,WAAW,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,GAAG;IACnE,kEAAkE;IAClE,QAAQ,CAAC,GAAG,EAAE,eAAe,CAAA;IAC7B;;;;;;OAMG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC,GAAG,CAAC,CAAA;IACzB,qDAAqD;IACrD,QAAQ,CAAC,SAAS,EAAE,aAAa,CAAC,SAAS,CAAC,CAAA;IAC5C,oCAAoC;IACpC,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC,MAAM,CAAC,CAAA;IAChC,qBAAqB;IACrB,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC,OAAO,CAAC,CAAA;IACtC,qDAAqD;IACrD,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAA;IACpC,mCAAmC;IACnC,QAAQ,CAAC,GAAG,EAAE,UAAU,CAAA;IACxB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAmDG;IACH,WAAW,IAAI,OAAO,CAAC,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,GAAG,CAAC,CAAC,CAAA;CAC9E;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAsB,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,GAAG,CAAC,GAAG,OAAO,CAAC,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,GAAG,CAAC,CAAC,CAO3M"}

package/output/core/test-support/test-server.js

@@ -0,0 +1,114 @@
+import { cleanServerUnits, initServiceUnits } from '../boot/lifecycle.js';
+import { buildClients, buildConfig, buildResources, buildServices, createBootContext, installShutdownHook, registerCoreStep, registerMiddlewares, registerRouters, registerSystemRoutesStep, resolveAppEnv, setupResources, } from '../boot/steps.js';
+import { assertCleanableEnvironment } from '../env.js';
+import { maskDatabaseUrl } from './database.js';
+import { prepareTestDatabase } from './environment.js';
+import { discoverTestDataModules, loadTestData } from './testdata.js';
+/**
+ * 构造测试对象。
+ *
+ * 固定顺序（安全闸门全部在装配之前，`resources` 一行代码都还没跑）：
+ * ```
+ * prepareTestDatabase()：
+ *   加载 env（强制叠加 .env.test / .env.test.local，ENV 未给时兜底 test）
+ *     → 环境闸门（ENV 必须可清理）
+ *     → 结算测试连接串（显式 TEST_DATABASE_URL 优先，否则派生 +_test，幂等）
+ *     → schema 闸门（必须以 _test 结尾）
+ *     → 回写 process.env.DATABASE_URL
+ * → resources → core → config → clients → services → init() → middlewares
+ *   → 系统路由 → routers → 关闭钩子 → ready()
+ *   → 装载 testdata/ 脚本并整体 load(ctx)
+ * ```
+ *
+ * `testdata/` 的 `load()` 排在 `ready()` 之后：脚本拿到的是装配好的 `ctx`（`env` + `resources` +
+ * `log`），所以它写数据用的就是被测服务读数据的那份连接——两套连接写/读同一张表而看不到对方
+ * 写入（缓存 / 连接级状态）这类问题从结构上不会发生。排在最后也让失败语义最干净：装载失败时
+ * 装配已完成、可正常 `app.close()` 释放。
+ *
+ * 不会再拿应用目标跟测试目标比对：本进程读到的 `DATABASE_URL` 此时已经是测试目标，比对恒等于
+ * 「自比自」。真正拦住「测试清空应用库」的是派生 + schema 闸门——派生只会给 schema 追加
+ * `_test`，schema 闸门只放行 `*_test`，所以测试目标结构上不可能是应用目标。
+ */
+export async function createTestServer(server) {
+    // 闸门 + 结算测试连接串全在框架内部，顺序不由调用方决定；**不改写全局 process.env**（见
+    // `prepareTestDatabase`）——测试目标只注入到本次装配的 `env` 快照里，`resources` 从
+    // `ctx.env.DATABASE_URL` 读取，同进程并行多个实例互不污染。
+    const env = resolveAppEnv(prepareTestDatabase());
+    return assemble(server, env);
+}
+/**
+ * 一次完整装配（`createTestServer` 与 `reprovision()` 共用）。
+ *
+ * 共用是刻意的：`reprovision()` 走的是**同一条**装配路径，不是「简化版重启」。两条路径一旦
+ * 分叉，测试里跑的就和第一次装配不再是同一件事，`reprovision()` 之后的用例就失去了证明力。
+ *
+ * 入参 `env` 是**已结算好**的快照：`reprovision()` 复用它、不重跑 `prepareTestDatabase()`——
+ * 连接串 / ENV 在一次测试生命周期里不该变，重算只会引入「第二次结算结果不同」的怪异失败。
+ *
+ * 返回的**只有** `TestServer`：装配期单元（`ResourceSetupUnit[]` 之类）是 boot 层的产物，
+ * 只在本函数的闭包里给 `reprovision()` 用，不往测试入口的外面漏。
+ */
+async function assemble(server, env) {
+    // 以下步序与 `startServer` 逐行对应，只去掉 listen 与信号处理器
+    const ctx = createBootContext(server, env);
+    const { resources, units: resourceUnits, classifyResourceError } = await buildResources(ctx);
+    await setupResources(ctx, resourceUnits);
+    await registerCoreStep(ctx, classifyResourceError);
+    await buildConfig(ctx, resources);
+    const clients = await buildClients(ctx, resources);
+    const services = await buildServices(ctx, resources, clients);
+    await initServiceUnits({
+        service: ctx.service,
+        log: ctx.log,
+        services: services,
+    });
+    await registerMiddlewares(ctx, services, clients);
+    registerSystemRoutesStep(ctx, services);
+    await registerRouters(ctx, services, clients);
+    installShutdownHook(ctx, services, resourceUnits);
+    await ctx.app.ready();
+    ctx.log.info({ service: ctx.service, database: maskDatabaseUrl(env.DATABASE_URL), env: env.ENV }, '[test-server] ready（测试实例不会监听端口）');
+    // `buildConfig` 一定跑过（本路径不跳过 config），缺了就按「没有 config」的语义
+    // 如实报错（`read()` 抛 `CONFIG_UNAVAILABLE`），而不是拿 `undefined` 冒充产物。
+    if (!ctx.configAccess.available) {
+        throw new Error('[test-server] config 槽位没有产出：装配顺序被改坏了（应当紧跟 resources 之后）');
+    }
+    // 装载`testdata/` 脚本并整体 `load(ctx)`：闸门（ENV 必须可清理）在 `loadTestData` 内部，
+    // 这里不重复判断，也不降级成「非测试就不算」——失败直接冒泡。
+    //
+    // `ctx` 与 `resources` 槽位同一个口径：脚本写数据 / 清缓存用的就是被测服务的那份实例。
+    const testDataCtx = {
+        env,
+        resources,
+        config: ctx.configAccess.read(),
+        clients,
+        services,
+        log: ctx.log,
+    };
+    // 脚本名单只在本函数的闭包里用：装配时 `load()` 一次就够了。用例之间的复位是
+    // `reprovision()` 的职责（重跑装配 = 重新发现 + 重新 `load`），返回值不需要把它挂在外面。
+    const testData = await discoverTestDataModules();
+    await loadTestData({ ctx: testDataCtx, units: testData, service: ctx.service });
+    return {
+        app: ctx.app,
+        env,
+        resources,
+        config: ctx.configAccess.read(),
+        clients,
+        services,
+        log: ctx.log,
+        reprovision: async () => {
+            // 1. 闸门先于一切：非可清理环境下连 `clean()` 都不该跑
+            assertCleanableEnvironment(env.ENV);
+            // 2. 清数据**必须在 `close()` 之前**：连接一断就清不了了。顺序由 boot 层编排
+            //    （资源在前、服务在后），本入口只说「给我一份干净基线」。失败冒泡——
+            //    没清干净就重装，后面全是伪绿。
+            await cleanServerUnits({ service: ctx.service, log: ctx.log, resources: resourceUnits, services: services });
+            // 3. 关掉旧实例：八步关闭自带逐单元 `dispose()`（缓冲落盘的归属就是它），
+            //    失败只 `log.error`、不阻断——旧实例释放不完美不该拦住下一条用例。
+            await ctx.app.close();
+            // 4. 用同一份 `env` 快照重新装配（内部照常 `loadTestData`）
+            return assemble(server, env);
+        },
+    };
+}

package/output/core/test-support/test-server.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=test-server.test.d.ts.map

package/output/core/test-support/test-server.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-server.test.d.ts","sourceRoot":"","sources":["../../../source/core/test-support/test-server.test.ts"],"names":[],"mappings":""}