@taicode/common-server 3.7.13 → 4.0.0-beta.1

package/output/app/define-server.negative-cases.js

@@ -0,0 +1,209 @@
+import { defineServer, startServer } from './entries.js';
+/**
+ * N2 §4 的 **15 条负向用例**：这些写法**必须编译失败**，全部由 `tsc --noEmit` 覆盖
+ * （**不进**运行期 vitest 断言）。
+ *
+ * 文件名刻意**不带** `.test.ts`：它由 `tsc --noEmit` 校验，不被 vitest 当作测试文件执行。
+ * 每个用例的 `@ts-expect-error` 必须**确有错误**，否则 tsc 会报「未使用」而失败。
+ *
+ * 说明：`defineServer` 的调用结果一律不用 —— 这些函数只作编译期证据。
+ */
+const identity = { service: 'negative-cases', title: 'Negative Cases', version: '1.0.0' };
+/** #1 `resources` 看不到 `config` */
+export function resourcesCannotSeeConfig() {
+    defineServer({
+        app: identity,
+        // @ts-expect-error `config` 不存在于 ResourcesContext
+        resources: ({ config }) => ({ config }),
+        config: () => ({}),
+        services: () => ({}),
+        middlewares: () => [],
+        routers: () => undefined,
+    });
+}
+/** #2 `resources` 看不到 `services` */
+export function resourcesCannotSeeServices() {
+    defineServer({
+        app: identity,
+        // @ts-expect-error `services` 不存在于 ResourcesContext
+        resources: ({ services }) => ({ services }),
+        config: () => ({}),
+        services: () => ({}),
+        middlewares: () => [],
+        routers: () => undefined,
+    });
+}
+/** #3 `config` 看不到 `services` */
+export function configCannotSeeServices() {
+    defineServer({
+        app: identity,
+        resources: () => ({}),
+        config: (ctx) => {
+            // @ts-expect-error `services` 不存在于 ConfigContext
+            void ctx.services;
+            return {};
+        },
+        services: () => ({}),
+        middlewares: () => [],
+        routers: () => undefined,
+    });
+}
+/** #4 `services` 看不到 `services`（禁 service 互依） */
+export function servicesCannotSeeServices() {
+    defineServer({
+        app: identity,
+        resources: () => ({}),
+        config: () => ({}),
+        services: (ctx) => {
+            // @ts-expect-error `services` 不存在于 ServiceContext（禁互依）
+            void ctx.services;
+            return {};
+        },
+        middlewares: () => [],
+        routers: () => undefined,
+    });
+}
+/** #5 `routers` 看不到 `resources`（禁绕层直连数据层） */
+export function routersCannotSeeResources() {
+    defineServer({
+        app: identity,
+        resources: () => ({ database: {} }),
+        config: () => ({}),
+        services: () => ({}),
+        middlewares: () => [],
+        routers: (ctx) => {
+            // @ts-expect-error `resources` 不存在于 RouterContext
+            void ctx.resources.database;
+        },
+    });
+}
+/** #6 `routers` 看不到 `config` */
+export function routersCannotSeeConfig() {
+    defineServer({
+        app: identity,
+        resources: () => ({}),
+        config: () => ({}),
+        services: () => ({}),
+        middlewares: () => [],
+        routers: (ctx) => {
+            // @ts-expect-error `config` 不存在于 RouterContext
+            void ctx.config;
+        },
+    });
+}
+/** #7 service 值声明 `dependsOn` → 该值塌成 `never` */
+export function serviceValueCannotDeclareDependsOn() {
+    defineServer({
+        app: identity,
+        resources: () => ({}),
+        config: () => ({}),
+        // @ts-expect-error `dependsOn` 声明使该值塌成 never
+        services: () => ({ a: { dependsOn: ['b'] } }),
+        middlewares: () => [],
+        routers: () => undefined,
+    });
+}
+/** #8 service 值是原始类型 → 被拒（防把配置塞进 services） */
+export function serviceValueCannotBePrimitive() {
+    defineServer({
+        app: identity,
+        resources: () => ({}),
+        config: () => ({}),
+        // @ts-expect-error 原始类型值被 ServicesShape 拒绝
+        services: () => ({ count: 1 }),
+        middlewares: () => [],
+        routers: () => undefined,
+    });
+}
+/** #9 `startServer` 只接受品牌产物，裸 `ServerConfig` 编译失败 */
+export function startServerRejectsBareConfig(bare) {
+    // @ts-expect-error 缺 `__brand`，不是 Server
+    void startServer(bare);
+}
+/** #10 `app.version` 必填 */
+export function appVersionIsRequired() {
+    defineServer({
+        // @ts-expect-error `AppIdentity.version` 必填
+        app: { service: 'no-version', title: 'No Version' },
+        resources: () => ({}),
+        config: () => ({}),
+        services: () => ({}),
+        middlewares: () => [],
+        routers: () => undefined,
+    });
+}
+/** #11 `cache: false` 静态关闭：键被 `Live<>` 从资源视图剔除 */
+export function staticallyDisabledResourceIsRemoved() {
+    defineServer({
+        app: identity,
+        resources: () => ({ cache: false, database: { query: () => '' } }),
+        config: (ctx) => {
+            // @ts-expect-error `cache: false` 的键已被 `Live<>` 剔除
+            void ctx.cache;
+            return {};
+        },
+        services: () => ({}),
+        middlewares: () => [],
+        routers: () => undefined,
+    });
+}
+/** #12 `config` 看不到 `app` */
+export function configCannotSeeApp() {
+    defineServer({
+        app: identity,
+        resources: () => ({}),
+        config: (ctx) => {
+            // @ts-expect-error `app` 不存在于 ConfigContext
+            void ctx.app;
+            return {};
+        },
+        services: () => ({}),
+        middlewares: () => [],
+        routers: () => undefined,
+    });
+}
+/** #13 `middlewares` 看不到 `resources`（中间件禁直连数据层） */
+export function middlewaresCannotSeeResources() {
+    defineServer({
+        app: identity,
+        resources: () => ({ database: {} }),
+        config: () => ({}),
+        services: () => ({}),
+        middlewares: (ctx) => {
+            // @ts-expect-error `resources` 不存在于 MiddlewareContext
+            void ctx.resources.database;
+            return [];
+        },
+        routers: () => undefined,
+    });
+}
+/** #14 `middlewares` 看不到 `env` */
+export function middlewaresCannotSeeEnv() {
+    defineServer({
+        app: identity,
+        resources: () => ({}),
+        config: () => ({}),
+        services: () => ({}),
+        middlewares: (ctx) => {
+            // @ts-expect-error `env` 不存在于 MiddlewareContext
+            void ctx.env;
+            return [];
+        },
+        routers: () => undefined,
+    });
+}
+/** #15 `services` 看不到 `env`（服务层禁读 env） */
+export function servicesCannotSeeEnv() {
+    defineServer({
+        app: identity,
+        resources: () => ({}),
+        config: () => ({}),
+        services: (ctx) => {
+            // @ts-expect-error `env` 不存在于 ServiceContext
+            void ctx.env.DATABASE_URL;
+            return {};
+        },
+        middlewares: () => [],
+        routers: () => undefined,
+    });
+}

package/output/app/define-server.test.d.ts

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

package/output/app/define-server.test.d.ts.map

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

package/output/app/define-server.test.js

@@ -0,0 +1,97 @@
+import { describe, expect, expectTypeOf, it } from 'vitest';
+import { defineServer, isServer, SERVER_BRAND, generateOpenApi } from './entries.js';
+/**
+ * `defineServer()`（N1 §1）——**纯定义**：产出一个 `Server` 对象，不建连、不起服务。
+ *
+ * 同一份定义可同时喂给「启动」与「出 spec」，这也是 `mode` 消失的原因。
+ */
+describe('defineServer 纯定义（N1 §1）', () => {
+    it('返回带品牌字段的 Server，并原样保留六个槽位', () => {
+        let resourcesCalls = 0;
+        const config = {
+            app: { service: 'define-server-test', title: 'Define Server Test', version: '1.0.0' },
+            resources: () => {
+                resourcesCalls += 1;
+                return {};
+            },
+            config: () => ({ enabled: true }),
+            services: () => ({}),
+            middlewares: () => [],
+            routers: () => undefined,
+        };
+        const server = defineServer(config);
+        expect(server.__brand).toBe(SERVER_BRAND);
+        expect(server.app).toEqual({ service: 'define-server-test', title: 'Define Server Test', version: '1.0.0' });
+        expect(server.services).toBe(config.services);
+        expect(server.routers).toBe(config.routers);
+        // 纯定义：不跑任何工厂
+        expect(resourcesCalls).toBe(0);
+    });
+    it('isServer 只识别 defineServer 产物', () => {
+        const server = defineServer({
+            app: { service: 'is-server-test', title: 'Is Server Test', version: '1.0.0' },
+            resources: () => ({}),
+            config: () => ({}),
+            services: () => ({}),
+            middlewares: () => [],
+            routers: () => undefined,
+        });
+        expect(isServer(server)).toBe(true);
+        expect(isServer({ __brand: 'other' })).toBe(false);
+        expect(isServer(null)).toBe(false);
+        expect(isServer('taicode.server')).toBe(false);
+    });
+    it('定义产物三入口共用：generateOpenApi 只读定义，不跑 config 槽位', async () => {
+        let configCalls = 0;
+        const server = defineServer({
+            app: { service: 'define-shared', title: 'Define Shared', version: '1.0.0' },
+            resources: () => ({}),
+            config: () => {
+                configCalls += 1;
+                return {};
+            },
+            services: () => ({}),
+            middlewares: () => [],
+            routers: () => undefined,
+        });
+        await generateOpenApi(server);
+        expect(configCalls).toBe(0);
+    });
+    it('app.version 必填：缺 version 时 TypeScript 编译失败（无默认值）', () => {
+        // 纯类型约束：这里只靠 `tsc --noEmit` 校验。若 `version` 又变回可选，
+        // `@ts-expect-error` 会因「未使用」而报错，测试反而变红。
+        const build = () => ({
+            // @ts-expect-error 缺少必填 app.version
+            app: { service: 'missing-version', title: 'Missing Version' },
+            resources: () => ({}),
+            config: () => ({}),
+            services: () => ({}),
+            middlewares: () => [],
+            routers: () => undefined,
+        });
+        expect(build).toBeTypeOf('function');
+    });
+    it('R / C / S 全推导：middlewares 与 routers 的 ctx.services 是强类型实体（M5）', () => {
+        defineServer({
+            app: { service: 'infer', title: 'Infer', version: '1.0.0' },
+            resources: () => ({ database: { query: (sql) => sql } }),
+            config: ({ resources }) => ({ domain: resources.database.query('domain') }),
+            services: ({ resources, config }) => ({
+                user: {
+                    find: (id) => `${config.domain}:${resources.database.query(id)}`,
+                },
+            }),
+            middlewares: (ctx) => {
+                // 类型自证：ctx.services 是 services 的返回类型（不是 unknown）
+                expectTypeOf(ctx.services.user.find).toEqualTypeOf();
+                // 类型自证：ctx.config 是 config 的返回类型
+                expectTypeOf(ctx.config.domain).toEqualTypeOf();
+                return [];
+            },
+            routers: (ctx) => {
+                expectTypeOf(ctx.services.user.find).toEqualTypeOf();
+                ctx.app.get('/user', () => ({ name: ctx.services.user.find('1') }));
+            },
+        });
+    });
+});

package/output/app/entries.d.ts

@@ -0,0 +1,29 @@
+import type { OpenApiDocument, Server, ServerConfig, StartServerOptions } from './types.js';
+import type { FastifyInstance } from 'fastify';
+export { SERVER_BRAND } from './types.js';
+/**
+ * `defineServer()`（N1 §1）——**纯定义**：产出一个 `Server` 对象，不建连、不起服务。
+ *
+ * 启动是另一个函数（`startServer`）的事——同一份定义可同时喂给「启动」与「出 spec」
+ * （`generateOpenApi`）。调用方**不写泛型**：`R` / `C` / `S` 全部从工厂返回类型推导。
+ */
+export declare function defineServer<R, C, S>(config: ServerConfig<R, C, S>): Server<R, C, S>;
+/** 供内部/调试使用：判断是否为 `defineServer()` 产物 */
+export declare function isServer(value: unknown): value is Server<unknown, unknown, unknown>;
+/**
+ * `startServer()`——真正跑起来：构造资源、加载配置、建服务、装中间件、注册路由、listen、装信号。
+ *
+ * - 最早阶段**固定加载 env**（`.env.dev < .env < .env.local`；`ENV=test` 追加 `.env.test.local`）。
+ * - 返回**原生 `FastifyInstance`**：不包 `fastify-plugin`、不返回包装对象。
+ * - `listen` 默认 `NODE_ENV !== 'test'`（测试不监听）。
+ * - 硬性要求 `Server`（品牌）产物：传裸 `ServerConfig` 是编译错误。
+ */
+export declare function startServer<R, C, S>(server: Server<R, C, S>, options?: StartServerOptions<R, C, S>): Promise<FastifyInstance>;
+/**
+ * `generateOpenApi()`——只出 spec，跑到能拿到 schema 就停。
+ *
+ * **红线**：全程**不得要求配置有效** —— 不跑 `config` 槽位、不要求 `DATABASE_URL` / `REDIS_URL`
+ * 有效；`resources`（只构造不建连）/ `services` / 中间件注册 / 路由注册照常执行。
+ */
+export declare function generateOpenApi<R, C, S>(server: Server<R, C, S>): Promise<OpenApiDocument>;
+//# sourceMappingURL=entries.d.ts.map

package/output/app/entries.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entries.d.ts","sourceRoot":"","sources":["../../source/app/entries.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAA;AAC3F,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAA;AAE9C,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAEzC;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,MAAM,EAAE,YAAY,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAMpF;AAED,yCAAyC;AACzC,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,CAMnF;AAED;;;;;;;GAOG;AACH,wBAAsB,WAAW,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,OAAO,GAAE,kBAAkB,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CAavI;AAED;;;;;GAKG;AACH,wBAAsB,eAAe,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,GAAG,OAAO,CAAC,eAAe,CAAC,CAiBhG"}

package/output/app/entries.js

@@ -0,0 +1,64 @@
+import { bootServer, BOOT_PHASE_OPENAPI, BOOT_PHASE_START } from './boot.js';
+import { loadRuntimeEnvFiles, resolveConfigEnv } from './env.js';
+import { SERVER_BRAND } from './types.js';
+export { SERVER_BRAND } from './types.js';
+/**
+ * `defineServer()`（N1 §1）——**纯定义**：产出一个 `Server` 对象，不建连、不起服务。
+ *
+ * 启动是另一个函数（`startServer`）的事——同一份定义可同时喂给「启动」与「出 spec」
+ * （`generateOpenApi`）。调用方**不写泛型**：`R` / `C` / `S` 全部从工厂返回类型推导。
+ */
+export function defineServer(config) {
+    const server = {
+        ...config,
+        __brand: SERVER_BRAND,
+    };
+    return server;
+}
+/** 供内部/调试使用：判断是否为 `defineServer()` 产物 */
+export function isServer(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        value.__brand === SERVER_BRAND);
+}
+/**
+ * `startServer()`——真正跑起来：构造资源、加载配置、建服务、装中间件、注册路由、listen、装信号。
+ *
+ * - 最早阶段**固定加载 env**（`.env.dev < .env < .env.local`；`ENV=test` 追加 `.env.test.local`）。
+ * - 返回**原生 `FastifyInstance`**：不包 `fastify-plugin`、不返回包装对象。
+ * - `listen` 默认 `NODE_ENV !== 'test'`（测试不监听）。
+ * - 硬性要求 `Server`（品牌）产物：传裸 `ServerConfig` 是编译错误。
+ */
+export async function startServer(server, options = {}) {
+    const env = loadRuntimeEnvFiles();
+    const isTest = process.env.NODE_ENV === 'test';
+    const booted = await bootServer({
+        server,
+        env,
+        phase: BOOT_PHASE_START,
+        listen: options.listen ?? !isTest,
+        shutdown: options.shutdown,
+    });
+    return booted.app;
+}
+/**
+ * `generateOpenApi()`——只出 spec，跑到能拿到 schema 就停。
+ *
+ * **红线**：全程**不得要求配置有效** —— 不跑 `config` 槽位、不要求 `DATABASE_URL` / `REDIS_URL`
+ * 有效；`resources`（只构造不建连）/ `services` / 中间件注册 / 路由注册照常执行。
+ */
+export async function generateOpenApi(server) {
+    // 不加载 .env 文件、不读配置
+    const env = resolveConfigEnv();
+    const booted = await bootServer({
+        server,
+        env,
+        phase: BOOT_PHASE_OPENAPI,
+        listen: false,
+    });
+    const app = booted.app;
+    if (typeof app.swagger !== 'function') {
+        throw new Error('[generateOpenApi] @fastify/swagger is not registered');
+    }
+    return app.swagger();
+}

package/output/app/env.d.ts

@@ -0,0 +1,59 @@
+/**
+ * 默认 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 ①：与现状逐字一致）。
+ */
+export declare const ENV_FILE_LAYERS: readonly [".env.dev", ".env", ".env.local"];
+/** `ENV=test` 时追加的最高层（设计 §3.1 ①） */
+export declare const TEST_ENV_FILE_LAYER = ".env.test.local";
+/** `LOG_LEVEL` 未设置时的默认级别（设计 §3.1 ① / §5.1 `logging`） */
+export declare const DEFAULT_LOG_LEVEL = "info";
+/**
+ * 按分层顺序加载 env 文件（设计 §3.1 ①）。
+ *
+ * `startServer` 内部会**固定调用**本函数；工具进程（`vitest.config.ts` / `scripts/*.ts`）不在
+ * `startServer` 覆盖范围内，须自行显式调用本函数。
+ *
+ * @param extraLayers 追加在最高优先级的额外层，例如测试配置传 `['.env.test.local']`
+ */
+export declare function loadEnvFiles(extraLayers?: readonly 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（不加载文件）；`startServer` 会先 `loadRuntimeEnvFiles()` 再调用本函数 */
+export declare function resolveConfigEnv(): ConfigEnv;
+/**
+ * `startServer` 最早阶段的固定 env 加载（设计 §3.1 ①）：
+ * `.env.dev < .env < .env.local`（外部注入最高），`ENV=test` 时再追加 `.env.test.local`。
+ *
+ * 注意 `generateOpenApi` **不**调用本函数（它不要求配置有效，设计 §3.2 规则 A/B）。
+ */
+export declare function loadRuntimeEnvFiles(): ConfigEnv;
+//# sourceMappingURL=env.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../../source/app/env.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,eAAe,6CAA8C,CAAA;AAE1E,oCAAoC;AACpC,eAAO,MAAM,mBAAmB,oBAAoB,CAAA;AAEpD,wDAAwD;AACxD,eAAO,MAAM,iBAAiB,SAAS,CAAA;AAUvC;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,WAAW,GAAE,SAAS,MAAM,EAAO,GAAG,IAAI,CAUtE;AAED;;;;;;;;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,sEAAsE;AACtE,wBAAgB,gBAAgB,IAAI,SAAS,CAQ5C;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,IAAI,SAAS,CAM/C"}

package/output/app/env.js

@@ -0,0 +1,66 @@
+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 ①：与现状逐字一致）。
+ */
+export const ENV_FILE_LAYERS = ['.env.dev', '.env', '.env.local'];
+/** `ENV=test` 时追加的最高层（设计 §3.1 ①） */
+export const TEST_ENV_FILE_LAYER = '.env.test.local';
+/** `LOG_LEVEL` 未设置时的默认级别（设计 §3.1 ① / §5.1 `logging`） */
+export const DEFAULT_LOG_LEVEL = 'info';
+/**
+ * 首次 import 时的真实环境变量快照（此时还没有任何 .env 文件被加载）。
+ * 加载结束后原样恢复，实现「外部注入 > .env.local > .env > .env.dev」。
+ */
+const EXTERNAL_ENV = new Map(Object.entries(process.env).filter((entry) => entry[1] !== undefined));
+/**
+ * 按分层顺序加载 env 文件（设计 §3.1 ①）。
+ *
+ * `startServer` 内部会**固定调用**本函数；工具进程（`vitest.config.ts` / `scripts/*.ts`）不在
+ * `startServer` 覆盖范围内，须自行显式调用本函数。
+ *
+ * @param extraLayers 追加在最高优先级的额外层，例如测试配置传 `['.env.test.local']`
+ */
+export function loadEnvFiles(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（不加载文件）；`startServer` 会先 `loadRuntimeEnvFiles()` 再调用本函数 */
+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,
+    };
+}
+/**
+ * `startServer` 最早阶段的固定 env 加载（设计 §3.1 ①）：
+ * `.env.dev < .env < .env.local`（外部注入最高），`ENV=test` 时再追加 `.env.test.local`。
+ *
+ * 注意 `generateOpenApi` **不**调用本函数（它不要求配置有效，设计 §3.2 规则 A/B）。
+ */
+export function loadRuntimeEnvFiles() {
+    loadEnvFiles();
+    if ((process.env.ENV ?? '') === 'test') {
+        loadEnvFiles([TEST_ENV_FILE_LAYER]);
+    }
+    return resolveConfigEnv();
+}

package/output/app/env.test.d.ts

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

package/output/app/env.test.d.ts.map

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

package/output/app/env.test.js

@@ -0,0 +1,124 @@
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+/**
+ * env 加载契约（设计 §3.1 ①）。
+ *
+ * 固定约定：`.env.dev` < `.env` < `.env.local`（外部注入最高），`ENV=test` 追加 `.env.test.local`；
+ * 固定读取 `ENV` / `API_PORT` / `LOG_LEVEL`，端口**只读 `API_PORT`，绝不回退 `PORT`**。
+ */
+const ENV_KEYS = [
+    'LAYER',
+    'OVERRIDE',
+    'ONLY_DEV',
+    'ONLY_ENV',
+    'ONLY_LOCAL',
+    'EXTERNAL_ONLY',
+    'ONLY_TEST',
+    'EXPORTED',
+    'QUOTED',
+    'MULTI',
+    'HASHED',
+    'ENV',
+    'API_PORT',
+    'PORT',
+    'LOG_LEVEL',
+];
+function clearEnvKeys() {
+    for (const key of ENV_KEYS) {
+        delete process.env[key];
+    }
+}
+/** 重新求值 `env.js`（`EXTERNAL_ENV` 快照在模块首次求值时抓取） */
+async function importEnvModule() {
+    vi.resetModules();
+    return import('./env.js');
+}
+describe('env 加载（设计 §3.1 ①）', () => {
+    let previousCwd;
+    let directory;
+    beforeEach(() => {
+        previousCwd = process.cwd();
+        directory = mkdtempSync(join(tmpdir(), 'common-app-env-'));
+        writeFileSync(join(directory, '.env.dev'), 'LAYER=dev\nONLY_DEV=dev\nOVERRIDE=dev\n');
+        writeFileSync(join(directory, '.env'), 'LAYER=env\nONLY_ENV=env\nOVERRIDE=env\n');
+        writeFileSync(join(directory, '.env.local'), 'LAYER=local\nONLY_LOCAL=local\nOVERRIDE=local\n');
+        process.chdir(directory);
+        clearEnvKeys();
+    });
+    afterEach(() => {
+        process.chdir(previousCwd);
+        rmSync(directory, { recursive: true, force: true });
+        clearEnvKeys();
+        vi.resetModules();
+    });
+    it('分层优先级：外部注入 > .env.local > .env > .env.dev', async () => {
+        process.env.LAYER = 'external';
+        process.env.EXTERNAL_ONLY = 'external';
+        const { loadEnvFiles } = await importEnvModule();
+        loadEnvFiles();
+        expect(process.env.LAYER).toBe('external');
+        expect(process.env.EXTERNAL_ONLY).toBe('external');
+        expect(process.env.OVERRIDE).toBe('local');
+        expect(process.env.ONLY_DEV).toBe('dev');
+        expect(process.env.ONLY_ENV).toBe('env');
+        expect(process.env.ONLY_LOCAL).toBe('local');
+    });
+    it('追加层（如 .env.test.local）优先级最高', async () => {
+        writeFileSync(join(directory, '.env.test.local'), 'OVERRIDE=test-local\nONLY_TEST=1\n');
+        const { loadEnvFiles } = await importEnvModule();
+        loadEnvFiles(['.env.test.local']);
+        expect(process.env.OVERRIDE).toBe('test-local');
+        expect(process.env.ONLY_TEST).toBe('1');
+    });
+    it('缺失的 env 文件不报错，已有层照常生效', async () => {
+        rmSync(join(directory, '.env.local'));
+        const { loadEnvFiles } = await importEnvModule();
+        expect(() => loadEnvFiles()).not.toThrow();
+        expect(process.env.ONLY_DEV).toBe('dev');
+        expect(process.env.OVERRIDE).toBe('env');
+    });
+    it('dotenv 语义：export 前缀 / 引号 / 转义 / 多行 / 行尾注释（与四家现状逐字一致）', async () => {
+        writeFileSync(join(directory, '.env.local'), ['export EXPORTED=1', 'QUOTED="a b"', 'MULTI="line1\\nline2"', 'HASHED=value # 行尾注释'].join('\n'));
+        const { loadEnvFiles } = await importEnvModule();
+        loadEnvFiles();
+        expect(process.env.EXPORTED).toBe('1');
+        expect(process.env.QUOTED).toBe('a b');
+        expect(process.env.MULTI).toBe('line1\nline2');
+        expect(process.env.HASHED).toBe('value');
+    });
+    it('loadRuntimeEnvFiles：ENV=test 时追加 .env.test.local', async () => {
+        writeFileSync(join(directory, '.env.dev'), 'LAYER=dev\nOVERRIDE=dev\nENV=test\nAPI_PORT=4321\n');
+        writeFileSync(join(directory, '.env.test.local'), 'LOG_LEVEL=debug\nONLY_TEST=1\n');
+        const { loadRuntimeEnvFiles } = await importEnvModule();
+        const env = loadRuntimeEnvFiles();
+        expect(env.ENV).toBe('test');
+        expect(env.API_PORT).toBe('4321');
+        expect(env.LOG_LEVEL).toBe('debug');
+        expect(process.env.ONLY_TEST).toBe('1');
+    });
+    it('loadRuntimeEnvFiles：ENV 非 test 时不加载 .env.test.local', async () => {
+        writeFileSync(join(directory, '.env.local'), 'ENV=development\n');
+        writeFileSync(join(directory, '.env.test.local'), 'LOG_LEVEL=debug\nONLY_TEST=1\n');
+        const { loadRuntimeEnvFiles } = await importEnvModule();
+        const env = loadRuntimeEnvFiles();
+        expect(env.ENV).toBe('development');
+        expect(env.LOG_LEVEL).toBe('info');
+        expect(process.env.ONLY_TEST).toBeUndefined();
+    });
+    it('固定读取：只认 API_PORT（绝不回退 PORT），LOG_LEVEL 默认 info，ENV 缺省空串', async () => {
+        process.env.PORT = '9999';
+        const { resolveConfigEnv } = await importEnvModule();
+        const env = resolveConfigEnv();
+        expect(env.API_PORT).toBe('');
+        expect(env.LOG_LEVEL).toBe('info');
+        expect(env.ENV).toBe('');
+    });
+    it('固有常量：分层顺序 / 测试层 / 默认日志级别', async () => {
+        const { ENV_FILE_LAYERS, TEST_ENV_FILE_LAYER, DEFAULT_LOG_LEVEL } = await importEnvModule();
+        expect(ENV_FILE_LAYERS).toEqual(['.env.dev', '.env', '.env.local']);
+        expect(TEST_ENV_FILE_LAYER).toBe('.env.test.local');
+        expect(DEFAULT_LOG_LEVEL).toBe('info');
+    });
+});