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

package/output/app/error-contract.test.d.ts

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

package/output/app/error-contract.test.d.ts.map

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

package/output/app/error-contract.test.js

@@ -0,0 +1,125 @@
+import { describe, expect, it } from 'vitest';
+import { z } from 'zod';
+import { defineServer, startServer } from './entries.js';
+import { SystemError, UserError } from './errors.js';
+/**
+ * 错误契约——**强制、不可配置**。
+ *
+ * 响应信封 `{ status, message, data }`（错误时 `data: null`，`status` 放错误码字符串）；
+ * 映射固定：`UserError`→400（`error.status` 字面量）/ `SystemError`→500 / zod→400 / 未知→500 /
+ * 未匹配路由→404。错误只给稳定**码**，文案不归框架。
+ */
+/** zod validator 由 core 的 `schema` 统一装配，运行时按 zod 校验（类型上仍是 FastifySchema） */
+const validatedQuerySchema = {
+    querystring: z.object({ count: z.coerce.number().int().min(1) }),
+};
+function createErrorContractServer() {
+    return defineServer({
+        app: { service: 'error-contract', title: 'Error Contract', version: '1.0.0' },
+        resources: () => ({}),
+        config: () => ({}),
+        services: () => ({}),
+        middlewares: () => [],
+        routers: (ctx) => {
+            ctx.app.get('/ok', () => ({ hello: 'world' }));
+            ctx.app.get('/envelope', () => ({ status: 'CUSTOM', message: 'm', data: 1 }));
+            ctx.app.get('/user-error', () => {
+                throw new UserError('INVALID_TOKEN', undefined, 'token 无效');
+            });
+            ctx.app.get('/system-error', () => {
+                throw new SystemError('DATABASE_UNAVAILABLE', undefined, '数据库不可用');
+            });
+            ctx.app.get('/unknown-error', () => {
+                throw new Error('boom');
+            });
+            ctx.app.get('/validated', { schema: validatedQuerySchema }, (request) => ({
+                count: request.query.count,
+            }));
+        },
+    });
+}
+describe('错误契约', () => {
+    it('成功信封：{ status: SUCCESS, message: ok, data }', async () => {
+        const app = await startServer(createErrorContractServer(), { listen: false });
+        const response = await app.inject({ method: 'GET', url: '/ok' });
+        expect(response.statusCode).toBe(200);
+        expect(response.json()).toEqual({ status: 'SUCCESS', message: 'ok', data: { hello: 'world' } });
+        await app.close();
+    });
+    it('已是信封的载荷不被二次包裹', async () => {
+        const app = await startServer(createErrorContractServer(), { listen: false });
+        const response = await app.inject({ method: 'GET', url: '/envelope' });
+        expect(response.statusCode).toBe(200);
+        expect(response.json()).toEqual({ status: 'CUSTOM', message: 'm', data: 1 });
+        await app.close();
+    });
+    it('UserError → 400（取 `error.status` 字面量），status 放错误码、data 为 null', async () => {
+        const app = await startServer(createErrorContractServer(), { listen: false });
+        const response = await app.inject({ method: 'GET', url: '/user-error' });
+        expect(response.statusCode).toBe(400);
+        expect(response.json()).toEqual({ status: 'INVALID_TOKEN', message: 'token 无效', data: null });
+        await app.close();
+    });
+    it('SystemError → 500（取 `error.status` 字面量）', async () => {
+        const app = await startServer(createErrorContractServer(), { listen: false });
+        const response = await app.inject({ method: 'GET', url: '/system-error' });
+        expect(response.statusCode).toBe(500);
+        expect(response.json()).toEqual({ status: 'DATABASE_UNAVAILABLE', message: '数据库不可用', data: null });
+        await app.close();
+    });
+    it('未知错误 → 500 + UNKNOWN_ERROR', async () => {
+        const app = await startServer(createErrorContractServer(), { listen: false });
+        const response = await app.inject({ method: 'GET', url: '/unknown-error' });
+        expect(response.statusCode).toBe(500);
+        expect(response.json()).toEqual({ status: 'UNKNOWN_ERROR', message: 'boom', data: null });
+        await app.close();
+    });
+    it('zod 校验失败 → 400（INVALID_INPUT）；通过校验 → 200', async () => {
+        const app = await startServer(createErrorContractServer(), { listen: false });
+        const invalid = await app.inject({ method: 'GET', url: '/validated?count=0' });
+        expect(invalid.statusCode).toBe(400);
+        const invalidBody = invalid.json();
+        expect(invalidBody.status).toBe('INVALID_INPUT');
+        expect(invalidBody.data).toBeNull();
+        expect(invalidBody.message).toContain('count');
+        const valid = await app.inject({ method: 'GET', url: '/validated?count=3' });
+        expect(valid.statusCode).toBe(200);
+        expect(valid.json()).toEqual({ status: 'SUCCESS', message: 'ok', data: { count: 3 } });
+        await app.close();
+    });
+    it('未匹配路由 → 404 + NOT_IMPLEMENTED', async () => {
+        const app = await startServer(createErrorContractServer(), { listen: false });
+        const response = await app.inject({ method: 'GET', url: '/missing' });
+        expect(response.statusCode).toBe(404);
+        const body = response.json();
+        expect(body.status).toBe('NOT_IMPLEMENTED');
+        expect(body.data).toBeNull();
+        expect(body.message).toContain('GET /missing');
+        await app.close();
+    });
+    it('资源包里的 `classifyError` 被用作数据层错误分类（→500）', async () => {
+        const server = defineServer({
+            app: { service: 'error-contract-database', title: 'Error Contract Database', version: '1.0.0' },
+            resources: () => ({
+                database: {
+                    classifyError: (error) => error instanceof Error && error.message === 'pg down'
+                        ? new SystemError('DATABASE_ERROR', { operation: 'query' }, 'pg down')
+                        : null,
+                },
+            }),
+            config: () => ({}),
+            services: () => ({}),
+            middlewares: () => [],
+            routers: (ctx) => {
+                ctx.app.get('/database-down', () => {
+                    throw new Error('pg down');
+                });
+            },
+        });
+        const app = await startServer(server, { listen: false });
+        const response = await app.inject({ method: 'GET', url: '/database-down' });
+        expect(response.statusCode).toBe(500);
+        expect(response.json()).toEqual({ status: 'DATABASE_ERROR', message: 'pg down', data: null });
+        await app.close();
+    });
+});

package/output/app/errors.d.ts

@@ -0,0 +1,20 @@
+import type { ErrorContext } from '@taicode/common-base';
+export declare class UserError extends Error {
+    readonly type: string;
+    readonly context?: ErrorContext | undefined;
+    /** 类型守卫（`Symbol.for` 品牌，不用 `instanceof`） */
+    static is(value: unknown): value is UserError;
+    /** 固定 HTTP 状态（字面量类型） */
+    readonly status: 400;
+    constructor(type: string, context?: ErrorContext | undefined, message?: string);
+}
+export declare class SystemError extends Error {
+    readonly type: string;
+    readonly context?: ErrorContext | undefined;
+    /** 类型守卫（`Symbol.for` 品牌，不用 `instanceof`） */
+    static is(value: unknown): value is SystemError;
+    /** 固定 HTTP 状态（字面量类型） */
+    readonly status: 500;
+    constructor(type: string, context?: ErrorContext | undefined, message?: string);
+}
+//# sourceMappingURL=errors.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../source/app/errors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAA;AAsBxD,qBAAa,SAAU,SAAQ,KAAK;aASC,IAAI,EAAE,MAAM;aAAkB,OAAO,CAAC,EAAE,YAAY;IARvF,4CAA4C;IAC5C,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,SAAS;IAI7C,wBAAwB;IACxB,QAAQ,CAAC,MAAM,EAAG,GAAG,CAAS;gBAEK,IAAI,EAAE,MAAM,EAAkB,OAAO,CAAC,EAAE,YAAY,YAAA,EAAE,OAAO,SAAK;CAKtG;AAED,qBAAa,WAAY,SAAQ,KAAK;aASD,IAAI,EAAE,MAAM;aAAkB,OAAO,CAAC,EAAE,YAAY;IARvF,4CAA4C;IAC5C,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,WAAW;IAI/C,wBAAwB;IACxB,QAAQ,CAAC,MAAM,EAAG,GAAG,CAAS;gBAEK,IAAI,EAAE,MAAM,EAAkB,OAAO,CAAC,EAAE,YAAY,YAAA,EAAE,OAAO,SAAK;CAKtG"}

package/output/app/errors.js

@@ -0,0 +1,51 @@
+/**
+ * 错误契约（N2 §2.12）。
+ *
+ * 框架直接提供并导出 `UserError` / `SystemError`：
+ * - `status` 是**字面量**（`400` / `500`）—— 映射表写成
+ *   `Record<UserError['status'] | SystemError['status'], number>` 时若改错直接编译失败；
+ * - `is()` 是**类型守卫**，走 `Symbol.for` 品牌（**不用 `instanceof`**：跨包 / 编译后 / 原型链丢失
+ *   都仍然可靠）；品牌与 `@taicode/common-base` 同名，故基座抛出的同类错误同样被识别；
+ * - 业务只抛这两个错误，状态码映射由框架固定（`UserError`→400 / `SystemError`→500）。
+ *
+ * 构造签名保持 `(code, context?, message?)`。
+ */
+const USER_ERROR_BRAND = Symbol.for('@taicode/common/UserError');
+const SYSTEM_ERROR_BRAND = Symbol.for('@taicode/common/SystemError');
+function hasBrand(value, brand) {
+    return typeof value === 'object' && value !== null && value[brand] === true;
+}
+export class UserError extends Error {
+    type;
+    context;
+    /** 类型守卫（`Symbol.for` 品牌，不用 `instanceof`） */
+    static is(value) {
+        return hasBrand(value, USER_ERROR_BRAND);
+    }
+    /** 固定 HTTP 状态（字面量类型） */
+    status = 400;
+    constructor(type, context, message = '') {
+        super(message, context);
+        this.type = type;
+        this.context = context;
+        this.name = 'UserError';
+        Object.defineProperty(this, USER_ERROR_BRAND, { value: true });
+    }
+}
+export class SystemError extends Error {
+    type;
+    context;
+    /** 类型守卫（`Symbol.for` 品牌，不用 `instanceof`） */
+    static is(value) {
+        return hasBrand(value, SYSTEM_ERROR_BRAND);
+    }
+    /** 固定 HTTP 状态（字面量类型） */
+    status = 500;
+    constructor(type, context, message = '') {
+        super(message, context);
+        this.type = type;
+        this.context = context;
+        this.name = 'SystemError';
+        Object.defineProperty(this, SYSTEM_ERROR_BRAND, { value: true });
+    }
+}

package/output/app/generate-openapi.test.d.ts

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

package/output/app/generate-openapi.test.d.ts.map

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

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

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

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

@@ -0,0 +1,18 @@
+// 提供 `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"}