@taicode/common-server 4.0.0-beta.5 → 4.0.0-beta.7

package/output/core/boot/shutdown.d.ts

@@ -5,17 +5,21 @@
  * 关闭时按阶段**逆序 flush**：`routers → middlewares → services → clients → config → resources`
  * （后创建的先销毁；Prisma / Redis 这类资源**最后**才断）。
  *
- * `services` 阶段内部保持既有语义：先 flush 自己的 `disposer`（原 `stopProducers`），
- * 再 `disposeServices`（单元**逆序** `dispose`）。配置失效通道已删除，故没有 `unsubscribeConfig` 步。
+ * `services` / `resources` 阶段内部保持同一套语义：先 flush 自己的 `disposer`（构造期注册的
+ * 临时产物），再逐单元 `dispose`（声明序**逆序**）。
+ *
+ * ❗`resources` 阶段**顺序与 `services` 相反**：先 `disposeResources`（单元自己的连接）再
+ * `flushResources`（`ctx.disposer` 里的逃生口清理）。理由：单元 `dispose` 是「资源自身怎么关」
+ * 的正事，`disposer` 是临时产物；临时产物可能在 `dispose` 过程中被用到，不能先拆。
  *
  * `clients` 排在 `services` **之后**：服务单元 `dispose()` 时可能还要落一次外部调用。
  *
- * 固定七步：`flushRouters` → `flushMiddlewares` → `flushServices` → `disposeServices`
- * → `flushClients` → `flushConfig` → `flushResources`。
+ * 固定八步：`flushRouters` → `flushMiddlewares` → `flushServices` → `disposeServices`
+ * → `flushClients` → `flushConfig` → `disposeResources` → `flushResources`。
  *
  * 每步失败记日志、不阻断后续，最后聚合上报。
  */
-declare const SHUTDOWN_ORDER: readonly ["flushRouters", "flushMiddlewares", "flushServices", "disposeServices", "flushClients", "flushConfig", "flushResources"];
+declare const SHUTDOWN_ORDER: readonly ["flushRouters", "flushMiddlewares", "flushServices", "disposeServices", "flushClients", "flushConfig", "disposeResources", "flushResources"];
 type ShutdownStepName = (typeof SHUTDOWN_ORDER)[number];
 type ShutdownHandles = Record<ShutdownStepName, () => void | Promise<void>>;
 export interface ShutdownLogger {

package/output/core/boot/shutdown.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shutdown.d.ts","sourceRoot":"","sources":["../../../source/core/boot/shutdown.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,QAAA,MAAM,cAAc,oIAQV,CAAA;AAEV,KAAK,gBAAgB,GAAG,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,CAAC,CAAA;AAEvD,KAAK,eAAe,GAAG,MAAM,CAAC,gBAAgB,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAA;AAE3E,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,CAAC,EAAE,MAAM,KAAK,IAAI,CAAA;CAC5C;AAED;;;GAGG;AACH,wBAAsB,WAAW,CAAC,OAAO,EAAE,eAAe,EAAE,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAe9F"}
+{"version":3,"file":"shutdown.d.ts","sourceRoot":"","sources":["../../../source/core/boot/shutdown.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,QAAA,MAAM,cAAc,wJASV,CAAA;AAEV,KAAK,gBAAgB,GAAG,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,CAAC,CAAA;AAEvD,KAAK,eAAe,GAAG,MAAM,CAAC,gBAAgB,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAA;AAE3E,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,CAAC,EAAE,MAAM,KAAK,IAAI,CAAA;CAC5C;AAED;;;GAGG;AACH,wBAAsB,WAAW,CAAC,OAAO,EAAE,eAAe,EAAE,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAe9F"}

package/output/core/boot/shutdown.js

@@ -5,13 +5,17 @@
  * 关闭时按阶段**逆序 flush**：`routers → middlewares → services → clients → config → resources`
  * （后创建的先销毁；Prisma / Redis 这类资源**最后**才断）。
  *
- * `services` 阶段内部保持既有语义：先 flush 自己的 `disposer`（原 `stopProducers`），
- * 再 `disposeServices`（单元**逆序** `dispose`）。配置失效通道已删除，故没有 `unsubscribeConfig` 步。
+ * `services` / `resources` 阶段内部保持同一套语义：先 flush 自己的 `disposer`（构造期注册的
+ * 临时产物），再逐单元 `dispose`（声明序**逆序**）。
+ *
+ * ❗`resources` 阶段**顺序与 `services` 相反**：先 `disposeResources`（单元自己的连接）再
+ * `flushResources`（`ctx.disposer` 里的逃生口清理）。理由：单元 `dispose` 是「资源自身怎么关」
+ * 的正事，`disposer` 是临时产物；临时产物可能在 `dispose` 过程中被用到，不能先拆。
  *
  * `clients` 排在 `services` **之后**：服务单元 `dispose()` 时可能还要落一次外部调用。
  *
- * 固定七步：`flushRouters` → `flushMiddlewares` → `flushServices` → `disposeServices`
- * → `flushClients` → `flushConfig` → `flushResources`。
+ * 固定八步：`flushRouters` → `flushMiddlewares` → `flushServices` → `disposeServices`
+ * → `flushClients` → `flushConfig` → `disposeResources` → `flushResources`。
  *
  * 每步失败记日志、不阻断后续，最后聚合上报。
  */
@@ -22,6 +26,7 @@ const SHUTDOWN_ORDER = [
     'disposeServices',
     'flushClients',
     'flushConfig',
+    'disposeResources',
     'flushResources',
 ];
 /**

package/output/core/boot/signal.d.ts

@@ -4,7 +4,7 @@ import type { FastifyInstance } from 'fastify';
  * 内置信号处理（设计 §7.1 `activate` 尾部 / §7.2）。
  *
  * `SIGTERM` / `SIGINT` / `uncaughtException` / `unhandledRejection` ⇒ `app.close()`（触发 `onClose`
- * 的关闭 6 步）⇒ `process.exit(0/1)`。**只有 `startServer` 装信号处理**（它一定 `listen`）；
+ * 的关闭 7 步）⇒ `process.exit(0/1)`。**只有 `startServer` 装信号处理**（它一定 `listen`）；
  * `createTestServer` 不装——它跑在测试进程里，退出由测试框架决定。
  *
  * @returns detach 函数（移除本次注册的监听器）；`startServer` 已把它挂到 `onClose` 上

package/output/core/boot/signal.js

@@ -2,7 +2,7 @@
  * 内置信号处理（设计 §7.1 `activate` 尾部 / §7.2）。
  *
  * `SIGTERM` / `SIGINT` / `uncaughtException` / `unhandledRejection` ⇒ `app.close()`（触发 `onClose`
- * 的关闭 6 步）⇒ `process.exit(0/1)`。**只有 `startServer` 装信号处理**（它一定 `listen`）；
+ * 的关闭 7 步）⇒ `process.exit(0/1)`。**只有 `startServer` 装信号处理**（它一定 `listen`）；
  * `createTestServer` 不装——它跑在测试进程里，退出由测试框架决定。
  *
  * @returns detach 函数（移除本次注册的监听器）；`startServer` 已把它挂到 `onClose` 上

package/output/core/boot/steps.d.ts

@@ -1,15 +1,30 @@
 import { Disposer } from '@taicode/common-base';
 import type { ConfigAccess } from './context.js';
+import type { ResourceSetupUnit } from './lifecycle.js';
 import type { ConfigEnv } from '../env.js';
-import type { AppInstance, ClientsView, ErrorClassifier, LoggerLike, ResourcesView, Server } from '../types.js';
+import type { AppEnv, AppInstance, ClientsView, ErrorClassifier, LoggerLike, ResourcesView, Server } from '../types.js';
 import type { FastifyInstance } from 'fastify';
 /**
  * 装配**步料**（不是装配流程）。
  *
- * `startServer` / `generateOpenApi` 各自在 `start.ts` / `openapi.ts` 里写明自己的步序——
+ * `startServer` / `generateOpenApi`（`entries.ts`）各自写明自己的步序——
  * 这里只放「一步」的实现，**不含任何 `phase` / `mode` / 跳过集**。哪个入口跑哪几步，
- * 在入口文件里一眼可见，不需要在数据结构和分支之间来回对照。
+ * 在入口函数里一眼可见，不需要在数据结构和分支之间来回对照。
  */
+/**
+ * 结算 `ctx.env`：**完全按内置逻辑加载**（dotenv 分层 + 进程注入已由 `loadEnvironment` /
+ * `prepareTestDatabase` 做完，结果在 `base` 与 `process.env` 里），这里只把两者合成最终视图。
+ *
+ * - `base`：框架固定约定值（`ENV` / `API_PORT` / `DATABASE_URL` / ...，已归一化）；
+ * - 应用声明的扩展字段（`Env`，`defineServer` 的第一个泛型）：运行期取**内置加载后的**
+ *   `process.env[key]` 字符串直通——框架**不提供自定义加载**，也不对扩展字段做映射 / 校验 / 默认值。
+ *
+ * 返回「`process.env` 直通 + 固定约定覆盖」：固定键以归一化后的 `base` 为准（放最后覆盖），
+ * 其余键保持内置加载后的原始字符串。类型上窄化为 `AppEnv<Env>`（只暴露固定键 + 声明的扩展键）。
+ *
+ * `Env` 由调用方（`startServer` / `createTestServer`）显式传入其自身的 `Env` 泛型。
+ */
+export declare function resolveAppEnv<Env>(base: ConfigEnv): AppEnv<Env>;
 /** 每个阶段一个 `Disposer`（创建与释放同处一地；关闭时按阶段逆序 flush） */
 export interface StageDisposers {
     resources: Disposer;
@@ -20,9 +35,9 @@ export interface StageDisposers {
     routers: Disposer;
 }
 /** 一次装配的**运行期上下文**（步料之间传递的、不放公共类型里的东西） */
-export interface BootContext<R, C, CL, S> {
-    server: Server<R, C, CL, S>;
-    env: ConfigEnv;
+export interface BootContext<Resources, Config, Clients, Services, Env> {
+    server: Server<Resources, Config, Clients, Services, Env>;
+    env: AppEnv<Env>;
     /** 原生 Fastify 实例（对外返回的就是它） */
     app: FastifyInstance;
     /** 同一实例的框架视图（`request.ctx` 等类型增强的载体） */
@@ -31,11 +46,11 @@ export interface BootContext<R, C, CL, S> {
     /** 身份块的 `service`（日志标签用） */
     service: string;
     /** `config` 槽位的**读取能力**（出 spec 路径未产出 → `read()` 抛错） */
-    configAccess: ConfigAccess<C>;
+    configAccess: ConfigAccess<Config>;
     disposers: StageDisposers;
 }
 /** 建 app + 六个阶段 `Disposer`（两个入口的**第一步**，内容完全相同） */
-export declare function createBootContext<R, C, CL, S>(server: Server<R, C, CL, S>, env: ConfigEnv): BootContext<R, C, CL, S>;
+export declare function createBootContext<Resources, Config, Clients, Services, Env>(server: Server<Resources, Config, Clients, Services, Env>, env: AppEnv<Env>): BootContext<Resources, Config, Clients, Services, Env>;
 /**
  * 出文档用的上下文：**同一个 `BootContext` 形状，但实例是最小 Fastify**（无 logger /
  * 无 requestId / 无 trustProxy，见 `createDocumentFastify`）。
@@ -43,29 +58,43 @@ export declare function createBootContext<R, C, CL, S>(server: Server<R, C, CL,
  * 形状不变是刻意的——`buildResources` / `registerRouters` 这些单步实现
  * 因此**不需要知道自己在哪个入口跑**，轻量只体现在「实例怎么造」和「跑哪几步」上。
  */
-export declare function createDocumentContext<R, C, CL, S>(server: Server<R, C, CL, S>, env: ConfigEnv): BootContext<R, C, CL, S>;
+export declare function createDocumentContext<Resources, Config, Clients, Services, Env>(server: Server<Resources, Config, Clients, Services, Env>, env: AppEnv<Env>): BootContext<Resources, Config, Clients, Services, Env>;
 /**
  * 取**已加载**配置的访问器（框架内置单元消费配置的唯一入口）。
  *
  * 出 spec 路径下 `config` 槽位未产出，读到即抛 `CONFIG_UNAVAILABLE`——
  * 「构造期不得读配置」因此有运行期护栏，而不只是文档约定。
  */
-export declare function createConfigReader<C>(configAccess: ConfigAccess<C>): (key: string) => unknown;
-export interface ResourceBuildResult<R> {
-    /** 剔除了「编译期静态关闭」（值为 `false`）的键 */
-    resources: ResourcesView<R>;
+export declare function createConfigReader<Config>(configAccess: ConfigAccess<Config>): (key: string) => unknown;
+export interface ResourceBuildResult<Resources> {
+    /** 剔除了「编译期静态关闭」（值为 `false`）的键，并完成单元解包 */
+    resources: ResourcesView<Resources>;
+    /** 待执行的资源 `setup`（按声明序；空数组 = 无需准备） */
+    units: ResourceSetupUnit[];
     /** 各资源注册的分类器合成结果（零个 = `undefined`） */
     classifyResourceError: ErrorClassifier | undefined;
 }
-/** `resources(ctx)`：**只构造、不建连**（仅运行期入口执行） */
-export declare function buildResources<R, C, CL, S>(ctx: BootContext<R, C, CL, S>): Promise<ResourceBuildResult<R>>;
+/**
+ * `resources(ctx)`：**只构造、不建连**（仅运行期入口执行）。
+ *
+ * 只看两件事：调用工厂、拆解单元（视图 + 待执行的 `setup`）。**不执行** `setup` —— 那是下一个
+ * 单步 `setupResources`，两个入口各自显式写明（与整个 `steps.ts` 【步料不是流程】的定位一致）。
+ */
+export declare function buildResources<Resources, Config, Clients, Services, Env>(ctx: BootContext<Resources, Config, Clients, Services, Env>): Promise<ResourceBuildResult<Resources>>;
+/**
+ * 资源单元 `setup` 步：建连验证 / 同步库结构 / 预热，**在 `config` 之前**。
+ *
+ * 为什么必须是独立一步而不是 `buildResources` 内部：它是一道**有失败可能的装配动作**，
+ * 入口需要能把它跟「构造」分开看（失败时已构造的资源照样要释放）。
+ */
+export declare function setupResources<Resources, Config, Clients, Services, Env>(ctx: BootContext<Resources, Config, Clients, Services, Env>, units: readonly ResourceSetupUnit[]): Promise<void>;
 /**
  * core 装配：`identity` → `schema`（+ 路由契约守卫）→ `requestContext` → `cookie` →
  * `response` → `openapi` → `requestId` 回吐。
  *
  * 仅运行期入口执行——它装的是「请求怎么被处理」，构建期没有请求。
  */
-export declare function registerCoreStep<R, C, CL, S>(ctx: BootContext<R, C, CL, S>, classifyResourceError?: ErrorClassifier): Promise<void>;
+export declare function registerCoreStep<Resources, Config, Clients, Services, Env>(ctx: BootContext<Resources, Config, Clients, Services, Env>, classifyResourceError?: ErrorClassifier): Promise<void>;
 /**
  * **文档 core** 装配：`identity` → `schema`（+ 路由契约守卫）→ `openapi`。
  *
@@ -73,35 +102,37 @@ export declare function registerCoreStep<R, C, CL, S>(ctx: BootContext<R, C, CL,
  * `response` / `requestId` 不装：它们影响的是请求怎么被处理，而构建期一条请求都不会发。
  * 守卫仍必须在——文档就是权限目录（§10-26）。
  */
-export declare function registerDocumentCoreStep<R, C, CL, S>(ctx: BootContext<R, C, CL, S>): Promise<void>;
+export declare function registerDocumentCoreStep<Resources, Config, Clients, Services, Env>(ctx: BootContext<Resources, Config, Clients, Services, Env>): Promise<void>;
 /** `config(ctx)`：**仅运行期**（出 spec 路径不跑） */
-export declare function buildConfig<R, C, CL, S>(ctx: BootContext<R, C, CL, S>, resources: ResourcesView<R>): Promise<void>;
+export declare function buildConfig<Resources, Config, Clients, Services, Env>(ctx: BootContext<Resources, Config, Clients, Services, Env>, resources: ResourcesView<Resources>): Promise<void>;
 /**
  * `clients(ctx)`：**仅运行期**（需要 `config`，出 spec 路径不跑）。
  *
  * 外部客户端的地址 / 凭证来自业务配置，所以它必须排在 `config` 之后；
  * 又因为多个 service 要共享同一份实例（而 `services` 之间禁止互依），所以它必须排在 `services` 之前。
+ *
+ * **槽位可选**：应用省略 `clients` 时，这里按「空客户端包」处理（`Clients` 退化为空）。
  */
-export declare function buildClients<R, C, CL, S>(ctx: BootContext<R, C, CL, S>, resources: ResourcesView<R>): Promise<ClientsView<CL>>;
+export declare function buildClients<Resources, Config, Clients, Services, Env>(ctx: BootContext<Resources, Config, Clients, Services, Env>, resources: ResourcesView<Resources>): Promise<ClientsView<Clients>>;
 /** `services(ctx)`：**只构造**（`init()` 由调用方决定跑不跑） */
-export declare function buildServices<R, C, CL, S>(ctx: BootContext<R, C, CL, S>, resources: ResourcesView<R>, clients: ClientsView<CL>): Promise<Awaited<S>>;
-/** `middlewares(ctx)`：按**对象键序**逐个 `register(app)`（两个入口都执行） */
-export declare function registerMiddlewares<R, C, CL, S>(ctx: BootContext<R, C, CL, S>, services: Awaited<S>, clients: ClientsView<CL>): Promise<void>;
+export declare function buildServices<Resources, Config, Clients, Services, Env>(ctx: BootContext<Resources, Config, Clients, Services, Env>, resources: ResourcesView<Resources>, clients: ClientsView<Clients>): Promise<Awaited<Services>>;
+/** `middlewares(ctx)`：按**数组顺序**逐个 `register(app)`（两个入口都执行） */
+export declare function registerMiddlewares<Resources, Config, Clients, Services, Env>(ctx: BootContext<Resources, Config, Clients, Services, Env>, services: Awaited<Services>, clients: ClientsView<Clients>): Promise<void>;
 /** 框架内置系统路由（`/` / `/health` / `/system/health` / `/system/openapi` / `/system/info`） */
-export declare function registerSystemRoutesStep<R, C, CL, S>(ctx: BootContext<R, C, CL, S>, services: Awaited<S>): void;
+export declare function registerSystemRoutesStep<Resources, Config, Clients, Services, Env>(ctx: BootContext<Resources, Config, Clients, Services, Env>, services: Awaited<Services>): void;
 /** `routers(ctx)`：业务路由（文档与权限目录都从这里来） */
-export declare function registerRouters<R, C, CL, S>(ctx: BootContext<R, C, CL, S>, services: Awaited<S>, clients: ClientsView<CL>): Promise<void>;
+export declare function registerRouters<Resources, Config, Clients, Services, Env>(ctx: BootContext<Resources, Config, Clients, Services, Env>, services: Awaited<Services>, clients: ClientsView<Clients>): Promise<void>;
 /** 系统路由（出文档路径：不构造 `services`） */
-export declare function registerDocumentSystemRoutesStep<R, C, CL, S>(ctx: BootContext<R, C, CL, S>): void;
+export declare function registerDocumentSystemRoutesStep<Resources, Config, Clients, Services, Env>(ctx: BootContext<Resources, Config, Clients, Services, Env>): void;
 /** 业务路由（出文档路径：不构造 `services` / `clients`；这是文档内容的**唯一**业务来源） */
-export declare function registerDocumentRoutersStep<R, C, CL, S>(ctx: BootContext<R, C, CL, S>): Promise<void>;
+export declare function registerDocumentRoutersStep<Resources, Config, Clients, Services, Env>(ctx: BootContext<Resources, Config, Clients, Services, Env>): Promise<void>;
 /**
- * 关闭流程（固定七步，顺序写在 `shutdown.ts` 里，不可覆盖）。
+ * 关闭流程（固定八步，顺序写在 `shutdown.ts` 里，不可覆盖）。
  *
  * 由 `onClose` 钩子触发；spec 入口在 `finally` 里 `close()` 同样会走它——
  * 「构造了什么就释放什么」，构建脚本不再留下未释放的资源。
  */
-export declare function buildShutdownFlow<R, C, CL, S>(ctx: BootContext<R, C, CL, S>, services: Awaited<S>): () => Promise<void>;
+export declare function buildShutdownFlow<Resources, Config, Clients, Services, Env>(ctx: BootContext<Resources, Config, Clients, Services, Env>, services: Awaited<Services>, resourceUnits?: readonly ResourceSetupUnit[]): () => Promise<void>;
 /** 把关闭流程挂到 `onClose`（两个入口都挂：谁 `close()` 谁负责释放） */
-export declare function installShutdownHook<R, C, CL, S>(ctx: BootContext<R, C, CL, S>, services: Awaited<S>): void;
+export declare function installShutdownHook<Resources, Config, Clients, Services, Env>(ctx: BootContext<Resources, Config, Clients, Services, Env>, services: Awaited<Services>, resourceUnits?: readonly ResourceSetupUnit[]): void;
 //# sourceMappingURL=steps.d.ts.map

package/output/core/boot/steps.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"steps.d.ts","sourceRoot":"","sources":["../../../source/core/boot/steps.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"steps.d.ts","sourceRoot":"","sources":["../../../source/core/boot/steps.ts"],"names":[],"mappings":"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"}

package/output/core/boot/steps.js

@@ -1,9 +1,38 @@
 import { Disposer } from '@taicode/common-base';
 import { registerCore, registerDocumentCore, createDocumentFastify, createFastify } from '../assemble.js';
 import { registerSystemRoutes } from '../modules/system-routes/index.js';
-import { createClientsContext, createConfigAccess, createConfigContext, createMiddlewareContext, createResourcesContext, createRouterContext, createServiceContext, liveClients, liveResources, provideConfig, readConfigKey, } from './context.js';
-import { CLIENTS_STAGE, CONFIG_STAGE, disposeServices, disposeStage, MIDDLEWARES_LOG_STAGE, MIDDLEWARES_STAGE, middlewareUnitName, RESOURCES_STAGE, ROUTERS_STAGE, SERVICES_STAGE, } from './lifecycle.js';
+import { createClientsContext, createConfigAccess, createConfigContext, createMiddlewareContext, createResourcesContext, createRouterContext, createServiceContext, liveResources, provideConfig, readConfigKey, splitResourceUnits, } from './context.js';
+import { CLIENTS_STAGE, CONFIG_STAGE, disposeResourceUnits, disposeServices, disposeStage, MIDDLEWARES_STAGE, middlewareUnitName, RESOURCES_STAGE, ROUTERS_STAGE, SERVICES_STAGE, setupResourceUnits, } from './lifecycle.js';
 import { runShutdown } from './shutdown.js';
+/**
+ * 装配**步料**（不是装配流程）。
+ *
+ * `startServer` / `generateOpenApi`（`entries.ts`）各自写明自己的步序——
+ * 这里只放「一步」的实现，**不含任何 `phase` / `mode` / 跳过集**。哪个入口跑哪几步，
+ * 在入口函数里一眼可见，不需要在数据结构和分支之间来回对照。
+ */
+/**
+ * 结算 `ctx.env`：**完全按内置逻辑加载**（dotenv 分层 + 进程注入已由 `loadEnvironment` /
+ * `prepareTestDatabase` 做完，结果在 `base` 与 `process.env` 里），这里只把两者合成最终视图。
+ *
+ * - `base`：框架固定约定值（`ENV` / `API_PORT` / `DATABASE_URL` / ...，已归一化）；
+ * - 应用声明的扩展字段（`Env`，`defineServer` 的第一个泛型）：运行期取**内置加载后的**
+ *   `process.env[key]` 字符串直通——框架**不提供自定义加载**，也不对扩展字段做映射 / 校验 / 默认值。
+ *
+ * 返回「`process.env` 直通 + 固定约定覆盖」：固定键以归一化后的 `base` 为准（放最后覆盖），
+ * 其余键保持内置加载后的原始字符串。类型上窄化为 `AppEnv<Env>`（只暴露固定键 + 声明的扩展键）。
+ *
+ * `Env` 由调用方（`startServer` / `createTestServer`）显式传入其自身的 `Env` 泛型。
+ */
+export function resolveAppEnv(base) {
+    const passthrough = {};
+    for (const [key, value] of Object.entries(process.env)) {
+        if (typeof value === 'string') {
+            passthrough[key] = value;
+        }
+    }
+    return { ...passthrough, ...base };
+}
 /** 建 app + 六个阶段 `Disposer`（两个入口的**第一步**，内容完全相同） */
 export function createBootContext(server, env) {
     return buildContext(server, env, createFastify(env));
@@ -71,7 +100,12 @@ function combineClassifiers(classifiers) {
         return null;
     };
 }
-/** `resources(ctx)`：**只构造、不建连**（仅运行期入口执行） */
+/**
+ * `resources(ctx)`：**只构造、不建连**（仅运行期入口执行）。
+ *
+ * 只看两件事：调用工厂、拆解单元（视图 + 待执行的 `setup`）。**不执行** `setup` —— 那是下一个
+ * 单步 `setupResources`，两个入口各自显式写明（与整个 `steps.ts` 【步料不是流程】的定位一致）。
+ */
 export async function buildResources(ctx) {
     const classifiers = [];
     const built = (await ctx.server.resources(createResourcesContext({
@@ -82,11 +116,22 @@ export async function buildResources(ctx) {
             classifiers.push(classifier);
         },
     })));
+    const { view, units } = splitResourceUnits(built);
     return {
-        resources: liveResources(built),
+        resources: view,
+        units,
         classifyResourceError: combineClassifiers(classifiers),
     };
 }
+/**
+ * 资源单元 `setup` 步：建连验证 / 同步库结构 / 预热，**在 `config` 之前**。
+ *
+ * 为什么必须是独立一步而不是 `buildResources` 内部：它是一道**有失败可能的装配动作**，
+ * 入口需要能把它跟「构造」分开看（失败时已构造的资源照样要释放）。
+ */
+export async function setupResources(ctx, units) {
+    await setupResourceUnits({ service: ctx.service, log: ctx.log, units });
+}
 /**
  * core 装配：`identity` → `schema`（+ 路由契约守卫）→ `requestContext` → `cookie` →
  * `response` → `openapi` → `requestId` 回吐。
@@ -121,16 +166,28 @@ export async function buildConfig(ctx, resources) {
  *
  * 外部客户端的地址 / 凭证来自业务配置，所以它必须排在 `config` 之后；
  * 又因为多个 service 要共享同一份实例（而 `services` 之间禁止互依），所以它必须排在 `services` 之前。
+ *
+ * **槽位可选**：应用省略 `clients` 时，这里按「空客户端包」处理（`Clients` 退化为空）。
  */
 export async function buildClients(ctx, resources) {
+    if (ctx.server.clients === undefined) {
+        return {};
+    }
     const built = (await ctx.server.clients(createClientsContext({ log: ctx.log, disposer: ctx.disposers.clients, resources, configAccess: ctx.configAccess })));
-    return liveClients(built);
+    return liveResources(built);
 }
 /** `services(ctx)`：**只构造**（`init()` 由调用方决定跑不跑） */
 export async function buildServices(ctx, resources, clients) {
     return ctx.server.services(createServiceContext({ log: ctx.log, disposer: ctx.disposers.services, resources, configAccess: ctx.configAccess, clients }));
 }
-/** `middlewares(ctx)`：按**对象键序**逐个 `register(app)`（两个入口都执行） */
+/** 归一化一个 `MiddlewareEntry`：裸函数补一个用于日志的占位名（`middleware[i]`） */
+function normalizeMiddleware(entry, index) {
+    if (typeof entry === 'function') {
+        return { name: `middleware[${index}]`, register: entry };
+    }
+    return { name: entry.name, register: entry.register };
+}
+/** `middlewares(ctx)`：按**数组顺序**逐个 `register(app)`（两个入口都执行） */
 export async function registerMiddlewares(ctx, services, clients) {
     const middlewares = ctx.server.middlewares(createMiddlewareContext({
         app: ctx.instance,
@@ -140,9 +197,10 @@ export async function registerMiddlewares(ctx, services, clients) {
         configAccess: ctx.configAccess,
         clients,
     }));
-    for (const [name, middleware] of Object.entries(middlewares)) {
-        await middleware(ctx.instance);
-        ctx.log.debug({ service: ctx.service, unit: middlewareUnitName(ctx.service, name), stage: MIDDLEWARES_LOG_STAGE }, '[middleware] registered');
+    for (const [index, entry] of middlewares.entries()) {
+        const { name, register } = normalizeMiddleware(entry, index);
+        await register(ctx.instance);
+        ctx.log.debug({ service: ctx.service, unit: middlewareUnitName(ctx.service, name), stage: MIDDLEWARES_STAGE }, '[middleware] registered');
     }
 }
 /** 框架内置系统路由（`/` / `/health` / `/system/health` / `/system/openapi` / `/system/info`） */
@@ -175,12 +233,12 @@ export async function registerDocumentRoutersStep(ctx) {
     await registerRouters(ctx, DOCUMENT_UNITS, DOCUMENT_UNITS);
 }
 /**
- * 关闭流程（固定七步，顺序写在 `shutdown.ts` 里，不可覆盖）。
+ * 关闭流程（固定八步，顺序写在 `shutdown.ts` 里，不可覆盖）。
  *
  * 由 `onClose` 钩子触发；spec 入口在 `finally` 里 `close()` 同样会走它——
  * 「构造了什么就释放什么」，构建脚本不再留下未释放的资源。
  */
-export function buildShutdownFlow(ctx, services) {
+export function buildShutdownFlow(ctx, services, resourceUnits = []) {
     return async () => {
         await runShutdown({
             flushRouters: () => disposeStage({ service: ctx.service, log: ctx.log, stage: ROUTERS_STAGE, disposer: ctx.disposers.routers }),
@@ -189,12 +247,13 @@ export function buildShutdownFlow(ctx, services) {
             disposeServices: () => disposeServices({ service: ctx.service, log: ctx.log, services: services }),
             flushClients: () => disposeStage({ service: ctx.service, log: ctx.log, stage: CLIENTS_STAGE, disposer: ctx.disposers.clients }),
             flushConfig: () => disposeStage({ service: ctx.service, log: ctx.log, stage: CONFIG_STAGE, disposer: ctx.disposers.config }),
+            disposeResources: () => disposeResourceUnits({ service: ctx.service, log: ctx.log, units: resourceUnits }),
             flushResources: () => disposeStage({ service: ctx.service, log: ctx.log, stage: RESOURCES_STAGE, disposer: ctx.disposers.resources }),
         }, ctx.log);
     };
 }
 /** 把关闭流程挂到 `onClose`（两个入口都挂：谁 `close()` 谁负责释放） */
-export function installShutdownHook(ctx, services) {
-    const flow = buildShutdownFlow(ctx, services);
+export function installShutdownHook(ctx, services, resourceUnits = []) {
+    const flow = buildShutdownFlow(ctx, services, resourceUnits);
     ctx.app.addHook('onClose', () => flow());
 }

package/output/core/entries.d.ts

@@ -1,51 +1,69 @@
 import type { OpenApiDocument, Server, ServerConfig } from './types.js';
 import type { FastifyInstance } from 'fastify';
-export { SERVER_BRAND } from './types.js';
 /**
  * `defineServer()`（N1 §1）——**纯定义**：产出一个 `Server` 对象，不建连、不起服务。
  *
  * 启动是另一个函数（`startServer`）的事——同一份定义可同时喂给「启动」与「出 spec」
- * （`generateOpenApi`）。调用方**不写泛型**：`R` / `C` / `CL` / `S` 全部从工厂返回类型推导。
+ * （`generateOpenApi`）。
  *
  * ## 怎么用
  *
- * 一个服务**只在 `source/server.ts` 里写一次**，然后在两个地方消费它：
+ * 一个服务**只在 `source/server.ts` 里写一次**，然后在三个地方消费它：
  *
  * ```ts
  * // source/server.ts
  * export const server = defineServer({ app, resources, config, clients, services, middlewares, routers })
  * ```
  * ```ts
- * // source/index.ts —— 启动
- * await startServer(server)
- * ```
- * ```ts
- * // build/openapi-gen.ts —— 出 spec
- * await generateOpenApi(server)
- * ```
- * ```ts
- * // *.test.ts —— 测试
- * const testServer = await createTestServer(server)
+ * await startServer(server)        // source/index.ts —— 启动
+ * await generateOpenApi(server)    // build/openapi-gen.ts —— 出 spec
+ * await createTestServer(server)   // *.test.ts —— 测试
  * ```
  *
  * ## 两条容易踩的规矩
  *
  * - **本函数不读 env、不建连、不读库**。放在模块顶层是安全的：`import { server }` 不会有副作用。
  *   （需要 env 的工具进程自己调 `loadRuntimeEnvironment()`。）
- * - **槽位是六个、恒定不缺**。没有业务路由也要写 `routers: () => {}`；没有外部客户端也要写
- *   `clients: () => ({})`——槽位不留「可省略」分支，省掉一个就会让「这份定义到底声明了什么」
- *   需要靠猜。
+ * - **`clients` 可省略**，其余槽位恒定：没有业务路由也要写 `routers: () => {}`。省略 `clients`
+ *   → 空客户端包。其余槽位不留「可省略」分支，省掉一个就会让「这份定义到底声明了什么」需要靠猜。
+ *
+ * ## 扩展 env（`Env`）：`Env` 是**第一个**泛型，类型声明，不影响加载
+ *
+ * `Env` 排在泛型首位，就是为了能**单独手写**：`defineServer<{ FOO?: string }>({ ... })` 把扩展字段
+ * 的类型并进 `ctx.env`（`resources` / `config` 的 `ctx.env` 上可读、有类型）。不写即 `Env = object`
+ * （无扩展，`ctx.env` 就是 `ConfigEnv`）。
+ *
+ * ⚠️ **TypeScript 限制（务必知道）**：只要**显式写了 `Env`**，其余四个泛型
+ * （`Resources` / `Config` / `Clients` / `Services`）就**不再从工厂推导、一律退化为 `object`**
+ * —— 这是 TS「类型参数全有或全无」的规则，不是本函数能绕过的。后果：`defineServer<MyEnv>({...})`
+ * 产出的 `server` 上，`services` 等类型会塌成 `object`，`testServer.services.xxx` 之类会丢类型。
+ *
+ * 因此两种写法各有适用：
+ * - **要完整推导**（典型业务服务，依赖 `ctx.services` / `testServer.services` 的类型）：**不写泛型**，
+ *   把扩展 env 的类型写在**工厂参数标注**上——`resources: (ctx: ResourcesContext<{ FOO?: string }>) => ...`
+ *   或 point-free 传入参数已标注的命名工厂。这样 `Env` 与其余泛型**一起被推导**，不丢类型。
+ * - **只在意 `Env`、不依赖其余被推导类型**（简单服务 / 测试）：直接 `defineServer<MyEnv>({...})`。
+ *
+ * ⚠️ **只声明类型，不参与加载**：env 的加载完全走框架内置逻辑（dotenv 分层 + 进程注入），框架
+ * **不提供自定义加载**；运行期扩展字段的值就是内置加载后的 `process.env[key]`（字符串直通）。
+ *
+ * ```ts
+ * // 写法一（推荐业务服务用）：不写泛型，Env 从工厂参数标注推导，其余泛型一起推导
+ * function createResources(ctx: ResourcesContext<{ REDIS_KEY_PREFIX?: string }>) { ... }
+ * export const server = defineServer({ app, resources: createResources, config, services, middlewares, routers })
+ *
+ * // 写法二：显式手写 Env（首位）——简单；但其余泛型退化为 object
+ * export const server = defineServer<{ REDIS_KEY_PREFIX?: string }>({ app, resources, config, services, middlewares, routers })
+ * ```
  */
-export declare function defineServer<R, C, CL, S>(config: ServerConfig<R, C, CL, S>): Server<R, C, CL, S>;
-/** 供内部/调试使用：判断是否为 `defineServer()` 产物 */
-export declare function isServer(value: unknown): value is Server<unknown, unknown, unknown, unknown>;
+export declare function defineServer<Env = object, Resources = object, Config = object, Clients = object, Services = object>(config: ServerConfig<Resources, Config, Clients, Services, Env>): Server<Resources, Config, Clients, Services, Env>;
 /**
  * `startServer()`——真正跑起来：构造资源、加载配置、建客户端、建服务、装中间件、注册路由、listen、装信号。
  *
  * 步序**就写在本函数里**，不抽到共享的「按模式分支」的装配器：
  * ```
  * env → resources → core → config → clients → services → services.init() → middlewares
- *     → systemRoutes → routers → onClose → ready → listen/signal
+ *     → systemRoutes → routers → onClose → ready → testdata → listen/signal
  * ```
  *
  * - 最早阶段**固定加载 env**（`.env.dev < .env < .env.local`；`ENV=test` 追加 `.env.test.local`）。
@@ -55,6 +73,16 @@ export declare function isServer(value: unknown): value is Server<unknown, unkno
  *   而不是同一个入口按环境变量 / 选项改行为。
  * - 硬性要求 `Server`（品牌）产物：传裸 `ServerConfig` 是编译错误。
  *
+ * ## `development` / `test` 下会自动装载 `testdata/`
+ *
+ * 真启动（本地 `pnpm dev`）在 `ready()` 之后、**listen 之前**装载 `<cwd>/testdata` 下的脚本并整体
+ * `load()`（见 `test-support/testdata.ts`）：端口一旦对外，数据必须已经在位。脚本拿到的是装配好的
+ * ctx（`env` + `resources` + `log`），所以它们写数据用的就是被测服务读数据的那份连接。
+ * `ENV` 不在 `CLEANABLE_ENVS` 里（即生产）时**整段跳过**——这是 `startServer` 的唯一一处环境
+ * 分支，且是安静的：生产不需要测试数据，也没有什么东西需要失败。
+ *
+ * `cleanup()` 在 `startServer` 路径上不会被调用：真启动要的就是「数据在」，不是「数据不在」。
+ *
  * ## 怎么用
  *
  * ```ts
@@ -71,10 +99,10 @@ export declare function isServer(value: unknown): value is Server<unknown, unkno
  * 你**需要**知道的两件事：
  * - 端口只读 env 的 `API_PORT`，**不回退 `PORT`**（`PORT` 属 nginx）。`API_PORT=0` 让内核
  *   分配空闲端口，多实例本地调试靠它。
- * - 失败时已构造的资源会被按固定顺序释放（关闭流程七步），不会漏掉连接池；错误原样抛给
+ * - 失败时已构造的资源会被按固定顺序释放（关闭流程八步），不会漏掉连接池；错误原样抛给
  *   调用方——所以端口占用会让 `startServer` 直接 reject，需要在入口处接住。
  */
-export declare function startServer<R, C, CL, S>(server: Server<R, C, CL, S>): Promise<FastifyInstance>;
+export declare function startServer<Resources, Config, Clients, Services, Env>(server: Server<Resources, Config, Clients, Services, Env>): Promise<FastifyInstance>;
 /**
  * `generateOpenApi()`——只出 spec。
  *
@@ -119,5 +147,5 @@ export declare function startServer<R, C, CL, S>(server: Server<R, C, CL, S>): P
  * 如果你的 `routers` 里写了 `services.xxx`（而不是只把它捕获进 handler），这条路会抛
  * `CONFIG_UNAVAILABLE`——那不是 bug，是在提醒「路由注册期不该依赖运行期产物」。
  */
-export declare function generateOpenApi<R, C, CL, S>(server: Server<R, C, CL, S>): Promise<OpenApiDocument>;
+export declare function generateOpenApi<Resources, Config, Clients, Services, Env>(server: Server<Resources, Config, Clients, Services, Env>): Promise<OpenApiDocument>;
 //# sourceMappingURL=entries.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"entries.d.ts","sourceRoot":"","sources":["../../source/core/entries.ts"],"names":[],"mappings":"AAsBA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AACvE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAA;AAE9C,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAczC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,MAAM,EAAE,YAAY,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,CAMhG;AAED,yCAAyC;AACzC,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,CAM5F;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAsB,WAAW,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,GAAG,OAAO,CAAC,eAAe,CAAC,CAqCpG;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,wBAAsB,eAAe,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,GAAG,OAAO,CAAC,eAAe,CAAC,CAsBxG"}
+{"version":3,"file":"entries.d.ts","sourceRoot":"","sources":["../../source/core/entries.ts"],"names":[],"mappings":"AAyBA,OAAO,KAAK,EAAU,eAAe,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAC/E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAA;AAc9C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AACH,wBAAgB,YAAY,CAAC,GAAG,GAAG,MAAM,EAAE,SAAS,GAAG,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,OAAO,GAAG,MAAM,EAAE,QAAQ,GAAG,MAAM,EACjH,MAAM,EAAE,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,GAAG,CAAC,GAC9D,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,GAAG,CAAC,CAMnD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,wBAAsB,WAAW,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,eAAe,CAAC,CAoDhK;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,wBAAsB,eAAe,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,eAAe,CAAC,CAsBpK"}