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

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

@@ -0,0 +1,206 @@
+import type { Disposer } from '@taicode/common-base';
+import type { LoggerLike } from '../types.js';
+/**
+ * 生命周期序（N1 §4 / N2 §2.5）。
+ *
+ * **每个阶段一个 `Disposer`**（`ctx.disposer`，所有槽位都有）：在创建某个东西的地方当场
+ * `ctx.disposer.add(() => 释放它)` —— 创建与释放同处一地。
+ *
+ * 关闭时按阶段**逆序 flush**：`routers → middlewares → services → clients → config → resources`
+ * （后创建的先销毁；Prisma / Redis 这类资源最后才断）。
+ *
+ * **`clients` 为什么排在 `services` 之后关**：服务单元 `dispose()` 时可能还要落一次外部调用
+ * （落库、通知、上报），客户端必须先活着。
+ *
+ * **`services` 额外有逐单元生命周期**（两个相位，语义互不替代）：
+ * - 单元之间**不得相互依赖**（`services` 的 ctx 没有 `services` 字段，编译期禁止）；
+ * - `init`（建状态）按**对象声明序**；
+ * - `dispose`（终态释放）**逆序**，只出现在关闭流程里；
+ * - services 阶段内部**先 flush `ctx.disposer`**（构造期注册的清理），再逐单元 `dispose`。
+ *
+ * ## 没有 `reset` 相位
+ *
+ * 「只回初始态、不释放实例」曾经存在过（单元上的 `reset?.()`）。它被
+ * **整体删除**：不复位实例却想复位世界，必然漏掉装配期只跑一次的东西（`onReady` 副作用、
+ * `config` 快照、连接池）。用例间的复位由 `TestServer.reprovision()` 承担——关掉实例、重新
+ * 装配一遍，新实例的 `init()` 天然给出初始态。删掉这条路径后，单元上不再有「既要在关闭时
+ * 调用、又要能在生命周期中途调用」的双重语义。
+ *
+ * ## `clean` 相位
+ *
+ * `clean` 是**测试期专属**的「清数据」相位（清行、不清结构），对 `resources` 与 `services`
+ * 都成立。它不在关闭流程里，只由 `TestServer.reprovision()` 在重新装配时调用一次，因此
+ * 失败**冒泡**（清不干净还继续跑，后面全是伪绿）。
+ *
+ * `middlewares` 按**数组顺序**注册；它只有 `disposer`，没有逐单元生命周期。
+ */
+export declare const RESOURCES_STAGE = "resources";
+export declare const CONFIG_STAGE = "config";
+export declare const CLIENTS_STAGE = "clients";
+export declare const SERVICES_STAGE = "services";
+export declare const MIDDLEWARES_STAGE = "middlewares";
+export declare const ROUTERS_STAGE = "routers";
+/** 生命周期相位（逐单元日志字段 `phase`） */
+export declare const LIFECYCLE_PHASE_SETUP = "setup";
+export declare const LIFECYCLE_PHASE_INIT = "init";
+export declare const LIFECYCLE_PHASE_DISPOSE = "dispose";
+export declare const LIFECYCLE_PHASE_CLEAN = "clean";
+export type LifecyclePhase = typeof LIFECYCLE_PHASE_SETUP | typeof LIFECYCLE_PHASE_INIT | typeof LIFECYCLE_PHASE_DISPOSE | typeof LIFECYCLE_PHASE_CLEAN;
+/**
+ * 逐单元生命周期日志上下文。
+ *
+ * `log` / `service` 缺省时**不打日志**（纯单测可直接调用生命周期函数，不注入假 logger）。
+ * 字段名固定为全拼：`service` + `unit` + `stage` + `phase`。
+ */
+export interface LifecycleLogContext {
+    /** 日志标签（`defineServer({ app: { service } })`）；缺省时退路名字失去前缀 */
+    service?: string;
+    /** 记录型 logger（`ctx.log`）；缺省 = 不打日志 */
+    log?: LoggerLike;
+}
+/** 逐单元日志字段（全拼）：`unit` = 有效名字（阶段 flush 时为阶段名），`stage` = 阶段名 */
+export interface LifecycleUnitLogFields {
+    service: string;
+    unit: string;
+    stage: string;
+    phase: LifecyclePhase;
+}
+/**
+ * `middlewares` 日志名字：**数组项的名字**（`MiddlewareUnit.name`，或裸函数的占位名 `middleware[i]`）。
+ *
+ * 名字为空串时退路 `<service>:middleware`（仅用于注册期日志，不影响注册序——顺序由数组位置决定）。
+ */
+export declare function middlewareUnitName(service: string, name: string): string;
+/** `initServiceUnits` 入参（参数签名内联对象类型已按 lint 规则外提） */
+export interface InitServiceUnitsParams extends LifecycleLogContext {
+    /** `services(ctx)` 返回的对象（**对象键即单元名**） */
+    services?: Record<string, unknown>;
+}
+/** `setupResourceUnits` / `cleanResourceUnits` / `disposeResourceUnits` 入参（资源单元有 `setup` / `clean` / `dispose`） */
+export interface ResourceLifecycleParams extends LifecycleLogContext {
+    /** 有生命周期方法的资源单元（**按 `resources` 对象声明序**） */
+    units?: readonly ResourceSetupUnit[];
+}
+/** 一个资源单元的可执行生命周期（含名字，用于日志） */
+export interface ResourceSetupUnit {
+    /** `resources` 对象里的键 */
+    name: string;
+    /** `setup()` 本身（已从单元外壳上取好）；无 `setup` 时为 `undefined` */
+    setup?: () => void | Promise<void>;
+    /** `dispose()` 本身（已从单元外壳上取好）；无 `dispose` 时为 `undefined` */
+    dispose?: () => void | Promise<void>;
+    /** `clean()` 本身（已从单元外壳上取好）；无 `clean` 时为 `undefined` */
+    clean?: () => void | Promise<void>;
+}
+/**
+ * 启动序：`services` 按**对象声明序**逐项 `await init?.()`；逐项打日志。
+ */
+export declare function initServiceUnits(params: InitServiceUnitsParams): Promise<void>;
+/**
+ * **测试期清数据**：`services` 按**对象声明序**逐项 `await clean?.()`；逐项打日志。
+ *
+ * ## 它解决的是「库外的服务数据」，不是「内存里的状态」
+ *
+ * 库里那部分数据由资源单元的 `clean()` 负责（`cleanResourceUnits`），因为只有持有连接的
+ * 单元才知道自己的方言与表。但有些服务数据并不在**业务的**库里：
+ *
+ * - 队列命名空间里的 key；
+ * - 临时目录 / 临时文件；
+ * - 外部 mock 的预置状态。
+ *
+ * 删库删不掉这些，而把它们留在世上就成了下一条用例的隐形污染。由单元自己声明 `clean()`
+ * 后，清理变成**单元的公开契约**：单元作者知道怎么清，测试只需要说「给我一份干净基线」。
+ *
+ * ## 与 `init` / `dispose` 的关系
+ *
+ * - `init()` 建状态，`clean()` 只清**数据**、不释放句柄、不重置实例；
+ * - `clean()` **不是** `dispose()`：调用后单元仍可用（但数据已空，只适合紧接着重新装配）；
+ * - 没有 `clean` 的单元被跳过（只有持有库外数据的单元需要实现）；
+ * - 失败**冒泡**：清理没做干净就继续跑，后面的断言全是鬼。
+ *
+ * ## 没有「内存态」相位
+ *
+ * 内存态（限流桶、进程内缓存、写入缓冲区）不靠任何 `reset?.()` 拨回，而由调用方重新装配——
+ * 新实例的 `init()` 天然给出初始态。这比「不复位实例而复位世界」可靠：后者必然漏掉装配期
+ * 只跑一次的东西。
+ */
+export declare function cleanServiceUnits(params: InitServiceUnitsParams): Promise<void>;
+/**
+ * `resources` 的装配期准备：按**对象声明序**逐项 `await setup()`；逐项打日志。
+ *
+ * 与 `initServiceUnits` 同形，差别在单元来源：资源值往往是第三方对象（没有 `setup` 方法），
+ * 单元外壳由 `buildResources` 在解包时收集成 `{ name, setup, dispose }`。
+ *
+ * **失败即中断**：资源准备失败时后续资源、`config`、`services` 都没有意义，直接冒泡给入口，
+ * 由入口把已构造的资源释放掉（与「端口占用」同一处理）。不放进关闭流程聚合——那不是关闭失败。
+ */
+export declare function setupResourceUnits(params: ResourceLifecycleParams): Promise<void>;
+/**
+ * `resources` 的测试期清理：按**对象声明序**逐项 `await clean()`；逐项打日志。
+ *
+ * **失败即冒泡**：清理没做干净就重新装配，后面全是伪绿。
+ *
+ * 「资源 → 服务」的先后由 `cleanServerUnits` 编排，本函数只负责「资源这一段」。
+ */
+export declare function cleanResourceUnits(params: ResourceLifecycleParams): Promise<void>;
+/** `cleanServerUnits` 入参（一次装配的两类单元：资源单元 + 服务单元） */
+export interface CleanServerUnitsParams extends LifecycleLogContext {
+    /** `buildResources` 收集的资源单元（**按 `resources` 对象声明序**） */
+    resources?: readonly ResourceSetupUnit[];
+    /** `services(ctx)` 返回的对象（**对象键即单元名**） */
+    services?: Record<string, unknown>;
+}
+/**
+ * **测试期清数据**：把一次装配里「有 `clean()` 的单元」按固定顺序全跑一遍。
+ *
+ * 顺序不能倒：资源在前、服务在后。数据库资源必须排**最前**（它持有 `TRUNCATE ... CASCADE`），
+ * 服务单元的 `clean()` 之后才轮得到「库外的数据」——先清库再清外部，反过来会把刚插进 mock
+ * 的引用撞成悬空。
+ *
+ * ## 为什么编排在这里，而不是调用方
+ *
+ * 「清哪些、按什么顺序清」是**装配层的事实**：只有 `buildResources` 才知道资源单元是什么、
+ * 只有 `initServiceUnits` 的同一份 `services` 对象才知道服务单元有哪些。测试入口只需要知道
+ * 「我要一份干净基线」——它不该拿到 `ResourceSetupUnit[]` 这种下层产物，更不该自己拼顺序。
+ *
+ * 因此本函数是**唯一**的清数据入口；`TestServer.reprovision()` 只调它，不直接碰下面两个分步。
+ *
+ * **失败冒泡**：清不干净还继续装配，后面的断言全是鬼。
+ */
+export declare function cleanServerUnits(params: CleanServerUnitsParams): Promise<void>;
+/**
+ * `resources` 的关闭：按声明序**逆序**逐项 `await dispose()`。
+ *
+ * 与 `disposeServices` 同语义：单元级失败已 `log.error`，此处吞掉以保证单个资源不阻断其他资源。
+ *
+ * 在关闭流程中排在 `flushResources`（阶段 `Disposer`）**之前**：单元 `dispose` 是资源自己的
+ * 正事（断连），而 `disposer` 是本阶段临时产物的逃生口，后者不应挡住前者。
+ */
+export declare function disposeResourceUnits(params: ResourceLifecycleParams): Promise<void>;
+/** `buildDisposeOrder` / `disposeServiceUnits` 入参（参数签名内联对象类型已按 lint 规则外提） */
+export interface DisposeServiceUnitsParams extends LifecycleLogContext {
+    /** `services(ctx)` 返回的对象（**对象键即单元名**） */
+    services?: Record<string, unknown>;
+}
+/**
+ * 关闭步 `disposeServices`：`services` 声明序逆序释放。
+ *
+ * 单元级失败已在 `runLifecycleUnit` 内 `log.error`（带 service / unit / stage / phase）；
+ * 此处仅保证单步不阻断后续。
+ */
+export declare function disposeServices(params: DisposeServiceUnitsParams): Promise<void>;
+/** `disposeStage` 入参（参数签名内联对象类型已按 lint 规则外提） */
+export interface DisposeStageParams extends LifecycleLogContext {
+    /** 阶段名（`routers` / `middlewares` / `services` / `config` / `resources`） */
+    stage: string;
+    /** 该阶段的 `Disposer`（构造期注册的清理函数，**逆注册序**执行） */
+    disposer: Disposer;
+}
+/**
+ * 关闭步：flush 某个阶段的 `disposer`。
+ *
+ * 单元名 = 阶段名（一个阶段一个 `Disposer`，不逐注册项打日志）；`phase` 固定 `dispose`。
+ * 单个清理函数失败由 `Disposer` 自己捕获记录，不影响同阶段其它函数。
+ */
+export declare function disposeStage(params: DisposeStageParams): Promise<void>;
+//# sourceMappingURL=lifecycle.d.ts.map

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

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

package/output/core/boot/lifecycle.js

@@ -0,0 +1,255 @@
+/**
+ * 生命周期序（N1 §4 / N2 §2.5）。
+ *
+ * **每个阶段一个 `Disposer`**（`ctx.disposer`，所有槽位都有）：在创建某个东西的地方当场
+ * `ctx.disposer.add(() => 释放它)` —— 创建与释放同处一地。
+ *
+ * 关闭时按阶段**逆序 flush**：`routers → middlewares → services → clients → config → resources`
+ * （后创建的先销毁；Prisma / Redis 这类资源最后才断）。
+ *
+ * **`clients` 为什么排在 `services` 之后关**：服务单元 `dispose()` 时可能还要落一次外部调用
+ * （落库、通知、上报），客户端必须先活着。
+ *
+ * **`services` 额外有逐单元生命周期**（两个相位，语义互不替代）：
+ * - 单元之间**不得相互依赖**（`services` 的 ctx 没有 `services` 字段，编译期禁止）；
+ * - `init`（建状态）按**对象声明序**；
+ * - `dispose`（终态释放）**逆序**，只出现在关闭流程里；
+ * - services 阶段内部**先 flush `ctx.disposer`**（构造期注册的清理），再逐单元 `dispose`。
+ *
+ * ## 没有 `reset` 相位
+ *
+ * 「只回初始态、不释放实例」曾经存在过（单元上的 `reset?.()`）。它被
+ * **整体删除**：不复位实例却想复位世界，必然漏掉装配期只跑一次的东西（`onReady` 副作用、
+ * `config` 快照、连接池）。用例间的复位由 `TestServer.reprovision()` 承担——关掉实例、重新
+ * 装配一遍，新实例的 `init()` 天然给出初始态。删掉这条路径后，单元上不再有「既要在关闭时
+ * 调用、又要能在生命周期中途调用」的双重语义。
+ *
+ * ## `clean` 相位
+ *
+ * `clean` 是**测试期专属**的「清数据」相位（清行、不清结构），对 `resources` 与 `services`
+ * 都成立。它不在关闭流程里，只由 `TestServer.reprovision()` 在重新装配时调用一次，因此
+ * 失败**冒泡**（清不干净还继续跑，后面全是伪绿）。
+ *
+ * `middlewares` 按**数组顺序**注册；它只有 `disposer`，没有逐单元生命周期。
+ */
+export const RESOURCES_STAGE = 'resources';
+export const CONFIG_STAGE = 'config';
+export const CLIENTS_STAGE = 'clients';
+export const SERVICES_STAGE = 'services';
+export const MIDDLEWARES_STAGE = 'middlewares';
+export const ROUTERS_STAGE = 'routers';
+/** 生命周期相位（逐单元日志字段 `phase`） */
+export const LIFECYCLE_PHASE_SETUP = 'setup';
+export const LIFECYCLE_PHASE_INIT = 'init';
+export const LIFECYCLE_PHASE_DISPOSE = 'dispose';
+export const LIFECYCLE_PHASE_CLEAN = 'clean';
+function isObject(value) {
+    return typeof value === 'object' && value !== null;
+}
+/**
+ * `middlewares` 日志名字：**数组项的名字**（`MiddlewareUnit.name`，或裸函数的占位名 `middleware[i]`）。
+ *
+ * 名字为空串时退路 `<service>:middleware`（仅用于注册期日志，不影响注册序——顺序由数组位置决定）。
+ */
+export function middlewareUnitName(service, name) {
+    return name.length > 0 ? name : `${service}:middleware`;
+}
+async function callLifecycleMethod(unit, method) {
+    if (isObject(unit) && typeof unit[method] === 'function') {
+        await unit[method]();
+    }
+}
+/**
+ * 执行单个生命周期单元（init / clean / dispose），并打逐单元日志。
+ *
+ * 失败时 `error` 后**重新抛出**：调用方（`startServer` 直接冒泡；关闭流程逐步骤聚合）自行决定后续。
+ */
+async function runLifecycleUnit(params, unit, value, phase) {
+    const fields = { service: params.service ?? '', unit, stage: SERVICES_STAGE, phase };
+    params.log?.debug(fields, `[lifecycle] ${phase} "${unit}" start`);
+    try {
+        if (phase === LIFECYCLE_PHASE_INIT) {
+            await callLifecycleMethod(value, 'init');
+        }
+        else if (phase === LIFECYCLE_PHASE_CLEAN) {
+            await callLifecycleMethod(value, 'clean');
+        }
+        else {
+            await callLifecycleMethod(value, 'dispose');
+        }
+        params.log?.debug(fields, `[lifecycle] ${phase} "${unit}" done`);
+    }
+    catch (error) {
+        params.log?.error({ ...fields, error }, `[lifecycle] ${phase} "${unit}" failed`);
+        throw error;
+    }
+}
+/**
+ * 启动序：`services` 按**对象声明序**逐项 `await init?.()`；逐项打日志。
+ */
+export async function initServiceUnits(params) {
+    for (const key of Object.keys(params.services ?? {})) {
+        await runLifecycleUnit(params, key, params.services?.[key], LIFECYCLE_PHASE_INIT);
+    }
+}
+/**
+ * **测试期清数据**：`services` 按**对象声明序**逐项 `await clean?.()`；逐项打日志。
+ *
+ * ## 它解决的是「库外的服务数据」，不是「内存里的状态」
+ *
+ * 库里那部分数据由资源单元的 `clean()` 负责（`cleanResourceUnits`），因为只有持有连接的
+ * 单元才知道自己的方言与表。但有些服务数据并不在**业务的**库里：
+ *
+ * - 队列命名空间里的 key；
+ * - 临时目录 / 临时文件；
+ * - 外部 mock 的预置状态。
+ *
+ * 删库删不掉这些，而把它们留在世上就成了下一条用例的隐形污染。由单元自己声明 `clean()`
+ * 后，清理变成**单元的公开契约**：单元作者知道怎么清，测试只需要说「给我一份干净基线」。
+ *
+ * ## 与 `init` / `dispose` 的关系
+ *
+ * - `init()` 建状态，`clean()` 只清**数据**、不释放句柄、不重置实例；
+ * - `clean()` **不是** `dispose()`：调用后单元仍可用（但数据已空，只适合紧接着重新装配）；
+ * - 没有 `clean` 的单元被跳过（只有持有库外数据的单元需要实现）；
+ * - 失败**冒泡**：清理没做干净就继续跑，后面的断言全是鬼。
+ *
+ * ## 没有「内存态」相位
+ *
+ * 内存态（限流桶、进程内缓存、写入缓冲区）不靠任何 `reset?.()` 拨回，而由调用方重新装配——
+ * 新实例的 `init()` 天然给出初始态。这比「不复位实例而复位世界」可靠：后者必然漏掉装配期
+ * 只跑一次的东西。
+ */
+export async function cleanServiceUnits(params) {
+    for (const key of Object.keys(params.services ?? {})) {
+        await runLifecycleUnit(params, key, params.services?.[key], LIFECYCLE_PHASE_CLEAN);
+    }
+}
+const RESOURCE_STEP_KEY = {
+    [LIFECYCLE_PHASE_SETUP]: 'setup',
+    [LIFECYCLE_PHASE_DISPOSE]: 'dispose',
+    [LIFECYCLE_PHASE_CLEAN]: 'clean',
+};
+/** 跑一个资源单元生命周期步骤（统一日志，失败冒泡给调用方决定） */
+async function runResourceUnit(params, unit, phase) {
+    const step = unit[RESOURCE_STEP_KEY[phase]];
+    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 clean()`；逐项打日志。
+ *
+ * **失败即冒泡**：清理没做干净就重新装配，后面全是伪绿。
+ *
+ * 「资源 → 服务」的先后由 `cleanServerUnits` 编排，本函数只负责「资源这一段」。
+ */
+export async function cleanResourceUnits(params) {
+    for (const unit of params.units ?? []) {
+        await runResourceUnit(params, unit, LIFECYCLE_PHASE_CLEAN);
+    }
+}
+/**
+ * **测试期清数据**：把一次装配里「有 `clean()` 的单元」按固定顺序全跑一遍。
+ *
+ * 顺序不能倒：资源在前、服务在后。数据库资源必须排**最前**（它持有 `TRUNCATE ... CASCADE`），
+ * 服务单元的 `clean()` 之后才轮得到「库外的数据」——先清库再清外部，反过来会把刚插进 mock
+ * 的引用撞成悬空。
+ *
+ * ## 为什么编排在这里，而不是调用方
+ *
+ * 「清哪些、按什么顺序清」是**装配层的事实**：只有 `buildResources` 才知道资源单元是什么、
+ * 只有 `initServiceUnits` 的同一份 `services` 对象才知道服务单元有哪些。测试入口只需要知道
+ * 「我要一份干净基线」——它不该拿到 `ResourceSetupUnit[]` 这种下层产物，更不该自己拼顺序。
+ *
+ * 因此本函数是**唯一**的清数据入口；`TestServer.reprovision()` 只调它，不直接碰下面两个分步。
+ *
+ * **失败冒泡**：清不干净还继续装配，后面的断言全是鬼。
+ */
+export async function cleanServerUnits(params) {
+    await cleanResourceUnits({ service: params.service, log: params.log, units: params.resources });
+    await cleanServiceUnits({ service: params.service, log: params.log, services: params.services });
+}
+/**
+ * `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) {
+    return Object.keys(params.services ?? {})
+        .reverse()
+        .map((key) => () => runLifecycleUnit(params, key, params.services?.[key], LIFECYCLE_PHASE_DISPOSE));
+}
+/**
+ * 关闭步 `disposeServices`：`services` 声明序逆序释放。
+ *
+ * 单元级失败已在 `runLifecycleUnit` 内 `log.error`（带 service / unit / stage / phase）；
+ * 此处仅保证单步不阻断后续。
+ */
+export async function disposeServices(params) {
+    for (const step of buildDisposeOrder(params)) {
+        try {
+            await step();
+        }
+        catch {
+            // 单元级 `runLifecycleUnit` 已 log.error；此处仅保证不阻断后续
+        }
+    }
+}
+/**
+ * 关闭步：flush 某个阶段的 `disposer`。
+ *
+ * 单元名 = 阶段名（一个阶段一个 `Disposer`，不逐注册项打日志）；`phase` 固定 `dispose`。
+ * 单个清理函数失败由 `Disposer` 自己捕获记录，不影响同阶段其它函数。
+ */
+export async function disposeStage(params) {
+    const fields = {
+        service: params.service ?? '',
+        unit: params.stage,
+        stage: params.stage,
+        phase: LIFECYCLE_PHASE_DISPOSE,
+    };
+    params.log?.debug(fields, `[lifecycle] ${LIFECYCLE_PHASE_DISPOSE} "${params.stage}" start`);
+    await params.disposer.dispose();
+    params.log?.debug(fields, `[lifecycle] ${LIFECYCLE_PHASE_DISPOSE} "${params.stage}" done`);
+}

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

@@ -0,0 +1,34 @@
+/**
+ * 固定关闭步（N1 §5）——**顺序写死在数组里**。
+ *
+ * `disposer` 是所有槽位 ctx 的标配：每个阶段一个 `Disposer`，在**创建处**注册释放。
+ * 关闭时按阶段**逆序 flush**：`routers → middlewares → services → clients → config → resources`
+ * （后创建的先销毁；Prisma / Redis 这类资源**最后**才断）。
+ *
+ * `services` / `resources` 阶段内部保持同一套语义：先 flush 自己的 `disposer`（构造期注册的
+ * 临时产物），再逐单元 `dispose`（声明序**逆序**）。
+ *
+ * ❗`resources` 阶段**顺序与 `services` 相反**：先 `disposeResources`（单元自己的连接）再
+ * `flushResources`（`ctx.disposer` 里的逃生口清理）。理由：单元 `dispose` 是「资源自身怎么关」
+ * 的正事，`disposer` 是临时产物；临时产物可能在 `dispose` 过程中被用到，不能先拆。
+ *
+ * `clients` 排在 `services` **之后**：服务单元 `dispose()` 时可能还要落一次外部调用。
+ *
+ * 固定八步：`flushRouters` → `flushMiddlewares` → `flushServices` → `disposeServices`
+ * → `flushClients` → `flushConfig` → `disposeResources` → `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 {
+    error: (obj: unknown, msg?: string) => void;
+}
+/**
+ * 顺序执行关闭步骤；单步抛错记录后**继续**后续步骤，最后聚合上报
+ * （避免「一步报错导致后面资源没关」）。
+ */
+export declare function runShutdown(handles: ShutdownHandles, log: ShutdownLogger): Promise<void>;
+export {};
+//# sourceMappingURL=shutdown.d.ts.map

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

@@ -0,0 +1 @@
+{"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

@@ -0,0 +1,50 @@
+/**
+ * 固定关闭步（N1 §5）——**顺序写死在数组里**。
+ *
+ * `disposer` 是所有槽位 ctx 的标配：每个阶段一个 `Disposer`，在**创建处**注册释放。
+ * 关闭时按阶段**逆序 flush**：`routers → middlewares → services → clients → config → resources`
+ * （后创建的先销毁；Prisma / Redis 这类资源**最后**才断）。
+ *
+ * `services` / `resources` 阶段内部保持同一套语义：先 flush 自己的 `disposer`（构造期注册的
+ * 临时产物），再逐单元 `dispose`（声明序**逆序**）。
+ *
+ * ❗`resources` 阶段**顺序与 `services` 相反**：先 `disposeResources`（单元自己的连接）再
+ * `flushResources`（`ctx.disposer` 里的逃生口清理）。理由：单元 `dispose` 是「资源自身怎么关」
+ * 的正事，`disposer` 是临时产物；临时产物可能在 `dispose` 过程中被用到，不能先拆。
+ *
+ * `clients` 排在 `services` **之后**：服务单元 `dispose()` 时可能还要落一次外部调用。
+ *
+ * 固定八步：`flushRouters` → `flushMiddlewares` → `flushServices` → `disposeServices`
+ * → `flushClients` → `flushConfig` → `disposeResources` → `flushResources`。
+ *
+ * 每步失败记日志、不阻断后续，最后聚合上报。
+ */
+const SHUTDOWN_ORDER = [
+    'flushRouters',
+    'flushMiddlewares',
+    'flushServices',
+    'disposeServices',
+    'flushClients',
+    'flushConfig',
+    'disposeResources',
+    'flushResources',
+];
+/**
+ * 顺序执行关闭步骤；单步抛错记录后**继续**后续步骤，最后聚合上报
+ * （避免「一步报错导致后面资源没关」）。
+ */
+export async function runShutdown(handles, log) {
+    const errors = [];
+    for (const step of SHUTDOWN_ORDER) {
+        try {
+            await handles[step]();
+        }
+        catch (error) {
+            errors.push(error);
+            log.error({ error, step }, '[shutdown] step failed');
+        }
+    }
+    if (errors.length > 0) {
+        log.error({ errors, count: errors.length }, '[shutdown] completed with errors');
+    }
+}

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

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"signal.d.ts","sourceRoot":"","sources":["../../../source/core/boot/signal.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAC7C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAA;AAE9C;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,eAAe,EAAE,GAAG,EAAE,UAAU,GAAG,MAAM,IAAI,CA2CtF"}

package/output/{app → core/boot}/signal.js

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