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

package/output/core/entries.test.js

@@ -0,0 +1,458 @@
+import { beforeAll, describe, expect, it, vi } from 'vitest';
+import { createAuthMiddleware } from '../auth/index.js';
+import { defineServer, generateOpenApi, startServer } from './entries.js';
+import { routerSchema } from './modules/schema/builders.js';
+import { defineResource } from './resource.js';
+const IDENTITY = { service: 'probe', title: 'Probe', version: '0.0.0' };
+const ROUTE_SCHEMA = routerSchema({
+    operationId: 'probeGet',
+    summary: '探测',
+    description: '探测路由',
+    tags: ['探测'],
+});
+/**
+ * 出 spec 用的定义：`config` 工厂**故意抛错**、`middlewares` 工厂记调用次数。
+ *
+ * 两者都能跑通就证明：出 spec 路径**既不需要配置有效**，**也不装配任何中间件**
+ * （它的文档只取决于路由声明 + zod 转换）。
+ */
+function buildServer(registerPermissionOperations, onMiddlewares = vi.fn()) {
+    return defineServer({
+        app: IDENTITY,
+        resources: () => ({}),
+        config: () => {
+            throw new Error('config 不应在出 spec 路径被调用');
+        },
+        clients: () => ({}),
+        services: () => ({}),
+        middlewares: (ctx) => {
+            onMiddlewares();
+            return [
+                createAuthMiddleware(ctx, {
+                    client: { verify: async () => ({ user: {}, token: 't' }), registerPermissionOperations },
+                }),
+            ];
+        },
+        routers: ({ app }) => {
+            app.get('/probe', { schema: ROUTE_SCHEMA }, async () => ({ ok: true }));
+        },
+    });
+}
+/** 启动用的定义：`config` 正常返回值（`startServer` 会跑它）。 */
+function buildStartableServer(registerPermissionOperations) {
+    return defineServer({
+        app: IDENTITY,
+        resources: () => ({}),
+        config: () => ({ server: { cookieNames: ['token'] } }),
+        clients: () => ({}),
+        services: () => ({}),
+        middlewares: (ctx) => [
+            createAuthMiddleware(ctx, {
+                client: { verify: async () => ({ user: {}, token: 't' }), registerPermissionOperations },
+            }),
+        ],
+        routers: ({ app }) => {
+            app.get('/probe', { schema: ROUTE_SCHEMA }, async () => ({ ok: true }));
+        },
+    });
+}
+describe('generateOpenApi', () => {
+    it('产出完整文档（含框架系统路由与业务路由）', async () => {
+        const spec = await generateOpenApi(buildServer(async () => { }));
+        expect(Object.keys(spec.paths ?? {})).toEqual(expect.arrayContaining(['/', '/health', '/system/openapi', '/system/info', '/probe']));
+        expect(spec.info).toEqual({ title: 'Probe', version: '0.0.0' });
+        expect(spec.openapi).toBe('3.0.3');
+    });
+    it('不向鉴权提供方提交权限目录（构建期不产生写操作）', async () => {
+        const registerPermissionOperations = vi.fn(async () => { });
+        await generateOpenApi(buildServer(registerPermissionOperations));
+        expect(registerPermissionOperations).not.toHaveBeenCalled();
+    });
+    it('不装配中间件（文档只取决于路由声明，副作用随之消失）', async () => {
+        const onMiddlewares = vi.fn();
+        await generateOpenApi(buildServer(async () => { }, onMiddlewares));
+        // `auth` 单元在出文档路径里压根不会被构造——这是「不向鉴权方写数据」的根因，
+        // 而不是靠某个入口标记把它关掉。
+        expect(onMiddlewares).not.toHaveBeenCalled();
+    });
+    it('不构造 resources / config / clients / services（文档不来自它们，构造它们只为了跑服务）', async () => {
+        const onResources = vi.fn();
+        const onServices = vi.fn();
+        const onClients = vi.fn();
+        const server = defineServer({
+            app: IDENTITY,
+            resources: () => {
+                onResources();
+                return {};
+            },
+            config: () => {
+                throw new Error('config 不应在出 spec 路径被调用');
+            },
+            clients: () => {
+                onClients();
+                return {};
+            },
+            services: () => {
+                onServices();
+                return {};
+            },
+            middlewares: () => [],
+            routers: ({ app }) => {
+                app.get('/probe', { schema: ROUTE_SCHEMA }, async () => ({ ok: true }));
+            },
+        });
+        const spec = await generateOpenApi(server);
+        expect(onResources).not.toHaveBeenCalled();
+        expect(onClients).not.toHaveBeenCalled();
+        expect(onServices).not.toHaveBeenCalled();
+        // 传的是空 services 占位，路由仍能正常注册并进入文档
+        expect(Object.keys(spec.paths ?? {})).toContain('/probe');
+    });
+    it('不跑 config 槽位（出 spec 不要求配置有效）', async () => {
+        // `config` 工厂本身就会抛错，能出 spec 即证明它没被调用
+        await expect(generateOpenApi(buildServer(async () => { }))).resolves.toBeDefined();
+    });
+    it('不监听端口（不占用 API_PORT）', async () => {
+        const spec = await generateOpenApi(buildServer(async () => { }));
+        expect(spec.servers).toEqual([{ url: '/' }]);
+    });
+    it('业务路由违反 schema 契约时出 spec 直接失败（不给漏声明留活路）', async () => {
+        const server = defineServer({
+            app: IDENTITY,
+            resources: () => ({}),
+            config: () => ({}),
+            clients: () => ({}),
+            services: () => ({}),
+            middlewares: () => [],
+            routers: ({ app }) => {
+                // 故意不声明 schema，验证运行期守卫
+                app.get('/bad', async () => ({ ok: true }));
+            },
+        });
+        await expect(generateOpenApi(server)).rejects.toThrow(/GET \/bad 缺少 schema/);
+    });
+});
+describe('startServer', () => {
+    // 入口一定 listen，所以这里要一个合法端口：`0` 让内核分配空闲端口，测试不抢固定端口
+    beforeAll(() => {
+        process.env.API_PORT = '0';
+    });
+    it('运行期照常提交权限目录（与出 spec 入口相反）', async () => {
+        const registerPermissionOperations = vi.fn(async () => { });
+        const app = await startServer(buildStartableServer(registerPermissionOperations));
+        // `startServer` 的契约就是「一定 listen」：端口交给内核分配（`API_PORT=0`），不靠开关
+        expect(app.server.listening).toBe(true);
+        // startServer 内部已 `ready()`，钩子应在返回前执行完
+        expect(registerPermissionOperations).toHaveBeenCalledTimes(1);
+        const [payload] = registerPermissionOperations.mock.calls[0];
+        expect(payload.service).toBe('probe');
+        expect(payload.version).toBe('0.0.0');
+        expect(payload.operations.map((item) => item.operation)).toEqual(expect.arrayContaining(['probeGet', 'getOpenApiDocument']));
+        await app.close();
+    });
+    it('clients 在 config 之后、services 之前构造，并被 services / middlewares / routers 共享同一实例', async () => {
+        const order = [];
+        const seen = {};
+        const server = defineServer({
+            app: IDENTITY,
+            resources: () => ({}),
+            config: () => {
+                order.push('config');
+                return { account: { serviceUrl: 'https://account.invalid' } };
+            },
+            clients: (ctx) => {
+                order.push('clients');
+                // 客户端地址来自业务配置（不是 env）——这正是它不能放进 resources 的原因
+                return { account: { baseUrl: ctx.config.account.serviceUrl } };
+            },
+            services: (ctx) => {
+                order.push('services');
+                // 两个 service 拿到的是**同一份**客户端实例：services 之间禁止互依，只能靠这一层共享
+                seen.serviceFirst = ctx.clients.account;
+                seen.serviceSecond = ctx.clients.account;
+                return {};
+            },
+            middlewares: (ctx) => {
+                seen.middleware = ctx.clients.account;
+                return [];
+            },
+            routers: (ctx) => {
+                order.push('routers');
+                seen.router = ctx.clients.account;
+                ctx.app.get('/probe', { schema: ROUTE_SCHEMA }, async () => ({ ok: true }));
+            },
+        });
+        const app = await startServer(server);
+        expect(order).toEqual(['config', 'clients', 'services', 'routers']);
+        expect(seen.serviceFirst).toEqual({ baseUrl: 'https://account.invalid' });
+        expect(seen.serviceSecond).toBe(seen.serviceFirst);
+        expect(seen.middleware).toBe(seen.serviceFirst);
+        expect(seen.router).toBe(seen.serviceFirst);
+        await app.close();
+    });
+    it('clients 阶段在 services 之后关闭（服务 dispose 时外部客户端仍可用）', async () => {
+        const order = [];
+        const server = defineServer({
+            app: IDENTITY,
+            resources: () => ({}),
+            config: () => ({}),
+            clients: (ctx) => {
+                ctx.disposer.add(() => {
+                    order.push('clients');
+                });
+                return {};
+            },
+            services: (ctx) => {
+                ctx.disposer.add(() => {
+                    order.push('services');
+                });
+                return {};
+            },
+            middlewares: () => [],
+            routers: () => { },
+        });
+        const app = await startServer(server);
+        await app.close();
+        expect(order).toEqual(['services', 'clients']);
+    });
+    it('middlewares 按**数组顺序**注册（顺序即书写顺序，不受键名影响）', async () => {
+        const order = [];
+        const unit = (name) => ({ name, register: () => { order.push(name); } });
+        const server = defineServer({
+            app: IDENTITY,
+            resources: () => ({}),
+            config: () => ({}),
+            services: () => ({}),
+            // 故意用「纯数字会被对象重排」的反例命名，证明数组顺序不被引擎重排
+            middlewares: () => [unit('2-first'), unit('1-second'), unit('cors')],
+            routers: ({ app }) => {
+                app.get('/probe', { schema: ROUTE_SCHEMA }, async () => ({ ok: true }));
+            },
+        });
+        const app = await startServer(server);
+        expect(order).toEqual(['2-first', '1-second', 'cors']);
+        await app.close();
+    });
+    it('裸注册函数也能进数组（框架补占位名）', async () => {
+        let called = false;
+        const server = defineServer({
+            app: IDENTITY,
+            resources: () => ({}),
+            config: () => ({}),
+            services: () => ({}),
+            middlewares: () => [() => { called = true; }],
+            routers: ({ app }) => {
+                app.get('/probe', { schema: ROUTE_SCHEMA }, async () => ({ ok: true }));
+            },
+        });
+        const app = await startServer(server);
+        expect(called).toBe(true);
+        await app.close();
+    });
+    it('clients 槽位可省略（CL 退化为空，services/middlewares/routers 照常）', async () => {
+        const server = defineServer({
+            app: IDENTITY,
+            resources: () => ({}),
+            config: () => ({}),
+            // 不写 clients
+            services: () => ({}),
+            middlewares: () => [],
+            routers: ({ app }) => {
+                app.get('/probe', { schema: ROUTE_SCHEMA }, async () => ({ ok: true }));
+            },
+        });
+        const app = await startServer(server);
+        const res = await app.inject({ method: 'GET', url: '/probe' });
+        expect(res.statusCode).toBe(200);
+        await app.close();
+    });
+    it('env 扩展：手写首位泛型 Env 即可（defineServer<Env>({...})），值取内置加载后的 process.env（框架不提供自定义加载）', async () => {
+        const seen = {};
+        // 内置加载逻辑把它读进来；应用只在泛型上声明类型，不参与加载
+        process.env.SERVICE_TOKEN = 'from-process-env';
+        // Env 排泛型首位 → 可单独手写；ctx.env 随之带上 SERVICE_TOKEN 的类型
+        const server = defineServer({
+            app: IDENTITY,
+            resources: (ctx) => {
+                seen.fromResources = ctx.env.SERVICE_TOKEN;
+                return {};
+            },
+            config: (ctx) => {
+                // config 的 ctx.env 同样带上了扩展类型
+                seen.fromConfig = ctx.env.SERVICE_TOKEN;
+                return {};
+            },
+            services: () => ({}),
+            middlewares: () => [],
+            routers: ({ app }) => {
+                app.get('/probe', { schema: ROUTE_SCHEMA }, async () => ({ ok: true }));
+            },
+        });
+        const app = await startServer(server);
+        expect(seen.fromResources).toBe('from-process-env');
+        expect(seen.fromConfig).toBe(seen.fromResources);
+        delete process.env.SERVICE_TOKEN;
+        await app.close();
+    });
+});
+describe('resources 单元生命周期（setup / dispose）', () => {
+    /** 造一个「记录调用」的资源单元 */
+    function probeResource(order, name, lifecycle = {}) {
+        const { setup = true, dispose = true } = lifecycle;
+        const client = { name };
+        return defineResource(client, {
+            ...(setup ? { setup: () => { order.push(`setup:${name}`); } } : {}),
+            ...(dispose ? { dispose: () => { order.push(`dispose:${name}`); } } : {}),
+        });
+    }
+    it('setup 在 resources 之后、config 之前，逐项按声明序执行', async () => {
+        const order = [];
+        const server = defineServer({
+            app: IDENTITY,
+            resources: () => {
+                order.push('resources');
+                return { first: probeResource(order, 'first'), second: probeResource(order, 'second') };
+            },
+            config: () => {
+                order.push('config');
+                return {};
+            },
+            services: () => ({}),
+            middlewares: () => [],
+            routers: () => { },
+        });
+        const app = await startServer(server);
+        expect(order).toEqual(['resources', 'setup:first', 'setup:second', 'config']);
+        await app.close();
+    });
+    it('消费方拿到的是解包后的值，不是单元外壳', async () => {
+        const order = [];
+        let seen;
+        const server = defineServer({
+            app: IDENTITY,
+            resources: () => ({ database: probeResource(order, 'database') }),
+            config: (ctx) => {
+                seen = ctx.resources.database;
+                return {};
+            },
+            services: () => ({}),
+            middlewares: () => [],
+            routers: () => { },
+        });
+        const app = await startServer(server);
+        // 看到的是裸 client（`{ name: 'database' }`），没有 `value` / `setup` 外壳
+        expect(seen).toEqual({ name: 'database' });
+        await app.close();
+    });
+    it('裸对象（无单元外壳）照旧可用，不产生 setup / dispose 调用', async () => {
+        const order = [];
+        const server = defineServer({
+            app: IDENTITY,
+            resources: () => ({ bare: { name: 'bare' } }),
+            config: () => ({ picked: true }),
+            services: () => ({}),
+            middlewares: () => [],
+            routers: () => { },
+        });
+        const app = await startServer(server);
+        await app.close();
+        expect(order).toEqual([]);
+    });
+    it('setup 在每次装配时都跑（不做一次性记忆，迁移本身靠状态判定）', async () => {
+        const order = [];
+        const server = defineServer({
+            app: IDENTITY,
+            resources: () => ({ database: probeResource(order, 'database', { dispose: false }) }),
+            config: () => ({}),
+            services: () => ({}),
+            middlewares: () => [],
+            routers: () => { },
+        });
+        const first = await startServer(server);
+        await first.close();
+        const second = await startServer(server);
+        await second.close();
+        expect(order).toEqual(['setup:database', 'setup:database']);
+    });
+    it('setup 抛错时装配中断（config 不跑），错误冒泡给入口', async () => {
+        const order = [];
+        const server = defineServer({
+            app: IDENTITY,
+            resources: () => ({
+                database: defineResource({ name: 'database' }, {
+                    setup: () => {
+                        throw new Error('migrate failed');
+                    },
+                }),
+            }),
+            config: () => {
+                order.push('config');
+                return {};
+            },
+            services: () => ({}),
+            middlewares: () => [],
+            routers: () => { },
+        });
+        await expect(startServer(server)).rejects.toThrow(/migrate failed/);
+        expect(order).toEqual([]);
+    });
+    it('dispose 按声明序**逆序**执行，排在 flushResources（disposer）之前', async () => {
+        const order = [];
+        const server = defineServer({
+            app: IDENTITY,
+            resources: (ctx) => {
+                ctx.disposer.add(() => {
+                    order.push('disposer:resources');
+                });
+                return { first: probeResource(order, 'first'), second: probeResource(order, 'second') };
+            },
+            config: () => ({}),
+            services: () => ({}),
+            middlewares: () => [],
+            routers: () => { },
+        });
+        const app = await startServer(server);
+        order.length = 0;
+        await app.close();
+        expect(order).toEqual(['dispose:second', 'dispose:first', 'disposer:resources']);
+    });
+    it('单个资源 dispose 失败不阻断其他资源（同阶段语义）', async () => {
+        const order = [];
+        const server = defineServer({
+            app: IDENTITY,
+            resources: () => ({
+                broken: defineResource({ name: 'broken' }, {
+                    dispose: () => {
+                        throw new Error('disconnect failed');
+                    },
+                }),
+                healthy: probeResource(order, 'healthy', { setup: false }),
+            }),
+            config: () => ({}),
+            services: () => ({}),
+            middlewares: () => [],
+            routers: () => { },
+        });
+        const app = await startServer(server);
+        await expect(app.close()).resolves.toBeUndefined();
+        // 逆序：healthy 先于 broken；broken 抛错被吞，healthy 已经跑过
+        expect(order).toEqual(['dispose:healthy']);
+    });
+    it('出 spec 路径既不构造 resources，也不跑 setup', async () => {
+        const onSetup = vi.fn();
+        const server = defineServer({
+            app: IDENTITY,
+            resources: () => ({ database: defineResource({ name: 'database' }, { setup: onSetup }) }),
+            config: () => {
+                throw new Error('config 不应在出 spec 路径被调用');
+            },
+            services: () => ({}),
+            middlewares: () => [],
+            routers: ({ app }) => {
+                app.get('/probe', { schema: ROUTE_SCHEMA }, async () => ({ ok: true }));
+            },
+        });
+        await generateOpenApi(server);
+        expect(onSetup).not.toHaveBeenCalled();
+    });
+});

package/output/core/env.d.ts

@@ -0,0 +1,83 @@
+/** `LOG_LEVEL` 未设置时的默认级别（设计 §3.1 ① / §5.1 `logging`） */
+export declare const DEFAULT_LOG_LEVEL = "info";
+/**
+ * 允许执行**破坏性 / 不可逆**操作的环境（`ENV` 取值）。
+ *
+ * 覆盖两类动作，两者共用同一份判定：
+ *
+ * - 测试数据库清理（`assertTestDatabaseSchema` 那道闸门的同伴）；
+ * - `testdata/` 脚本的 `load()` / `cleanup()`（`test-support/testdata.ts`）。
+ *
+ * `development` 是本地开发，`test` 是 vitest 入口显式声明的环境开关。除此之外一律拒绝——
+ * 只看 `NODE_ENV`、CI 标志或变量名都不构成证明：`NODE_ENV=test` 完全可能连着生产库。
+ */
+export declare const CLEANABLE_ENVS: readonly string[];
+/**
+ * 环境闸门：非可清理环境立即失败。
+ *
+ * **不在分支里「跳过清理」**——把破坏性动作降级成静默 no-op，会让同一份代码在生产和测试里
+ * 走两条不同的路径，测试结果随即失去意义。要禁就整体失败。
+ *
+ * 报错必须带上当前值：漏配 `ENV` 时的症状否则会变成「莫名其妙不许跑」。
+ */
+export declare function assertCleanableEnvironment(env: string): void;
+/**
+ * 框架在配置前固定加载的 env（N2 §2.2）。
+ *
+ * 只读固定约定值：`ENV` / `API_PORT` / `LOG_LEVEL` / `DATABASE_URL` / `REDIS_URL`；
+ * `debug` 由 `ENV === 'development'` 派生；**绝不回退 `PORT`**（`PORT` 属 nginx）。
+ *
+ * **不给索引签名**：访问 `env.XXX` 拼错即编译错误。各仓若有额外 env，不扩展这个类型 ——
+ * 走 `process.env.XXX`（在 `resources(ctx)` 里读），框架不背书。
+ */
+export interface ConfigEnv {
+    /** 运行环境标记；`debug` 由 `ENV === 'development'` 派生 */
+    ENV: string;
+    /** 监听端口；**只读 `API_PORT`，绝不回退 `PORT`** */
+    API_PORT: string;
+    /** 日志级别；默认 `info` */
+    LOG_LEVEL: string;
+    /** 数据层连接串（`resources` 只读它构造数据层客户端） */
+    DATABASE_URL: string;
+    /** Redis 连接串；缺省 → redis 资源为 `undefined` */
+    REDIS_URL?: string;
+}
+/** 读取固定 env（不加载文件）；入口会先 `loadEnvironment()` 再调用本函数 */
+export declare function resolveConfigEnv(): ConfigEnv;
+/**
+ * env 加载模式：
+ *
+ * - `runtime`（默认）`startServer` 与工具进程用：三层开发分层，`ENV=test` 时再叠测试层。
+ * - `test` 测试入口用：**无条件**叠测试层，且三/五层都没给出 `ENV` 时兜底成 `test`。
+ */
+export type EnvironmentMode = 'runtime' | 'test';
+/** `loadEnvironment()` 的选项 */
+export interface LoadEnvironmentOptions {
+    mode?: EnvironmentMode;
+}
+/**
+ * 加载 env 文件并在加载后返回固定约定值。
+ *
+ * **这是 env 的唯一出口**：层名、顺序、覆盖规则全在框架内部，业务与工具进程只表达
+ * 「我要运行期 env」还是「我要测试 env」（`mode: 'test'`），不接触 `.env.dev` /
+ * `.env.test.local` 这些文件名。
+ *
+ * 三种调用方：
+ *
+ * - `startServer`：`loadEnvironment()`（最早阶段固定调用）；
+ * - `createTestServer`：经 `prepareTestDatabase()` 间接调用（再跑两道闸门）；
+ * - 工具进程（`vitest.config.ts` / `prisma.config.ts` / `scripts/*.ts`）：调
+ *   `loadRuntimeEnvironment()`（它只是本函数的具名包装）—— 它们不被任何入口覆盖。
+ *
+ * `mode: 'test'` 的语义顺序：
+ *
+ * 1. 先加载三层开发分层，再叠测试层（两套 .env.test 逐层覆盖）；
+ * 2. `loadLayers` 末尾把**外部注入**（进程 / 容器 / CI）原样恢复 —— 所以线上注入的
+ *    `ENV=production` 一定压过仓库里的 `.env.test`，随后的环境闸门照旧拒绕启动；
+ * 3. 前面都没给出 `ENV` 时才兜底成 `test`：测试入口的默认身份就是测试，不该要求调用方
+ *    额外声明一次（否则漏写就变成「环境必须是 development/test」的莫名报错）。
+ *
+ * `generateOpenApi` **不**调用本函数（它不要求配置有效，设计 §3.2 规则 A/B）。
+ */
+export declare function loadEnvironment(options?: LoadEnvironmentOptions): ConfigEnv;
+//# sourceMappingURL=env.d.ts.map

package/output/core/env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../../source/core/env.ts"],"names":[],"mappings":"AAgCA,wDAAwD;AACxD,eAAO,MAAM,iBAAiB,SAAS,CAAA;AAEvC;;;;;;;;;;GAUG;AACH,eAAO,MAAM,cAAc,EAAE,SAAS,MAAM,EAA4B,CAAA;AAExE;;;;;;;GAOG;AACH,wBAAgB,0BAA0B,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAU5D;AA2BD;;;;;;;;GAQG;AACH,MAAM,WAAW,SAAS;IACxB,kDAAkD;IAClD,GAAG,EAAE,MAAM,CAAA;IACX,yCAAyC;IACzC,QAAQ,EAAE,MAAM,CAAA;IAChB,qBAAqB;IACrB,SAAS,EAAE,MAAM,CAAA;IACjB,sCAAsC;IACtC,YAAY,EAAE,MAAM,CAAA;IACpB,2CAA2C;IAC3C,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED,sDAAsD;AACtD,wBAAgB,gBAAgB,IAAI,SAAS,CAQ5C;AAED;;;;;GAKG;AACH,MAAM,MAAM,eAAe,GAAG,SAAS,GAAG,MAAM,CAAA;AAEhD,8BAA8B;AAC9B,MAAM,WAAW,sBAAsB;IACrC,IAAI,CAAC,EAAE,eAAe,CAAA;CACvB;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,eAAe,CAAC,OAAO,GAAE,sBAA2B,GAAG,SAAS,CAY/E"}

package/output/core/env.js

@@ -0,0 +1,124 @@
+import { config } from 'dotenv';
+/**
+ * 默认 env 文件分层（低 → 高优先级，后者覆盖前者）：
+ *
+ *   .env.dev   已提交进仓库的 dev 默认值（克隆后 `pnpm run dev` 开箱即用）
+ *   .env       本机私有覆盖（已被 gitignore）
+ *   .env.local 本机更高优先级覆盖（已被 gitignore）
+ *
+ * 真实环境变量（进程/容器注入）优先级最高，任何 .env 文件都不会覆盖它们 —— 这条保证让 CI、
+ * helm、`docker run -e` 等显式注入始终生效，也避免测试探针
+ * （`check-test-database-isolation`）注入的连接串被仓库里的默认值顶掉。
+ *
+ * 解析器与四家现状保持一致，统一使用 `dotenv`，以保证多行值、引号/转义、`export` 前缀等
+ * 细节语义完全等价（设计 §3.1 ①：与现状逐字一致）。
+ *
+ * **分层是框架的内部实现**：不导出、不参数化。调用方只表达「我要运行期 env」还是「我要测试
+ * env」（`mode`），层名与顺序不进入业务代码。
+ */
+const ENV_FILE_LAYERS = ['.env.dev', '.env', '.env.local'];
+/**
+ * 测试层（叠在 `ENV_FILE_LAYERS` 之上，低 → 高）：
+ *
+ *   .env.test       测试环境默认值（可提交：`ENV=test`、测试库连接串）
+ *   .env.test.local 本机覆盖（已被 gitignore）
+ *
+ * 测试入口**无条件**加载这两层（不等 `ENV === 'test'`）：测试入口的存在本身就意味着「这是
+ * 测试」，让调用方再声明一次是多余且容易漏的。
+ */
+const TEST_ENV_FILE_LAYERS = ['.env.test', '.env.test.local'];
+/** `LOG_LEVEL` 未设置时的默认级别（设计 §3.1 ① / §5.1 `logging`） */
+export const DEFAULT_LOG_LEVEL = 'info';
+/**
+ * 允许执行**破坏性 / 不可逆**操作的环境（`ENV` 取值）。
+ *
+ * 覆盖两类动作，两者共用同一份判定：
+ *
+ * - 测试数据库清理（`assertTestDatabaseSchema` 那道闸门的同伴）；
+ * - `testdata/` 脚本的 `load()` / `cleanup()`（`test-support/testdata.ts`）。
+ *
+ * `development` 是本地开发，`test` 是 vitest 入口显式声明的环境开关。除此之外一律拒绝——
+ * 只看 `NODE_ENV`、CI 标志或变量名都不构成证明：`NODE_ENV=test` 完全可能连着生产库。
+ */
+export const CLEANABLE_ENVS = ['development', 'test'];
+/**
+ * 环境闸门：非可清理环境立即失败。
+ *
+ * **不在分支里「跳过清理」**——把破坏性动作降级成静默 no-op，会让同一份代码在生产和测试里
+ * 走两条不同的路径，测试结果随即失去意义。要禁就整体失败。
+ *
+ * 报错必须带上当前值：漏配 `ENV` 时的症状否则会变成「莫名其妙不许跑」。
+ */
+export function assertCleanableEnvironment(env) {
+    if (CLEANABLE_ENVS.includes(env)) {
+        return;
+    }
+    throw new Error(`[env-gate] 拒绝在 ENV="${env || '<未设置>'}" 下执行会清理数据的操作：` +
+        `只接受 ${CLEANABLE_ENVS.join(' / ')}。` +
+        '会写入 / 清理 / truncate / reset 数据库的操作绝不能指向非开发环境。');
+}
+/**
+ * 首次 import 时的真实环境变量快照（此时还没有任何 .env 文件被加载）。
+ * 加载结束后原样恢复，实现「外部注入 > .env.local > .env > .env.dev」。
+ */
+const EXTERNAL_ENV = new Map(Object.entries(process.env).filter((entry) => entry[1] !== undefined));
+/**
+ * 按分层顺序加载 env 文件（内部实现，见上方「分层不导出」的约定）。
+ *
+ * @param extraLayers 追加在最高优先级的额外层
+ */
+function loadLayers(extraLayers = []) {
+    const layers = [...ENV_FILE_LAYERS, ...extraLayers];
+    layers.forEach((path, index) => {
+        // 第一层不覆盖已有值，后续层逐层覆盖前一层
+        config({ path, override: index > 0 });
+    });
+    for (const [key, value] of EXTERNAL_ENV) {
+        process.env[key] = value;
+    }
+}
+/** 读取固定 env（不加载文件）；入口会先 `loadEnvironment()` 再调用本函数 */
+export function resolveConfigEnv() {
+    return {
+        ENV: process.env.ENV ?? '',
+        API_PORT: process.env.API_PORT ?? '',
+        LOG_LEVEL: process.env.LOG_LEVEL ?? DEFAULT_LOG_LEVEL,
+        DATABASE_URL: process.env.DATABASE_URL ?? '',
+        REDIS_URL: process.env.REDIS_URL,
+    };
+}
+/**
+ * 加载 env 文件并在加载后返回固定约定值。
+ *
+ * **这是 env 的唯一出口**：层名、顺序、覆盖规则全在框架内部，业务与工具进程只表达
+ * 「我要运行期 env」还是「我要测试 env」（`mode: 'test'`），不接触 `.env.dev` /
+ * `.env.test.local` 这些文件名。
+ *
+ * 三种调用方：
+ *
+ * - `startServer`：`loadEnvironment()`（最早阶段固定调用）；
+ * - `createTestServer`：经 `prepareTestDatabase()` 间接调用（再跑两道闸门）；
+ * - 工具进程（`vitest.config.ts` / `prisma.config.ts` / `scripts/*.ts`）：调
+ *   `loadRuntimeEnvironment()`（它只是本函数的具名包装）—— 它们不被任何入口覆盖。
+ *
+ * `mode: 'test'` 的语义顺序：
+ *
+ * 1. 先加载三层开发分层，再叠测试层（两套 .env.test 逐层覆盖）；
+ * 2. `loadLayers` 末尾把**外部注入**（进程 / 容器 / CI）原样恢复 —— 所以线上注入的
+ *    `ENV=production` 一定压过仓库里的 `.env.test`，随后的环境闸门照旧拒绕启动；
+ * 3. 前面都没给出 `ENV` 时才兜底成 `test`：测试入口的默认身份就是测试，不该要求调用方
+ *    额外声明一次（否则漏写就变成「环境必须是 development/test」的莫名报错）。
+ *
+ * `generateOpenApi` **不**调用本函数（它不要求配置有效，设计 §3.2 规则 A/B）。
+ */
+export function loadEnvironment(options = {}) {
+    const test = options.mode === 'test';
+    loadLayers(test ? TEST_ENV_FILE_LAYERS : undefined);
+    if (!test && (process.env.ENV ?? '') === 'test') {
+        loadLayers(TEST_ENV_FILE_LAYERS);
+    }
+    if (test && (process.env.ENV ?? '') === '') {
+        process.env.ENV = 'test';
+    }
+    return resolveConfigEnv();
+}

package/output/{app → core}/env.test.d.ts.map

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