@taicode/common-server 4.0.0-beta.2 → 4.0.0-beta.4

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

@@ -0,0 +1,94 @@
+import type { ConfigEnv } from '../env.js';
+import type { 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()`、没有 `reset()`。`app` 就是原生
+ * `FastifyInstance`，关闭就是 `await app.close()`，走同一套七步流程；连接串就是
+ * `env.DATABASE_URL`。多包一层 `close()` 只是在已有接口上再加一个同义名，反而让「用哪个」变成
+ * 需要记的事。
+ */
+export interface TestServer<R, C, CL, S> {
+    /** 原生 Fastify 实例（已 `ready()`，用 `inject` 发请求；关闭用 `app.close()`） */
+    readonly app: FastifyInstance;
+    /**
+     * 装配后的固定约定 env。
+     *
+     * **测试断言「连的是哪个库」就看这里**：`env.DATABASE_URL` 在装配前已被改写成
+     * `*_test` 目标，它就是本次实际连的连接串。不额外给一个 `databaseUrl` 字段——
+     * 同一份事实出现两次，迟早会有人读到另一个。
+     */
+    readonly env: ConfigEnv;
+    /** `resources` 槽位产物（`false` 键已按 `Live<T>` 剔除） */
+    readonly resources: ResourcesView<R>;
+    /** `config` 槽位产物（`Awaited<>` 归一） */
+    readonly config: Awaited<C>;
+    /** `clients` 槽位产物 */
+    readonly clients: ClientsView<CL>;
+    /** `services` 槽位产物（已 `init()` 过；测试直接拿它调方法，不 mock） */
+    readonly services: Awaited<S>;
+    /** 日志器（与 `app.log` 同一个；关闭阶段仍可用） */
+    readonly log: LoggerLike;
+}
+/**
+ * 构造测试对象。
+ *
+ * 固定顺序（安全闸门全部在装配之前，`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()
+ * ```
+ *
+ * 不会再拿应用目标跟测试目标比对：本进程读到的 `DATABASE_URL` 此时已经是测试目标，比对恒等于
+ * 「自比自」。真正拦住「测试清空应用库」的是派生 + schema 闸门——派生只会给 schema 追加
+ * `_test`，schema 闸门只放行 `*_test`，所以测试目标结构上不可能是应用目标。
+ */
+export declare function createTestServer<R, C, CL, S>(server: Server<R, C, CL, S>): Promise<TestServer<R, C, CL, S>>;
+//# 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":"AAgBA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAA;AAC1C,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AACjF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAA;AAE9C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,MAAM,WAAW,UAAU,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC;IACrC,kEAAkE;IAClE,QAAQ,CAAC,GAAG,EAAE,eAAe,CAAA;IAC7B;;;;;;OAMG;IACH,QAAQ,CAAC,GAAG,EAAE,SAAS,CAAA;IACvB,iDAAiD;IACjD,QAAQ,CAAC,SAAS,EAAE,aAAa,CAAC,CAAC,CAAC,CAAA;IACpC,oCAAoC;IACpC,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,CAAA;IAC3B,qBAAqB;IACrB,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC,EAAE,CAAC,CAAA;IACjC,qDAAqD;IACrD,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC,CAAC,CAAA;IAC7B,mCAAmC;IACnC,QAAQ,CAAC,GAAG,EAAE,UAAU,CAAA;CACzB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,gBAAgB,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC,CA8CjH"}

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

@@ -0,0 +1,60 @@
+import { initServiceUnits } from '../boot/lifecycle.js';
+import { buildClients, buildConfig, buildResources, buildServices, createBootContext, installShutdownHook, registerCoreStep, registerMiddlewares, registerRouters, registerSystemRoutesStep, } from '../boot/steps.js';
+import { maskDatabaseUrl } from './database.js';
+import { prepareTestDatabase } from './environment.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()
+ * ```
+ *
+ * 不会再拿应用目标跟测试目标比对：本进程读到的 `DATABASE_URL` 此时已经是测试目标，比对恒等于
+ * 「自比自」。真正拦住「测试清空应用库」的是派生 + schema 闸门——派生只会给 schema 追加
+ * `_test`，schema 闸门只放行 `*_test`，所以测试目标结构上不可能是应用目标。
+ */
+export async function createTestServer(server) {
+    // 闸门 + 结算 + 改写全在框架内部，顺序不由调用方决定
+    const env = prepareTestDatabase();
+    // 以下步序与 `startServer` 逐行对应，只去掉 listen 与信号处理器
+    const ctx = createBootContext(server, env);
+    const { resources, classifyResourceError } = await buildResources(ctx);
+    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);
+    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 之后）');
+    }
+    const app = ctx.app;
+    return {
+        app,
+        env,
+        resources,
+        config: ctx.configAccess.read(),
+        clients,
+        services,
+        log: ctx.log
+    };
+}

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":""}

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

@@ -0,0 +1,162 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { defineServer } from '../entries.js';
+import { routerSchema } from '../modules/schema/builders.js';
+import { createTestServer } from './test-server.js';
+const IDENTITY = { service: 'probe', title: 'Probe', version: '0.0.0' };
+const ROUTE_SCHEMA = routerSchema({
+    operationId: 'probeGet',
+    summary: '探测',
+    description: '探测路由',
+    tags: ['探测'],
+});
+const APP_URL = 'postgresql://postgres:secret@db.internal:5432/taicode-labs?schema=probe';
+const TEST_URL = 'postgresql://postgres:secret@db.internal:5432/taicode-labs?schema=probe_test';
+const ORIGINAL_ENV = { ...process.env };
+afterEach(() => {
+    process.env = { ...ORIGINAL_ENV };
+});
+function buildServer(seen = {}) {
+    return defineServer({
+        app: IDENTITY,
+        resources: (ctx) => {
+            seen.databaseUrl = ctx.env.DATABASE_URL;
+            seen.env = ctx.env.ENV;
+            return {};
+        },
+        config: () => ({ server: { cookieNames: ['token'] } }),
+        clients: () => ({}),
+        services: () => ({}),
+        middlewares: () => ({}),
+        routers: ({ app }) => {
+            app.get('/probe', { schema: ROUTE_SCHEMA }, async () => ({ ok: true }));
+        },
+    });
+}
+/** 把 vitest 自己设的环境变量清干净，让每个用例只看到自己注入的值 */
+function useEnv(overrides) {
+    process.env.ENV = 'development';
+    // 注意：给 process.env 赋 undefined 会变成字符串 "undefined"，所以必须先 delete
+    delete process.env.DATABASE_URL;
+    delete process.env.TEST_DATABASE_URL;
+    process.env.LOG_LEVEL = 'silent';
+    for (const [key, value] of Object.entries(overrides)) {
+        if (value === undefined) {
+            delete process.env[key];
+        }
+        else {
+            process.env[key] = value;
+        }
+    }
+}
+describe('createTestServer', () => {
+    it('与 startServer 装配同一套处理链：系统路由 + 业务路由 + zod 序列化 + 成功信封', async () => {
+        useEnv({ DATABASE_URL: APP_URL });
+        const testServer = await createTestServer(buildServer());
+        const response = await testServer.app.inject({ method: 'GET', url: '/probe' });
+        expect(response.statusCode).toBe(200);
+        // 信封形状来自框架 core/response，而不是测试自己拼的一份
+        expect(response.json()).toEqual({ status: 'SUCCESS', message: 'ok', data: { ok: true } });
+        // 框架系统路由同样就位
+        expect((await testServer.app.inject({ method: 'GET', url: '/health' })).statusCode).toBe(200);
+        await testServer.app.close();
+    });
+    it('数据层被强制指向 *_test（resources 拿到的 DATABASE_URL 已改写）', async () => {
+        useEnv({ DATABASE_URL: APP_URL });
+        const seen = {};
+        const testServer = await createTestServer(buildServer(seen));
+        expect(seen.databaseUrl).toContain('schema=probe_test');
+        expect(process.env.DATABASE_URL).toContain('schema=probe_test');
+        // 交出来的连接串就是「测试实际连的那个」，不是从 process.env 再推一遍
+        expect(testServer.env.DATABASE_URL).toBe(seen.databaseUrl);
+        await testServer.app.close();
+    });
+    it('显式 TEST_DATABASE_URL 优先于派生', async () => {
+        useEnv({
+            DATABASE_URL: APP_URL,
+            TEST_DATABASE_URL: TEST_URL.replace('probe_test', 'explicit_test'),
+        });
+        const seen = {};
+        const testServer = await createTestServer(buildServer(seen));
+        expect(seen.databaseUrl).toContain('schema=explicit_test');
+        await testServer.app.close();
+    });
+    it('不监听端口（测试用 inject，占端口会让重跑互相踩）', async () => {
+        useEnv({ DATABASE_URL: APP_URL });
+        const testServer = await createTestServer(buildServer());
+        expect(testServer.app.server.listening).toBe(false);
+        await testServer.app.close();
+    });
+    it('env 强制加载测试层：ENV 没人给时兜底成 test（不用调用方额外声明）', async () => {
+        useEnv({ DATABASE_URL: APP_URL, ENV: undefined });
+        const seen = {};
+        const testServer = await createTestServer(buildServer(seen));
+        expect(seen.env).toBe('test');
+        await testServer.app.close();
+    });
+    it('环境闸门：非可清理环境在装配之前就失败（resources 一次都没跑）', async () => {
+        useEnv({ DATABASE_URL: APP_URL, ENV: 'production' });
+        const onResources = vi.fn(buildServer().resources);
+        const server = defineServer({ ...buildServer(), resources: onResources });
+        await expect(createTestServer(server)).rejects.toThrow(/ENV="production"/);
+        expect(onResources).not.toHaveBeenCalled();
+    });
+    it('schema 闸门：目标不以 *_test 结尾时拒绝装配', async () => {
+        useEnv({ DATABASE_URL: APP_URL, TEST_DATABASE_URL: APP_URL });
+        const onResources = vi.fn(buildServer().resources);
+        const server = defineServer({ ...buildServer(), resources: onResources });
+        await expect(createTestServer(server)).rejects.toThrow(/必须以 _test 结尾/);
+        expect(onResources).not.toHaveBeenCalled();
+    });
+    it('关闭时走同一套七步流程（services 的 dispose 被调用）', async () => {
+        useEnv({ DATABASE_URL: APP_URL });
+        const onDispose = vi.fn();
+        const server = defineServer({
+            ...buildServer(),
+            services: () => ({ unit: { dispose: onDispose } }),
+        });
+        const testServer = await createTestServer(server);
+        await testServer.app.close();
+        expect(onDispose).toHaveBeenCalledTimes(1);
+    });
+    it('业务路由缺少 schema 时注册即失败（守卫在测试入口同样生效）', async () => {
+        useEnv({ DATABASE_URL: APP_URL });
+        const server = defineServer({
+            ...buildServer(),
+            routers: ({ app }) => {
+                app.get('/bad', async () => ({ ok: true }));
+            },
+        });
+        await expect(createTestServer(server)).rejects.toThrow(/GET \/bad 缺少 schema/);
+    });
+    it('返回装配产物本身：resources / config / clients / services 与槽位一一对应', async () => {
+        useEnv({ DATABASE_URL: APP_URL });
+        const resources = { cache: { get: () => undefined } };
+        const config = { server: { cookieNames: ['token'] } };
+        const clients = { account: { verify: async () => true } };
+        const services = { user: { name: () => 'user' } };
+        const testServer = await createTestServer(defineServer({
+            app: IDENTITY,
+            resources: () => resources,
+            config: () => config,
+            clients: () => clients,
+            services: () => services,
+            middlewares: () => ({}),
+            routers: () => { },
+        }));
+        // 装配产物直接交出来：测试能断言/操作它们本身，而不是再构造一份副本。
+        // `resources` / `clients` 经过 `Live<T>` 视图（剔 `false` 键），所以按值比较；
+        // `config` / `services` 就是槽位原始返回值，引用相同。
+        expect(testServer.resources).toEqual(resources);
+        expect(testServer.clients).toEqual(clients);
+        expect(testServer.config).toBe(config);
+        expect(testServer.services).toBe(services);
+        // env 是**改写后**的快照（resources 看到的就是它）
+        expect(testServer.env.DATABASE_URL).toContain('schema=probe_test');
+        await testServer.app.close();
+    });
+    it('只有定义一个参数：没有「半个生产」的配置入口', () => {
+        // 签名只有一个必填参数。这条断言盯着「别再加 options」——一旦加了，测试就能绕开
+        // 生产接线，本入口随即失去证明力。
+        expect(createTestServer.length).toBe(1);
+    });
+});

package/output/{app → core}/type-augment.d.ts

@@ -4,7 +4,7 @@
  * `request.user` / `request.token` / `request.id` 与 `routeOptions.config.accessControls`（以及
  * 限流规则 `rateLimit`）的 `declare module 'fastify'` 由 common 统一提供，各仓删除自建声明。
  */
-import type { RequestContext } from '../context/index.js';
+import type { RequestContext } from './modules/context/index.js';
 /** 路由级访问控制声明（各服务在 `routeOptions.config.accessControls` 里写） */
 export type AccessControl = 'NoLoginRequired' | 'IgnorePermission' | 'RequiredSecurityCode';
 /** 路由级限流规则（`createRateLimitMiddleware` 消费，另有路由级 `config.rateLimit`） */
@@ -21,7 +21,7 @@ declare module 'fastify' {
         user?: unknown;
         /** 认证后由 `auth` 中间件填充 */
         token?: unknown;
-        /** `createContextMiddleware()` 注入的请求级上下文 */
+        /** 由 core 固定注入的请求级上下文（`registerRequestContext`） */
         ctx?: RequestContext;
     }
     interface FastifyContextConfig {

package/output/core/type-augment.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"type-augment.d.ts","sourceRoot":"","sources":["../../source/core/type-augment.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAA;AAEhE,8DAA8D;AAC9D,MAAM,MAAM,aAAa,GAAG,iBAAiB,GAAG,kBAAkB,GAAG,sBAAsB,CAAA;AAE3F,uEAAuE;AACvE,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAA;IACb,cAAc;IACd,MAAM,EAAE,MAAM,CAAA;IACd,wBAAwB;IACxB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAA;CAChB;AAED,OAAO,QAAQ,SAAS,CAAC;IACvB,UAAU,cAAc;QACtB,wBAAwB;QACxB,IAAI,CAAC,EAAE,OAAO,CAAA;QACd,wBAAwB;QACxB,KAAK,CAAC,EAAE,OAAO,CAAA;QACf,mDAAmD;QACnD,GAAG,CAAC,EAAE,cAAc,CAAA;KACrB;IAED,UAAU,oBAAoB;QAC5B,+EAA+E;QAC/E,cAAc,CAAC,EAAE,aAAa,EAAE,CAAA;QAChC,cAAc;QACd,SAAS,CAAC,EAAE,aAAa,CAAA;KAC1B;CACF"}