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

package/output/core/boot/lifecycle.js

@@ -15,7 +15,7 @@
  * - `init` 按**对象声明序**，`dispose` **逆序**；
  * - services 阶段内部**先 flush `ctx.disposer`**（构造期注册的清理），再逐单元 `dispose`。
  *
- * `middlewares` 按**对象键序**注册；它只有 `disposer`，没有逐单元生命周期。
+ * `middlewares` 按**数组顺序**注册；它只有 `disposer`，没有逐单元生命周期。
  */
 export const RESOURCES_STAGE = 'resources';
 export const CONFIG_STAGE = 'config';
@@ -23,27 +23,20 @@ export const CLIENTS_STAGE = 'clients';
 export const SERVICES_STAGE = 'services';
 export const MIDDLEWARES_STAGE = 'middlewares';
 export const ROUTERS_STAGE = 'routers';
-/** `middlewares` 的**注册期日志**阶段标签（与生命周期阶段同名） */
-export const MIDDLEWARES_LOG_STAGE = MIDDLEWARES_STAGE;
 /** 生命周期相位（逐单元日志字段 `phase`） */
+export const LIFECYCLE_PHASE_SETUP = 'setup';
 export const LIFECYCLE_PHASE_INIT = 'init';
 export const LIFECYCLE_PHASE_DISPOSE = 'dispose';
 function isObject(value) {
     return typeof value === 'object' && value !== null;
 }
 /**
- * `services` 有效名字：**对象键即单元名**（N1 §4：没有 `name` 字段）。
- */
-function serviceUnitName(key) {
-    return key;
-}
-/**
- * `middlewares` 日志名字：**对象键即单元名**（与 `services` 同口径）。
+ * `middlewares` 日志名字：**数组项的名字**（`MiddlewareUnit.name`，或裸函数的占位名 `middleware[i]`）。
  *
- * 键为空串时退路 `<service>:middleware`（仅用于注册期日志，不影响注册序）。
+ * 名字为空串时退路 `<service>:middleware`（仅用于注册期日志，不影响注册序——顺序由数组位置决定）。
  */
-export function middlewareUnitName(service, key) {
-    return key.length > 0 ? key : `${service}:middleware`;
+export function middlewareUnitName(service, name) {
+    return name.length > 0 ? name : `${service}:middleware`;
 }
 async function callInit(unit) {
     if (isObject(unit) && typeof unit.init === 'function') {
@@ -82,18 +75,65 @@ async function runLifecycleUnit(params, unit, value, phase) {
  */
 export async function initServiceUnits(params) {
     for (const key of Object.keys(params.services ?? {})) {
-        await runLifecycleUnit(params, serviceUnitName(key), params.services?.[key], LIFECYCLE_PHASE_INIT);
+        await runLifecycleUnit(params, key, params.services?.[key], LIFECYCLE_PHASE_INIT);
+    }
+}
+/** 跑一个资源单元生命周期步骤（统一日志，失败冒泡给调用方决定） */
+async function runResourceUnit(params, unit, phase) {
+    const step = phase === LIFECYCLE_PHASE_SETUP ? unit.setup : unit.dispose;
+    if (!step) {
+        return;
+    }
+    const fields = { service: params.service ?? '', unit: unit.name, stage: RESOURCES_STAGE, phase };
+    params.log?.debug(fields, `[lifecycle] ${phase} "${unit.name}" start`);
+    try {
+        await step();
+        params.log?.debug(fields, `[lifecycle] ${phase} "${unit.name}" done`);
+    }
+    catch (error) {
+        params.log?.error({ ...fields, error }, `[lifecycle] ${phase} "${unit.name}" failed`);
+        throw error;
+    }
+}
+/**
+ * `resources` 的装配期准备：按**对象声明序**逐项 `await setup()`；逐项打日志。
+ *
+ * 与 `initServiceUnits` 同形，差别在单元来源：资源值往往是第三方对象（没有 `setup` 方法），
+ * 单元外壳由 `buildResources` 在解包时收集成 `{ name, setup, dispose }`。
+ *
+ * **失败即中断**：资源准备失败时后续资源、`config`、`services` 都没有意义，直接冒泡给入口，
+ * 由入口把已构造的资源释放掉（与「端口占用」同一处理）。不放进关闭流程聚合——那不是关闭失败。
+ */
+export async function setupResourceUnits(params) {
+    for (const unit of params.units ?? []) {
+        await runResourceUnit(params, unit, LIFECYCLE_PHASE_SETUP);
+    }
+}
+/**
+ * `resources` 的关闭：按声明序**逆序**逐项 `await dispose()`。
+ *
+ * 与 `disposeServices` 同语义：单元级失败已 `log.error`，此处吞掉以保证单个资源不阻断其他资源。
+ *
+ * 在关闭流程中排在 `flushResources`（阶段 `Disposer`）**之前**：单元 `dispose` 是资源自己的
+ * 正事（断连），而 `disposer` 是本阶段临时产物的逃生口，后者不应挡住前者。
+ */
+export async function disposeResourceUnits(params) {
+    for (const unit of [...(params.units ?? [])].reverse()) {
+        try {
+            await runResourceUnit(params, unit, LIFECYCLE_PHASE_DISPOSE);
+        }
+        catch {
+            // 单元级已 log.error；此处仅保证不阻断其他资源
+        }
     }
 }
 /**
  * 关闭序：`services` 按声明序**逆序**逐项 `dispose?.()`。
  */
 function buildDisposeOrder(params) {
-    const steps = [];
-    for (const key of Object.keys(params.services ?? {}).reverse()) {
-        steps.push(() => runLifecycleUnit(params, serviceUnitName(key), params.services?.[key], LIFECYCLE_PHASE_DISPOSE));
-    }
-    return steps;
+    return Object.keys(params.services ?? {})
+        .reverse()
+        .map((key) => () => runLifecycleUnit(params, key, params.services?.[key], LIFECYCLE_PHASE_DISPOSE));
 }
 /**
  * 关闭步 `disposeServices`：`services` 声明序逆序释放。

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());
 }