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

package/output/app/generate-openapi.test.js

@@ -0,0 +1,123 @@
+import { describe, expect, it } from 'vitest';
+import { z } from 'zod';
+import { defineServer, generateOpenApi, startServer } from './entries.js';
+import { createRedis } from './redis.js';
+/**
+ * `generateOpenApi()` 红线。
+ *
+ * 全程**不得要求配置有效**：不跑 `config` 槽位、不要求 `DATABASE_URL` / `REDIS_URL` 有效、不建连；
+ * `resources`（只构造不建连）/ `services` / 中间件注册 / 路由注册照常执行。
+ * 跳过集：`config` / `initLifecycleUnits` / `listen`。
+ */
+const routeSchema = {
+    querystring: z.object({ name: z.string().optional() }),
+};
+describe('generateOpenApi 红线', () => {
+    it('不跑 config、不要求 DATABASE_URL / REDIS_URL，能出 spec', async () => {
+        delete process.env.DATABASE_URL;
+        delete process.env.REDIS_URL;
+        let configCalls = 0;
+        const server = defineServer({
+            app: { service: 'openapi-test', title: 'OpenAPI Test', version: '1.2.3' },
+            resources: () => ({ database: { connected: false } }),
+            config: () => {
+                configCalls += 1;
+                return {};
+            },
+            services: () => ({}),
+            middlewares: () => [],
+            routers: (ctx) => {
+                ctx.app.get('/widgets', { schema: routeSchema }, () => []);
+            },
+        });
+        const spec = (await generateOpenApi(server));
+        expect(configCalls).toBe(0);
+        expect(spec.openapi).toBe('3.0.3');
+        expect(spec.info).toMatchObject({ title: 'OpenAPI Test', version: '1.2.3' });
+        // 身份块只有 service / title / version：`info.description` 不再由框架填
+        expect(spec.info?.description).toBeUndefined();
+        expect(spec.servers).toEqual([{ url: '/' }]);
+        expect(Object.keys(spec.paths ?? {})).toContain('/widgets');
+        expect(Object.keys(spec.components?.securitySchemes ?? {})).toContain('bearerAuth');
+    });
+    it('跳过集：不跑 config / initLifecycleUnits（但跑 resources / services / 中间件注册 / routers）', async () => {
+        const calls = [];
+        const server = defineServer({
+            app: { service: 'openapi-skip-set', title: 'OpenAPI Skip Set', version: '1.0.0' },
+            resources: () => {
+                calls.push('resources');
+                return {};
+            },
+            config: () => {
+                calls.push('config');
+                return {};
+            },
+            services: () => {
+                calls.push('services');
+                return {
+                    a: {
+                        init: () => {
+                            calls.push('init:a');
+                        },
+                    },
+                };
+            },
+            middlewares: () => [
+                {
+                    name: 'probe',
+                    register: () => {
+                        calls.push('register:probe');
+                    },
+                },
+            ],
+            routers: () => {
+                calls.push('routers');
+            },
+        });
+        await generateOpenApi(server);
+        expect(calls).toEqual(['resources', 'services', 'register:probe', 'routers']);
+    });
+    it('REDIS_URL 存在时仍不建连（惰性包装）', async () => {
+        process.env.REDIS_URL = 'redis://127.0.0.1:1/0';
+        try {
+            const server = defineServer({
+                app: { service: 'openapi-redis-lazy', title: 'Redis Lazy', version: '1.0.0' },
+                // resources 里照常构造 Redis 句柄（惰性包装：不建连、不 ping）
+                resources: (ctx) => ({ redis: createRedis(ctx.env, ctx.log) }),
+                config: () => ({}),
+                services: () => ({}),
+                middlewares: () => [],
+                routers: () => undefined,
+            });
+            const spec = (await generateOpenApi(server));
+            expect(spec.openapi).toBe('3.0.3');
+        }
+        finally {
+            delete process.env.REDIS_URL;
+        }
+    });
+});
+describe('startServer 与 generateOpenApi 共用同一份定义', () => {
+    it('startServer(server, { listen: false }) 返回原生实例、可 inject，且会跑 config', async () => {
+        let configCalls = 0;
+        const server = defineServer({
+            app: { service: 'openapi-shared-definition', title: 'Shared Definition', version: '1.0.0' },
+            resources: () => ({}),
+            config: () => {
+                configCalls += 1;
+                return {};
+            },
+            services: () => ({}),
+            middlewares: () => [],
+            routers: (ctx) => {
+                ctx.app.get('/ping', () => ({ pong: true }));
+            },
+        });
+        const app = await startServer(server, { listen: false });
+        expect(typeof app.inject).toBe('function');
+        const response = await app.inject({ method: 'GET', url: '/ping' });
+        expect(response.statusCode).toBe(200);
+        expect(configCalls).toBe(1);
+        await app.close();
+    });
+});

package/output/app/index.d.ts

@@ -1,16 +1,16 @@
-export { defineServer } from './define-server.js';
-export { loadEnvFiles, ENV_FILE_LAYERS } from './env.js';
-export { createPrismaDatabaseModule } from './database.js';
-export { createEnvModule, createRedisModule, createDefaultModules } from './default-modules.js';
-export { MODULE_NAMES, PENDING_MODULES } from './module.js';
-export { STEP_ORDER, SKIP_BY_MODE } from './steps.js';
-export { SHUTDOWN_ORDER } from './shutdown.js';
-export { assembleModules } from './assemble.js';
-export { attachSignalHandlers } from './signal.js';
-export type { DefineServerOptions, ServerInstance, ServerMode, ErrorFactory, ErrorFactories, RuntimeConfig, ConfigModule, LoggerLike, RedisLike, RedisHandle, DisposeFunction, UnsubscribeFunction, GlobalConfigOptions, DbContext, ServicesContext, InitContext, WorkersContext, ReadyContext, ServerOptions, ResolveMessage, MapStatus, RuntimeState, StepContext, StepRunner, StepImplementations, ShutdownRunner, ShutdownImplementations, ServerHooks, } from './types.js';
-export type { ModuleName, ModuleAssembly, ServerModule, DatabaseModule, DatabaseClientParams, PrismaErrorConstructors, PrismaOperationKey, PrismaOperationLabels, PendingModuleName, PendingModuleStage, } from './module.js';
-export type { ResolvedModules } from './assemble.js';
-export type { StepName } from './steps.js';
-export type { ShutdownStepName } from './shutdown.js';
-export type { PrismaDatabaseModuleParams } from './database.js';
+import './type-augment.js';
+export { defineServer, isServer, SERVER_BRAND, startServer, generateOpenApi } from './entries.js';
+export { loadEnvFiles, loadRuntimeEnvFiles, resolveConfigEnv, ENV_FILE_LAYERS, TEST_ENV_FILE_LAYER, DEFAULT_LOG_LEVEL } from './env.js';
+export type { ConfigEnv } from './env.js';
+export { UserError, SystemError } from './errors.js';
+export { createRedis, createCache, DEFAULT_REDIS_CACHE_TTL_SECONDS } from './redis.js';
+export { createCorsMiddleware, createContextMiddleware, createAuthMiddleware, createRateLimitMiddleware, defaultMiddlewares, defaultAuthSkip } from './middleware/index.js';
+export { REQUEST_ID_HEADER } from './core/request-id.js';
+export { DOC_ROUTE_PREFIX, DOC_SPEC_ROUTE } from './core/openapi.js';
+export { extractPermissionOperations } from './permission-operations.js';
+export type { AppIdentity, AppInstance, LoggerLike, MaybePromise, RedisHandle, Live, ResourcesView, AssertNoDependencies, ServicesShape, ResourcesContext, ResourcesFactory, ConfigContext, ConfigFactory, ServiceUnit, ServiceContext, ServicesFactory, MiddlewareUnit, MiddlewareContext, MiddlewaresFactory, RouterContext, RoutersFactory, ServerConfig, Server, StartServerOptions, ShutdownContext, OpenApiDocument, } from './types.js';
+export type { CacheSetupParams } from './redis.js';
+export type { PermissionOperation } from './permission-operations.js';
+export type { CorsMiddlewareOptions, ContextMiddlewareOptions, AuthMiddlewareOptions, AuthSkip, AuthVerifyInput, AuthVerifyMetadata, AuthVerifyResult, AccountIntegrationConfig, RateLimitMiddlewareOptions } from './middleware/index.js';
+export type { AccessControl, RateLimitRule } from './type-augment.js';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../source/app/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AACjD,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,UAAU,CAAA;AACxD,OAAO,EAAE,0BAA0B,EAAE,MAAM,eAAe,CAAA;AAC1D,OAAO,EAAE,eAAe,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAA;AAC/F,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAC3D,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AACrD,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAA;AAC9C,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAA;AAC/C,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAA;AAElD,YAAY,EACV,mBAAmB,EACnB,cAAc,EACd,UAAU,EACV,YAAY,EACZ,cAAc,EACd,aAAa,EACb,YAAY,EACZ,UAAU,EACV,SAAS,EACT,WAAW,EACX,eAAe,EACf,mBAAmB,EACnB,mBAAmB,EACnB,SAAS,EACT,eAAe,EACf,WAAW,EACX,cAAc,EACd,YAAY,EACZ,aAAa,EACb,cAAc,EACd,SAAS,EACT,YAAY,EACZ,WAAW,EACX,UAAU,EACV,mBAAmB,EACnB,cAAc,EACd,uBAAuB,EACvB,WAAW,GACZ,MAAM,YAAY,CAAA;AACnB,YAAY,EACV,UAAU,EACV,cAAc,EACd,YAAY,EACZ,cAAc,EACd,oBAAoB,EACpB,uBAAuB,EACvB,kBAAkB,EAClB,qBAAqB,EACrB,iBAAiB,EACjB,kBAAkB,GACnB,MAAM,aAAa,CAAA;AACpB,YAAY,EAAE,eAAe,EAAE,MAAM,eAAe,CAAA;AACpD,YAAY,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAA;AAC1C,YAAY,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAA;AACrD,YAAY,EAAE,0BAA0B,EAAE,MAAM,eAAe,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../source/app/index.ts"],"names":[],"mappings":"AAEA,OAAO,mBAAmB,CAAA;AAG1B,OAAO,EAAE,YAAY,EAAE,QAAQ,EAAE,YAAY,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,cAAc,CAAA;AAGjG,OAAO,EAAE,YAAY,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,eAAe,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAA;AACvI,YAAY,EAAE,SAAS,EAAE,MAAM,UAAU,CAAA;AAGzC,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAGpD,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,+BAA+B,EAAE,MAAM,YAAY,CAAA;AAGtF,OAAO,EAAE,oBAAoB,EAAE,uBAAuB,EAAE,oBAAoB,EAAE,yBAAyB,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAA;AAG3K,OAAO,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAA;AACxD,OAAO,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAA;AAGpE,OAAO,EAAE,2BAA2B,EAAE,MAAM,4BAA4B,CAAA;AAGxE,YAAY,EAEV,WAAW,EACX,WAAW,EACX,UAAU,EACV,YAAY,EACZ,WAAW,EAEX,IAAI,EACJ,aAAa,EACb,oBAAoB,EACpB,aAAa,EAEb,gBAAgB,EAChB,gBAAgB,EAChB,aAAa,EACb,aAAa,EACb,WAAW,EACX,cAAc,EACd,eAAe,EACf,cAAc,EACd,iBAAiB,EACjB,kBAAkB,EAClB,aAAa,EACb,cAAc,EAEd,YAAY,EACZ,MAAM,EACN,kBAAkB,EAClB,eAAe,EACf,eAAe,GAChB,MAAM,YAAY,CAAA;AACnB,YAAY,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA;AAClD,YAAY,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAA;AACrE,YAAY,EAAE,qBAAqB,EAAE,wBAAwB,EAAE,qBAAqB,EAAE,QAAQ,EAAE,eAAe,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,wBAAwB,EAAE,0BAA0B,EAAE,MAAM,uBAAuB,CAAA;AAC1O,YAAY,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAA"}

package/output/app/index.js

@@ -1,9 +1,18 @@
-export { defineServer } from './define-server.js';
-export { loadEnvFiles, ENV_FILE_LAYERS } from './env.js';
-export { createPrismaDatabaseModule } from './database.js';
-export { createEnvModule, createRedisModule, createDefaultModules } from './default-modules.js';
-export { MODULE_NAMES, PENDING_MODULES } from './module.js';
-export { STEP_ORDER, SKIP_BY_MODE } from './steps.js';
-export { SHUTDOWN_ORDER } from './shutdown.js';
-export { assembleModules } from './assemble.js';
-export { attachSignalHandlers } from './signal.js';
+// 提供 `request.user` / `request.token` / `request.ctx` 与 `routeOptions.config.accessControls`
+// 的统一类型增强。
+import './type-augment.js';
+// ── 入口 API（N1 §1 / N2 §2.8 / §2.10 / §2.11）───────────────────
+export { defineServer, isServer, SERVER_BRAND, startServer, generateOpenApi } from './entries.js';
+// ── 配置层（env 固定加载）────────────────────────────────────────
+export { loadEnvFiles, loadRuntimeEnvFiles, resolveConfigEnv, ENV_FILE_LAYERS, TEST_ENV_FILE_LAYER, DEFAULT_LOG_LEVEL } from './env.js';
+// ── 错误类型（N2 §2.12）──────────────────────────────────────────
+export { UserError, SystemError } from './errors.js';
+// ── 引导期 helper（`resources(ctx)` 里按需调用）─────────────────
+export { createRedis, createCache, DEFAULT_REDIS_CACHE_TTL_SECONDS } from './redis.js';
+// ── 标准中间件单元 ───────────────────────────────────────────────
+export { createCorsMiddleware, createContextMiddleware, createAuthMiddleware, createRateLimitMiddleware, defaultMiddlewares, defaultAuthSkip } from './middleware/index.js';
+// ── 公共路由 / header 常量 ───────────────────────────────────────
+export { REQUEST_ID_HEADER } from './core/request-id.js';
+export { DOC_ROUTE_PREFIX, DOC_SPEC_ROUTE } from './core/openapi.js';
+// ── 权限操作目录（框架内置；各仓用它替代自写实现）───────────────
+export { extractPermissionOperations } from './permission-operations.js';

package/output/app/lifecycle-logging.test.d.ts

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

package/output/app/lifecycle-logging.test.d.ts.map

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

package/output/app/lifecycle-logging.test.js

@@ -0,0 +1,155 @@
+import { describe, expect, it, vi } from 'vitest';
+import { defineServer, startServer } from './entries.js';
+import { buildDisposeOrder, initServiceUnits, LIFECYCLE_PHASE_DISPOSE, LIFECYCLE_PHASE_INIT, MIDDLEWARES_LOG_STAGE, middlewareUnitName, SERVICES_STAGE, serviceUnitName, } from './lifecycle.js';
+import { createRecordingLogger } from './test-support.js';
+/**
+ * 逐单元日志。
+ *
+ * - **注册期**：每个中间件注册后打一条 `debug`，带 `{ service, unit, stage: 'middlewares' }`；
+ * - **init / dispose**：逐单元 `debug`（开始 / 完成），失败 `error`；带 `{ service, unit, stage, phase }`；
+ * - 中间件名字：`unit.name ?? '<service>:middleware[<index>]'`；services 用对象键。
+ *
+ * 分两层验证：
+ * 1. **单元层**：直接调 `initServiceUnits` / `buildDisposeOrder`，注入记录型 logger；
+ * 2. **真路径**：`startServer(server, { listen: false })` 走完整装配；把框架 logger 的写入流接到
+ *    捕获数组（mock `./core/logging.js` 的 `createLoggerOptions`），再按字段断言。
+ */
+// ── 单元层：记录型 logger ────────────────────────────────────────
+/** 按相位 / 阶段 / 消息片段挑出 `unit` 列表（保序） */
+function unitsOf(log, phase, stage, messagePart) {
+    return log.entries
+        .filter((entry) => entry.level === 'debug' && entry.msg?.includes(messagePart) === true)
+        .map((entry) => entry.obj)
+        .filter((fields) => fields.phase === phase && fields.stage === stage)
+        .map((fields) => fields.unit);
+}
+function expectServiceField(log, service) {
+    const fields = log.entries
+        .filter((entry) => entry.level === 'debug')
+        .map((entry) => entry.obj);
+    expect(fields.length).toBeGreaterThan(0);
+    for (const field of fields) {
+        expect(field.service).toBe(service);
+    }
+}
+describe('逐单元日志：init / dispose', () => {
+    it('init 逐单元 debug：单元名 = 对象键', async () => {
+        const log = createRecordingLogger();
+        const services = {
+            alpha: { init: () => undefined },
+            beta: { init: () => undefined },
+        };
+        await initServiceUnits({ service: 'svc', log, services });
+        expect(unitsOf(log, LIFECYCLE_PHASE_INIT, SERVICES_STAGE, 'start')).toEqual(['alpha', 'beta']);
+        expect(unitsOf(log, LIFECYCLE_PHASE_INIT, SERVICES_STAGE, 'done')).toEqual(['alpha', 'beta']);
+        expectServiceField(log, 'svc');
+        expect(serviceUnitName('alpha')).toBe('alpha');
+    });
+    it('dispose 逐单元 debug：声明序逆序', async () => {
+        const log = createRecordingLogger();
+        const services = {
+            alpha: { dispose: () => undefined },
+            beta: { dispose: () => undefined },
+        };
+        for (const step of buildDisposeOrder({ service: 'svc', log, services })) {
+            await step();
+        }
+        expect(unitsOf(log, LIFECYCLE_PHASE_DISPOSE, SERVICES_STAGE, 'start')).toEqual(['beta', 'alpha']);
+        expectServiceField(log, 'svc');
+    });
+    it('单元 init 抛错 → 逐单元 error（带 unit / stage / phase）后重新抛出', async () => {
+        const log = createRecordingLogger();
+        const services = {
+            boom: {
+                init: () => {
+                    throw new Error('init boom');
+                },
+            },
+        };
+        await expect(initServiceUnits({ service: 'svc', log, services })).rejects.toThrow('init boom');
+        const failure = log.entries.find((entry) => entry.level === 'error');
+        expect(failure).toBeDefined();
+        const fields = failure?.obj;
+        expect(fields.unit).toBe('boom');
+        expect(fields.stage).toBe(SERVICES_STAGE);
+        expect(fields.phase).toBe(LIFECYCLE_PHASE_INIT);
+        expect(fields.error.message).toBe('init boom');
+    });
+    it('不传 logger → 生命周期函数照常工作（纯函数式调用不发日志）', async () => {
+        const calls = [];
+        const services = {
+            alpha: {
+                init: () => {
+                    calls.push('init');
+                },
+            },
+        };
+        await initServiceUnits({ services });
+        expect(calls).toEqual(['init']);
+    });
+    it('中间件日志名字退路：`<service>:middleware[index]`', () => {
+        expect(middlewareUnitName('svc', {}, 3)).toBe('svc:middleware[3]');
+        expect(middlewareUnitName('svc', { name: 'named' }, 1)).toBe('named');
+    });
+});
+// ── 真路径：`startServer` 走完整装配，捕获框架 logger 写入 ────────
+const captured = vi.hoisted(() => ({ lines: [] }));
+vi.mock('./core/logging.js', () => ({
+    LOG_REDACT_PATHS: [],
+    // 把 pino 的目标流换成捕获数组（level=debug，否则逐单元 debug 不会落盘）
+    createLoggerOptions: () => ({
+        level: 'debug',
+        stream: {
+            write: (chunk) => {
+                captured.lines.push(chunk);
+            },
+        },
+    }),
+}));
+function capturedRecords() {
+    return captured.lines
+        .join('')
+        .split('\n')
+        .filter((line) => line.trim().length > 0)
+        .map((line) => JSON.parse(line));
+}
+/** 按字段匹配捕获到的记录（pino 还会加 `time` / `pid` 等，故只比关键字段） */
+function matchRecords(records, match) {
+    return records.filter((record) => Object.entries(match).every(([key, value]) => record[key] === value));
+}
+describe('startServer 真路径：注册 / init / dispose 逐单元日志', () => {
+    it('中间件注册、services 的 init / dispose 日志都能拿到名字；未命名用退路', async () => {
+        captured.lines.length = 0;
+        const server = defineServer({
+            app: { service: 'logging-svc', title: 'Logging Service', version: '1.0.0' },
+            resources: () => ({}),
+            config: () => ({}),
+            services: () => ({
+                alpha: {
+                    init: () => undefined,
+                    dispose: () => undefined,
+                },
+            }),
+            middlewares: () => [
+                { name: 'named', register: () => undefined },
+                // 未命名 → 退路 `logging-svc:middleware[1]`
+                { register: () => undefined },
+            ],
+            routers: () => undefined,
+        });
+        const app = await startServer(server, { listen: false });
+        await app.close();
+        const records = capturedRecords();
+        // 注册期：字段 `{ service, unit, stage }`，未命名走退路
+        const registered = matchRecords(records, { msg: '[middleware] registered' });
+        expect(matchRecords(registered, { unit: 'named', stage: MIDDLEWARES_LOG_STAGE }).length).toBe(1);
+        expect(matchRecords(registered, { unit: 'logging-svc:middleware[1]', stage: MIDDLEWARES_LOG_STAGE }).length).toBe(1);
+        expect(matchRecords(registered, { service: 'logging-svc' }).length).toBe(2);
+        // init / dispose：services 逐单元 debug（带 `phase`）
+        expect(matchRecords(records, { unit: 'alpha', stage: SERVICES_STAGE, phase: LIFECYCLE_PHASE_INIT }).length).toBeGreaterThan(0);
+        expect(matchRecords(records, { unit: 'alpha', stage: SERVICES_STAGE, phase: LIFECYCLE_PHASE_DISPOSE }).length).toBeGreaterThan(0);
+        // 中间件**不参与生命周期**：没有 middlewares 阶段的 init / dispose 日志
+        expect(matchRecords(records, { stage: MIDDLEWARES_LOG_STAGE, phase: LIFECYCLE_PHASE_INIT })).toHaveLength(0);
+        expect(matchRecords(records, { stage: MIDDLEWARES_LOG_STAGE, phase: LIFECYCLE_PHASE_DISPOSE })).toHaveLength(0);
+    });
+});

package/output/app/lifecycle.d.ts

@@ -0,0 +1,70 @@
+import type { LoggerLike } from './types.js';
+/**
+ * 生命周期序（N1 §4 / N2 §2.5）。
+ *
+ * **只有 `services` 参与生命周期**：
+ * - 单元之间**不得相互依赖**（`services` 的 ctx 没有 `services` 字段，编译期禁止）；
+ * - 顺序语义只有一条：按**对象声明序** `init`、**逆序** `dispose`；
+ * - `middlewares` 按数组序注册，**不参与生命周期**（要常驻资源就放 `services`）；
+ * - `resources` 只是惰性包装（构造不建连），框架不替它们做生命周期。
+ */
+export declare const SERVICES_STAGE = "services";
+/** `middlewares` 的**注册期日志**阶段标签（中间件不参与生命周期，只用于注册日志） */
+export declare const MIDDLEWARES_LOG_STAGE = "middlewares";
+/** 生命周期相位（逐单元日志字段 `phase`） */
+export declare const LIFECYCLE_PHASE_INIT = "init";
+export declare const LIFECYCLE_PHASE_DISPOSE = "dispose";
+export type LifecyclePhase = typeof LIFECYCLE_PHASE_INIT | typeof LIFECYCLE_PHASE_DISPOSE;
+/**
+ * 逐单元生命周期日志上下文。
+ *
+ * `log` / `service` 缺省时**不打日志**（纯单测可直接调用生命周期函数，不注入假 logger）。
+ * 字段名固定为全拼：`service` + `unit` + `stage` + `phase`。
+ */
+export interface LifecycleLogContext {
+    /** 日志标签（`defineServer({ app: { service } })`）；缺省时退路名字失去前缀 */
+    service?: string;
+    /** 记录型 logger（`ctx.log`）；缺省 = 不打日志 */
+    log?: LoggerLike;
+}
+/** 逐单元日志字段（全拼）：`unit` = 有效名字，`stage` = `services` */
+export interface LifecycleUnitLogFields {
+    service: string;
+    unit: string;
+    stage: string;
+    phase: LifecyclePhase;
+}
+/**
+ * `services` 有效名字：**对象键即单元名**（N1 §4：没有 `name` 字段）。
+ */
+export declare function serviceUnitName(key: string): string;
+/**
+ * `middlewares` 日志名字：`unit.name ?? '<service>:middleware[<index>]'`（仅用于注册期日志）。
+ */
+export declare function middlewareUnitName(service: string, unit: unknown, index: number): string;
+/** `initServiceUnits` 入参（参数签名内联对象类型已按 lint 规则外提） */
+export interface InitServiceUnitsParams extends LifecycleLogContext {
+    /** `services(ctx)` 返回的对象（**对象键即单元名**） */
+    services?: Record<string, unknown>;
+}
+/**
+ * 启动序：`services` 按**对象声明序**逐项 `await init?.()`；逐项打日志。
+ */
+export declare function initServiceUnits(params: InitServiceUnitsParams): Promise<void>;
+/** `buildDisposeOrder` / `disposeServiceUnits` 入参（参数签名内联对象类型已按 lint 规则外提） */
+export interface DisposeServiceUnitsParams extends LifecycleLogContext {
+    /** `services(ctx)` 返回的对象（**对象键即单元名**） */
+    services?: Record<string, unknown>;
+}
+/**
+ * 关闭序：`services` 按声明序**逆序**逐项 `dispose?.()`。
+ */
+export declare function buildDisposeOrder(params: DisposeServiceUnitsParams): Array<() => void | Promise<void>>;
+/**
+ * 关闭步 `disposeServices`：`services` 声明序逆序释放。
+ *
+ * 单元级失败已在 `runLifecycleUnit` 内 `log.error`（带 service / unit / stage / phase）；
+ * 此处仅保证单步不阻断后续。
+ */
+export declare function disposeServices(params: DisposeServiceUnitsParams): Promise<void>;
+//# sourceMappingURL=lifecycle.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle.d.ts","sourceRoot":"","sources":["../../source/app/lifecycle.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AAE5C;;;;;;;;GAQG;AAEH,eAAO,MAAM,cAAc,aAAa,CAAA;AACxC,uDAAuD;AACvD,eAAO,MAAM,qBAAqB,gBAAgB,CAAA;AAElD,8BAA8B;AAC9B,eAAO,MAAM,oBAAoB,SAAS,CAAA;AAC1C,eAAO,MAAM,uBAAuB,YAAY,CAAA;AAChD,MAAM,MAAM,cAAc,GAAG,OAAO,oBAAoB,GAAG,OAAO,uBAAuB,CAAA;AAEzF;;;;;GAKG;AACH,MAAM,WAAW,mBAAmB;IAClC,6DAA6D;IAC7D,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,sCAAsC;IACtC,GAAG,CAAC,EAAE,UAAU,CAAA;CACjB;AAED,qDAAqD;AACrD,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,MAAM,CAAA;IACf,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,cAAc,CAAA;CACtB;AAMD;;GAEG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAKxF;AAED,oDAAoD;AACpD,MAAM,WAAW,sBAAuB,SAAQ,mBAAmB;IACjE,yCAAyC;IACzC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACnC;AAmCD;;GAEG;AACH,wBAAsB,gBAAgB,CAAC,MAAM,EAAE,sBAAsB,GAAG,OAAO,CAAC,IAAI,CAAC,CAIpF;AAED,6EAA6E;AAC7E,MAAM,WAAW,yBAA0B,SAAQ,mBAAmB;IACpE,yCAAyC;IACzC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACnC;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,yBAAyB,GAAG,KAAK,CAAC,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAMtG;AAED;;;;;GAKG;AACH,wBAAsB,eAAe,CAAC,MAAM,EAAE,yBAAyB,GAAG,OAAO,CAAC,IAAI,CAAC,CAQtF"}

package/output/app/lifecycle.js

@@ -0,0 +1,99 @@
+/**
+ * 生命周期序（N1 §4 / N2 §2.5）。
+ *
+ * **只有 `services` 参与生命周期**：
+ * - 单元之间**不得相互依赖**（`services` 的 ctx 没有 `services` 字段，编译期禁止）；
+ * - 顺序语义只有一条：按**对象声明序** `init`、**逆序** `dispose`；
+ * - `middlewares` 按数组序注册，**不参与生命周期**（要常驻资源就放 `services`）；
+ * - `resources` 只是惰性包装（构造不建连），框架不替它们做生命周期。
+ */
+export const SERVICES_STAGE = 'services';
+/** `middlewares` 的**注册期日志**阶段标签（中间件不参与生命周期，只用于注册日志） */
+export const MIDDLEWARES_LOG_STAGE = 'middlewares';
+/** 生命周期相位（逐单元日志字段 `phase`） */
+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` 字段）。
+ */
+export function serviceUnitName(key) {
+    return key;
+}
+/**
+ * `middlewares` 日志名字：`unit.name ?? '<service>:middleware[<index>]'`（仅用于注册期日志）。
+ */
+export function middlewareUnitName(service, unit, index) {
+    if (isObject(unit) && typeof unit.name === 'string' && unit.name.length > 0) {
+        return unit.name;
+    }
+    return `${service}:middleware[${index}]`;
+}
+async function callInit(unit) {
+    if (isObject(unit) && typeof unit.init === 'function') {
+        await unit.init();
+    }
+}
+async function callDispose(unit) {
+    if (isObject(unit) && typeof unit.dispose === 'function') {
+        await unit.dispose();
+    }
+}
+/**
+ * 执行单个生命周期单元（init / 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 callInit(value);
+        }
+        else {
+            await callDispose(value);
+        }
+        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, serviceUnitName(key), params.services?.[key], LIFECYCLE_PHASE_INIT);
+    }
+}
+/**
+ * 关闭序：`services` 按声明序**逆序**逐项 `dispose?.()`。
+ */
+export 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;
+}
+/**
+ * 关闭步 `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；此处仅保证不阻断后续
+        }
+    }
+}

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

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

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

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