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

package/output/core/types.d.ts

@@ -6,18 +6,23 @@ import type { ConfigEnv } from './env.js';
 /**
  * `defineServer` 槽位口径与接口类型（N1 / N2，**唯一规格来源**）。
  *
- * 顶层是「一个身份块 + 六个工厂槽位」，**键顺序即分层**：
+ * 顶层是「一个身份块 + 工厂槽位」，**键顺序即分层**（`clients` 可选）：
  *
  * ```
  * app            （身份块，无依赖）
  * resources      ← env                            引导期：唯一读 env 的地方
  * config         ← env + resources                引导期：❗不给 services（结构性解耦）
- * clients        ← resources + config             外部服务客户端：❗不给 env / services / app
+ * clients        ← resources + config（可选）      外部服务客户端：❗不给 env / services / app
  * services       ← resources + config + clients   运行期开始：❗不给 env、不给 services
- * middlewares    ← app + services + config + clients （不给 resources / env）
+ * middlewares    ← app + services + config + clients （不给 resources / env）；**有序数组**
  * routers        ← app + services + clients       （不给 resources / env / config）
  * ```
  *
+ * 应用扩展 env（`Env`）**不是槽位**，而是 `defineServer` 的**第一个泛型**：可**单独手写**
+ * `defineServer<{ FOO?: string }>({...})`，也可不写、从 `resources` / `config` 的 `ctx` 类型标注
+ * 推导（`ResourcesContext<Env>`）。⚠️ 手写 `Env` 会让其余泛型停止推导（退化为 `object`，TS 限制），
+ * 详见 `defineServer` 文档。加载仍走内置逻辑，框架不提供自定义加载。
+ *
  * 槽位只能引用**排在它前面**的产物（向下引用是编译错误）；`env` 只属引导期
  * （`resources` / `config` 可见，运行期三层一律看不到）。
  *
@@ -36,13 +41,12 @@ import type { ConfigEnv } from './env.js';
  *
  * 类型安全机制（N2 §1）：
  * - **M1 分阶段 ctx**：每个工厂只拿到「该阶段该看的字段」（**外加每个阶段都有的 `disposer`**）；
- * - **M2 `Awaited<>` 归一**：工厂签名写 `(ctx) => R`（不是 `R | Promise<R>`），下游一律
- *   `Awaited<R>` / `Awaited<C>` / `Awaited<CL>` / `Awaited<S>`；
+ * - **M2 `Awaited<>` 归一**：工厂签名写 `(ctx) => Resources`（不是 `Resources | Promise<Resources>`），下游一律
+ *   `Awaited<Resources>` / `Awaited<Config>` / `Awaited<Clients>` / `Awaited<Services>`；
  * - **M3 资源嵌套**：资源包挂在 `ctx.resources` 上（不再摊平到 ctx，键冲突从根上消失）；
- * - **M4 `Live<T>` 静态开关**：资源包 / 客户端包里值为 `false` 的键在类型上剔除；
- * - **M5 强类型 `services`**：`middlewares` / `routers` 的 `ctx.services` 是 `S` 实体；
- * - **M6 品牌 + 类型守卫**：`Server` 带品牌，`isServer()` 收窄；
- * - **M7 负向类型测试**：`define-server.negative-cases.ts`，由 `tsc --noEmit` 覆盖。
+ * - **M4 `Live<Value>` 静态开关**：资源包 / 客户端包里值为 `false` 的键在类型上剔除；
+ * - **M5 强类型 `services`**：`middlewares` / `routers` 的 `ctx.services` 是 `Services` 实体；
+ * - **M6 品牌**：`Server` 带 `__brand`（`SERVER_BRAND`），只能由 `defineServer` 产出，入口函数据此拒收裸对象。
  *
  * 命名全拼：`requestId` / `database` / `configuration` / `service`（不用 `db` / `cfg`）。
  */
@@ -67,8 +71,8 @@ export type AppInstance = FastifyInstance<RawServerDefault, IncomingMessage, Ser
  */
 export interface AppIdentity {
     /** 权限注册键 / cache 前缀 / 失效通道前缀 / 日志标签 */
-    readonly service: string;
     readonly title: string;
+    readonly service: string;
     /** openapi `info.version` + 权限操作自注册；建议从 package.json 读入 */
     readonly version: string;
 }
@@ -83,18 +87,143 @@ export interface RedisHandle {
     dispose: () => void | Promise<void>;
 }
 /**
- * 剔掉值为 `false` 的键（编译期静态开关）。
+ * 资源单元：**值 + 生命周期分离**。
+ *
+ * 为什么不把生命周期挂在值上（像 service 的 `init` / `dispose`）：资源多是**第三方对象**
+ * （`PrismaClient`、Redis client、连接池），形状改不了 —— `prisma.setup = …` 是在改别人的类型。
+ * 单元是框架私有外壳，`value` 保持原样。
+ *
+ * ## 与 `ctx.disposer` 的分工
+ *
+ * 两者都能释放，但默认路径不同：
+ * - **资源自己的连接 / 句柄 → `dispose()`**：它和资源写在同一个对象里，一处表达完。
+ * - **`ctx.disposer` → 逃生口**：非常规清理（不是这个资源自身的句柄、需要跨资源协调、
+ *   临时产物），或资源值确实是裸对象、不想包单元时。
+ *
+ * 这正是「框架收起具体实现，`ctx` 留给特殊情况」的分工：正常情况不需要知道 `ctx.disposer`
+ * 存在。
+ *
+ * ## 两个生命周期，各管一段
+ *
+ * | 方法 | 谁调 | 何时 |
+ * | --- | --- | --- |
+ * | `setup()` | 框架（两个入口） | 装配期，`config` 之前 |
+ * | `dispose()` | 框架（关闭流程） | 进程关闭，最后一步 |
+ *
+ * 两者互不替代：`setup()` 是「连接前把地基铺好」（状态驱动的迁移 / 预热），`dispose()` 断开的是
+ * **连接**（一次性）。
+ *
+ * ## 用例间的样本数据不在资源上
+ *
+ * 「清表 + 重新插入样本数据」这伴事**不属于资源**：资源只知道有哪些表 / 哪些 key，不知道谁往里
+ * 写了什么。写在资源上就意味着新增一个 model 要回去改一次清库清单，漏改只会安静地变脏。
+ *
+ * 因此它单独做成一套机制：**`testdata/` 目录 + 每脚本自带 `load()` / `cleanup()`**，只在
+ * 可清理环境执行（见 `test-support/testdata.ts`）。
+ *
+ * ```ts
+ * resources: (ctx) => ({
+ *   database: defineResource(createPrisma(ctx.env.DATABASE_URL), {
+ *     // 自动执行：startServer / createTestServer 都会调，生产与测试同一份
+ *     async setup() { await pushSchema(ctx.env.DATABASE_URL) },
+ *     dispose: () => prisma.$disconnect(),
+ *   }),
+ *   cache: ctx.env.REDIS_URL ? defineResource(createRedis(ctx.env.REDIS_URL)) : false,
+ * })
+ * ```
+ */
+export interface ResourceUnit<Value> {
+    /** 真正的资源对象（框架不碰） */
+    readonly value: Value;
+    /**
+     * 装配期准备（建连验证、同步库结构、预热……）。
+     *
+     * **何时跑**：`resources` 槽位构造完成后、`config` 槽位之前，按**对象声明序**逐项 `await`。
+     * 排在 `config` 之前是硬要求：`config` 常从数据库读（如 `SystemConfig` 表），库没准备好
+     * 它就连不上。
+     *
+     * **谁跑**：框架。两个入口都调，应用永不手调；`generateOpenApi` 不调（出 spec 不构造资源）。
+     *
+     * **不要在这里写 `if (ENV === 'test')`**：准备动作本身应当是状态驱动的（迁移工具会自己比对
+     * 现状、只补差量），生产与测试跑同一份代码。需要区分环境时，区分点应当来自 `ctx.env`，
+     * 而不是「跑不跑这个函数」。
+     */
+    setup?(): void | Promise<void>;
+    /**
+     * 关闭时释放本资源（断连、清池、flush……）。
+     *
+     * **何时跑**：关闭流程的最后一步（`resources` 阶段），按声明序**逆序**逐项 `await`——
+     * 后创建的先销毁；此时 `services` / `clients` / `config` 都已关完，不会再有使用方。
+     *
+     * **unit 级失败只记日志、不阻断其他资源**（关闭不能半途中断）。
+     */
+    dispose?(): void | Promise<void>;
+}
+/** 资源单元的生命周期（`defineResource` 的第二个参数） */
+export interface ResourceLifecycle {
+    setup?(): void | Promise<void>;
+    dispose?(): void | Promise<void>;
+}
+/**
+ * 构造资源单元（唯一的正当方式）。
  *
- * 资源包里写 `cache: false` 表示**静态关闭**：`Live<T>` 里该键**不存在**，访问直接编译失败；
- * 而 `cache: Cache | undefined`（显式可选）表示**运行时缺省**：键存在，类型为 `Cache | undefined`。
+ * 实现见 `core/resource.ts`（`types.ts` 只放类型，不放运行时值）。
  */
-export type Live<T> = {
-    [K in keyof T as T[K] extends false ? never : K]: T[K];
+export type DefineResource = <Value>(value: Value, lifecycle?: ResourceLifecycle) => ResourceUnit<Value>;
+/** 单元 → 值；非单元原样通过（`defineResource` 是可选的，裸对象照旧可用） */
+type UnwrapResource<Value> = Value extends ResourceUnit<infer Inner> ? Inner : Value;
+/**
+ * 剔掉「静态关闭」的键，并从保留键的类型里抹掉 `false` 分支（编译期静态开关）。
+ *
+ * 三种写法，三种语义，都被精确表达：
+ * - `cache: false`（**纯 `false`**）→ **静态关闭**：`Live<Value>` 里该键**不存在**，访问直接编译失败；
+ * - `cache: Cache | false`（**条件构造**）→ 键**保留**，但类型收窄为 `Cache`（`false` 分支被
+ *   `Exclude` 抹掉）——运行期 `liveResources` 会剔掉值为 `false` 的那一项，所以类型与运行时一致；
+ * - `cache: Cache | undefined`（**显式可选**）→ 键存在、类型保持 `Cache | undefined`（`undefined`
+ *   表示「运行时缺省」，与「静态关闭」语义不同，不受影响）。
+ *
+ * 旧版 `Value[K] extends false ? never : K` 只能处理「纯 `false`」，遇到 `Cache | false` 会把
+ * 整个键保留且类型仍含 `false`（与运行时剔除行为不符）。现版用 `Exclude<Value[K], false>` 对齐。
+ */
+export type Live<Value> = {
+    [K in keyof Value as [Exclude<Value[K], false>] extends [never] ? never : K]: Exclude<Value[K], false>;
 };
-/** 框架在 ctx 上暴露的资源视图（`Awaited<>` 归一 + `false` 键剔除） */
-export type ResourcesView<R> = Live<Awaited<R>>;
+/**
+ * 框架在 ctx 上暴露的资源视图（`Awaited<>` 归一 + `false` 键剔除 + **单元解包**）。
+ *
+ * 解包是必须的：`ctx.resources.database` 必须是那个客户端本身，不能是
+ * `ResourceUnit<PrismaClient>` —— 否则每个消费方都要多写一层 `.value`，而单元外壳
+ * 是框架用来挂 `setup` 的实现细节。
+ */
+export type ResourcesView<Resources> = Live<{
+    [K in keyof Awaited<Resources>]: UnwrapResource<Awaited<Resources>[K]>;
+}>;
 /** 框架在 ctx 上暴露的客户端视图（口径同 `ResourcesView`） */
-export type ClientsView<CL> = Live<Awaited<CL>>;
+export type ClientsView<Clients> = Live<Awaited<Clients>>;
+/**
+ * 应用扩展后的 env 类型（固定 env + 应用声明的扩展字段）。
+ *
+ * `ConfigEnv` 是框架**固定约定**的最小集合（`ENV` / `API_PORT` / ...），不接受业务字段；
+ * 业务字段（如 `REDIS_KEY_PREFIX`、第三方 token）由应用声明：`Env` 是 `defineServer` 的**第一个
+ * 泛型**，可**手写** `defineServer<{ FOO?: string }>({...})`，也可从 `resources` / `config` 工厂的
+ * `ctx` 类型标注（`ResourcesContext<Env>` / `ConfigContext<Env>`）推导；两种方式都让扩展字段并进
+ * `ctx.env`、有类型地访问。（手写 `Env` 的代价见 `defineServer` 文档：其余泛型会退化为 `object`。）
+ *
+ * ⚠️ **只是类型声明，不影响加载**：env 的加载完全走框架内置逻辑（dotenv 分层 + 进程注入，
+ * 见 `env.ts`），框架**不提供自定义加载**。运行期扩展字段的值就是内置加载后的 `process.env[key]`
+ * （字符串直通，不映射 / 不校验 / 不给默认值——要默认值 / 归一化在 `resources` 里自己做）。
+ *
+ * 这样各仓不必再往 `ctx.env` 上开「`process.env.XXX` 无类型后门」——用泛型或 ctx 标注声明即可。
+ *
+ * ```ts
+ * // 命名工厂：参数标注扩展 env，`defineServer` 从中推导 Env（point-free 最简）
+ * function createResources(ctx: ResourcesContext<{ REDIS_KEY_PREFIX?: string }>) {
+ *   return { cache: createCache({ prefix: ctx.env.REDIS_KEY_PREFIX ?? 'account' }) }
+ * }
+ * const server = defineServer({ app, resources: createResources, config, services, middlewares, routers })
+ * ```
+ */
+export type AppEnv<Env> = ConfigEnv & Env;
 /**
  * 资源错误分类器（响应层用）。
  *
@@ -122,8 +251,8 @@ export type ErrorClassifier = (error: unknown) => SystemError | null;
  * }
  * ```
  */
-export interface ResourcesContext {
-    readonly env: ConfigEnv;
+export interface ResourcesContext<Env = object> {
+    readonly env: AppEnv<Env>;
     readonly log: LoggerLike;
     /**
      * 本阶段的释放器：**在创建资源的地方当场注册释放**。
@@ -140,7 +269,7 @@ export interface ResourcesContext {
      */
     registerClassifyError(classifier: ErrorClassifier): void;
 }
-export type ResourcesFactory<R> = (ctx: ResourcesContext) => R;
+export type ResourcesFactory<Resources, Env = object> = (ctx: ResourcesContext<Env>) => Resources;
 /**
  * `config(ctx)` 的入参：`env` + `log` + `disposer` + 资源视图。
  *
@@ -155,14 +284,14 @@ export type ResourcesFactory<R> = (ctx: ResourcesContext) => R;
  *
  * 返回值是**启动期快照**：进程内不再变，没有热更新通道。要能随时改的开关放数据库、请求期现读。
  */
-export interface ConfigContext<R> {
-    readonly env: ConfigEnv;
+export interface ConfigContext<Resources, Env = object> {
+    readonly env: AppEnv<Env>;
     readonly log: LoggerLike;
     /** 本阶段的释放器（关闭时在 services 之后、resources 之前 flush） */
     readonly disposer: Disposer;
-    readonly resources: ResourcesView<R>;
+    readonly resources: ResourcesView<Resources>;
 }
-export type ConfigFactory<R, C> = (ctx: ConfigContext<R>) => C;
+export type ConfigFactory<Resources, Config, Env = object> = (ctx: ConfigContext<Resources, Env>) => Config;
 /**
  * `clients(ctx)` 的入参：`log` + `disposer` + `resources` + `config`。
  *
@@ -183,16 +312,17 @@ export type ConfigFactory<R, C> = (ctx: ConfigContext<R>) => C;
  * }
  * ```
  *
- * 没有外部客户端时写 `clients: () => ({})`——槽位恒定，不留「可省略」分支。
+ * 没有外部客户端时**省略本槽位**（框架默认空客户端包）——独立成层只为「分层依赖」
+ * （排在 `config` 之后、`services` 之前），不要求「必须出现」。
  */
-export interface ClientsContext<R, C> {
+export interface ClientsContext<Resources, Config> {
     readonly log: LoggerLike;
     /** 本阶段的释放器（关闭时在 services 之后、config 之前 flush） */
     readonly disposer: Disposer;
-    readonly resources: ResourcesView<R>;
-    readonly config: Awaited<C>;
+    readonly resources: ResourcesView<Resources>;
+    readonly config: Awaited<Config>;
 }
-export type ClientsFactory<R, C, CL> = (ctx: ClientsContext<NoInfer<R>, NoInfer<C>>) => CL;
+export type ClientsFactory<Resources, Config, Clients> = (ctx: ClientsContext<NoInfer<Resources>, NoInfer<Config>>) => Clients;
 /**
  * `services(ctx)` 的入参：`log` + `disposer` + `resources` + `config` + `clients`。
  *
@@ -212,54 +342,73 @@ export type ClientsFactory<R, C, CL> = (ctx: ClientsContext<NoInfer<R>, NoInfer<
  * - **service 之间不得互依**：要共享的东西放 `clients`；需要常驻资源的单元自己实现
  *   `init()` / `dispose()`（框架会在 `middlewares` 之前 `init`、关闭时逆序 `dispose`）。
  */
-export interface ServiceContext<R, C, CL = unknown> {
+export interface ServiceContext<Resources, Config, Clients = unknown> {
     readonly log: LoggerLike;
     /** 本阶段的释放器（关闭时**先** flush 它，再逐单元逆序 `dispose`） */
     readonly disposer: Disposer;
-    readonly resources: ResourcesView<R>;
-    readonly config: Awaited<C>;
-    readonly clients: ClientsView<CL>;
+    readonly resources: ResourcesView<Resources>;
+    readonly config: Awaited<Config>;
+    readonly clients: ClientsView<Clients>;
 }
 /**
- * 一个已构造好的中间件：接收 app 的注册函数。
+ * 一个已构造好的中间件注册函数：接收 app，挂钩子 / 注册插件。
  *
  * 中间件**不参与生命周期**（要常驻资源就放 `services`）；注册后不再暴露内部钩子名。
  */
 export type Middleware = (app: AppInstance) => void | Promise<void>;
+/**
+ * 具名中间件单元：`register` + 一个仅用于日志 / 报错定位的 `name`。
+ *
+ * 标准中间件工厂（`createCorsMiddleware` / `createAuthMiddleware` / `createRateLimitMiddleware`）
+ * 直接返回带默认名字的单元，调用方把它们按顺序摆进数组即可，不必自己起名。
+ */
+export interface MiddlewareUnit {
+    /** 名字：仅用于注册期日志 / 报错定位，**不参与生命周期、不影响注册序**（顺序由数组位置决定） */
+    readonly name: string;
+    /** 注册函数 */
+    readonly register: Middleware;
+}
+/**
+ * `middlewares` 数组里的一项：**具名单元**或**裸注册函数**。
+ *
+ * 裸函数会被框架补一个占位名（`middleware[i]`，`i` 为数组下标）用于日志；要可读的日志名
+ * 就返回 `MiddlewareUnit`（标准工厂已经这么做了）。
+ */
+export type MiddlewareEntry = MiddlewareUnit | Middleware;
 /**
  * `middlewares(ctx)` 的入参：`app` + `log` + `disposer` + `services` + `config` + `clients`。
  *
  * ❗**故意没有 `resources` / `env`** —— 中间件要访问数据层必须穿过 service。
  *
  * ```ts
- * middlewares: (ctx) => ({
- *   cors: createCorsMiddleware(ctx),
- *   auth: createAuthMiddleware(ctx, { client: createAuthClient(ctx.services) }),
- *   rateLimit: createRateLimitMiddleware(ctx, { limit: ctx.config.rateLimit }),
- * })
+ * middlewares: (ctx) => [
+ *   createCorsMiddleware(ctx),
+ *   createAuthMiddleware(ctx, { client: createAuthClient(ctx.services) }),
+ *   createRateLimitMiddleware(ctx, { store: ctx.services.rateLimitStore }),
+ * ]
  * ```
- *
- * 返回对象是**键即名字、键序即注册序**（见下方 `MiddlewaresFactory` 的数字键陷阱）。
  */
-export interface MiddlewareContext<C, S, CL = unknown> {
+export interface MiddlewareContext<Config, Services, Clients = unknown> {
     readonly app: AppInstance;
     readonly log: LoggerLike;
     /** 本阶段的释放器（关闭时最早 flush：在 services / clients / config / resources 之前） */
     readonly disposer: Disposer;
-    readonly services: Awaited<S>;
-    readonly config: Awaited<C>;
-    readonly clients: ClientsView<CL>;
+    readonly services: Awaited<Services>;
+    readonly config: Awaited<Config>;
+    readonly clients: ClientsView<Clients>;
 }
 /**
- * `middlewares` 必须返回 `{ 名字: 注册函数 }` —— **键即 name、键序即注册序**。
+ * `middlewares` 返回一个**有序数组** —— **数组位置即注册序**，再无歧义。
  *
- * 键只用于报错定位 / 注册期日志，**不参与生命周期**。
+ * 为什么是数组而不是 `Record<string, Middleware>`：注册序是中间件的核心语义（cors 必须在
+ * auth 之前、auth 必须在限流之前），而对象键的枚举序由 JS 引擎决定（纯数字键还会被重排到
+ * 最前）——用「顺序由引擎决定、且有已知陷阱」的结构承载「必须严格有序」的东西本身自相矛盾。
+ * 数组把顺序交还给书写顺序，既直观又没有数字键坑。
  *
- * ⚠️ **坑**：JS 对象的枚举序是「整数样式的键在前（按数值升序），其余按插入序」。所以
- * **纯数字键会被引擎重排到最前**，注册序随之改变——键名避免纯数字（用 `auth` / `rateLimit`
- * 这类标识符即可）。除此外，注册序 = 对象键顺序。
+ * 每一项可以是标准工厂返回的具名单元（`MiddlewareUnit`），也可以是一个裸注册函数
+ * （`Middleware`，框架会补占位名用于日志）。
  */
-export type MiddlewaresFactory<C, S, CL = unknown> = (ctx: MiddlewareContext<C, S, CL>) => Record<string, Middleware>;
+export type MiddlewaresFactory<Config, Services, Clients = unknown> = (ctx: MiddlewareContext<Config, Services, Clients>) => MiddlewareEntry[];
 /**
  * `routers(ctx)` 的入参：`app` + `log` + `disposer` + `services` + `clients`。
  *
@@ -275,48 +424,62 @@ export type MiddlewaresFactory<C, S, CL = unknown> = (ctx: MiddlewareContext<C,
  * `generateOpenApi` 走这条路径时不构造 `services`，注册期就读它会让出 spec 直接失败。
  * 没业务路由也要写 `routers: () => {}`。
  */
-export interface RouterContext<S, CL = unknown> {
+export interface RouterContext<Services, Clients = unknown> {
     readonly app: AppInstance;
     readonly log: LoggerLike;
     /** 本阶段的释放器（关闭时**最先** flush） */
     readonly disposer: Disposer;
-    readonly services: Awaited<S>;
-    readonly clients: ClientsView<CL>;
+    readonly services: Awaited<Services>;
+    readonly clients: ClientsView<Clients>;
 }
-export type RoutersFactory<S, CL = unknown> = (ctx: RouterContext<S, CL>) => void | Promise<void>;
+export type RoutersFactory<Services, Clients = unknown> = (ctx: RouterContext<Services, Clients>) => void | Promise<void>;
 /**
  * `services` 返回值形状闸门：
  * - 原始类型值（`string` / `number` / `boolean`）**拒绝**（防把配置塞进 services）。
  */
-export type ServicesShape<S> = {
-    [K in keyof S]: S[K] extends string | number | boolean ? never : S[K];
+export type ServicesShape<Services> = {
+    [K in keyof Services]: Services[K] extends string | number | boolean ? never : Services[K];
 };
 /**
- * `defineServer()` 入参：一个身份块 + **六个**工厂槽位（键顺序=分层）。
+ * `defineServer()` 入参：一个身份块 + 工厂槽位（键顺序=分层）。
  *
  * ```
- * app → resources(env) → config(env+resources) → clients(resources+config)
+ * app → resources(env) → config(env+resources) → (clients?)(resources+config)
  *     → services(resources+config+clients) → middlewares(app+services+config+clients)
  *     → routers(app+services+clients)
  * ```
  *
- * `S` 上的两道闸门（`ServicesShape<S>`，N2 §2.5）写在 `services` 的返回类型上：
- * `S & ServicesShape<S>` —— 形状合法时恒等，非法时该值塌成 `never` → 编译失败。
+ * `clients` 槽位**可选**（省略即空客户端包、`Clients` 退化为空）。
+ *
+ * **应用扩展 env（`Env`）不是槽位**，而是 `defineServer` 的**第一个泛型**（本接口里排最后一位，
+ * 但 `defineServer` 把它提到首位以便单独手写）：手写 `defineServer<{ FOO?: string }>({...})`，或
+ * 不写、从 `resources` / `config` 的 `ctx` 类型标注推导。不声明即无扩展（`Env = object`）。
+ * 手写 `Env` 会让其余泛型退化为 `object`（TS 限制，详见 `defineServer`）。加载走内置逻辑。
+ *
+ * `Services` 上的两道闸门（`ServicesShape<Services>`，N2 §2.5）写在 `services` 的返回类型上：
+ * `Services & ServicesShape<Services>` —— 形状合法时恒等，非法时该值塌成 `never` → 编译失败。
  */
-export interface ServerConfig<R, C, CL, S> {
+export interface ServerConfig<Resources, Config, Clients = object, Services = object, Env = object> {
     app: AppIdentity;
-    resources: ResourcesFactory<R>;
-    config: ConfigFactory<NoInfer<R>, C>;
+    /**
+     * 资源工厂。`ctx` 类型可写 `ResourcesContext<Env>` 声明应用扩展 env —— `Env` 从这里推导、
+     * 并进 `ctx.env`（见 `AppEnv`）。不声明即 `Env = object`（无扩展）。
+     */
+    resources: ResourcesFactory<Resources, Env>;
+    config: ConfigFactory<NoInfer<Resources>, Config, Env>;
     /**
      * 外部服务客户端（**我们调用的、地址/凭证来自业务配置的外部服务**）。
      *
      * 存在的唯一理由是「`services` 之间禁止互依」与「客户端需要 `config`」这两条约束
      * 的交集：多个 service / middleware 必须共享同一份客户端，而它们之间没有共享通道。
-     * 没有这种需求就写 `() => ({})` —— 槽位恒定，不留「可省略」分支。
+     *
+     * **可选**：没有外部客户端就**省略**本槽位（框架默认 `() => ({})`，`Clients` 退化为空）——
+     * 不再要求写一行仪式性的 `clients: () => ({})`。独立成层的意义只在于「分层依赖」
+     * （客户端排在 `config` 之后、`services` 之前），不在于「必须出现」。
      */
-    clients: ClientsFactory<NoInfer<R>, NoInfer<C>, CL>;
-    services: (ctx: ServiceContext<NoInfer<R>, NoInfer<C>, NoInfer<CL>>) => S & ServicesShape<S>;
-    middlewares: MiddlewaresFactory<NoInfer<C>, NoInfer<S>, NoInfer<CL>>;
+    clients?: ClientsFactory<NoInfer<Resources>, NoInfer<Config>, Clients>;
+    services: (ctx: ServiceContext<NoInfer<Resources>, NoInfer<Config>, NoInfer<Clients>>) => Services & ServicesShape<Services>;
+    middlewares: MiddlewaresFactory<NoInfer<Config>, NoInfer<Services>, NoInfer<Clients>>;
     /**
      * 业务路由注册（**必填**）。
      *
@@ -325,14 +488,15 @@ export interface ServerConfig<R, C, CL, S> {
      * 本槽位只用于注册**业务**路由。没有业务路由的应用也必须显式传入（写 `() => {}`），
      * 以保持槽位结构恒定、无「可省略」分支。
      */
-    routers: RoutersFactory<NoInfer<S>, NoInfer<CL>>;
+    routers: RoutersFactory<NoInfer<Services>, NoInfer<Clients>>;
 }
 /** 品牌字段值（`Server` 的 `__brand`） */
 export declare const SERVER_BRAND = "taicode.server";
 /** 纯定义产物：同一份定义可同时喂给「启动」与「出 spec」 */
-export type Server<R, C, CL, S> = ServerConfig<R, C, CL, S> & {
+export type Server<Resources, Config, Clients = object, Services = object, Env = object> = ServerConfig<Resources, Config, Clients, Services, Env> & {
     readonly __brand: typeof SERVER_BRAND;
 };
 /** `generateOpenApi()` 的返回（OpenAPI 文档对象） */
 export type OpenApiDocument = Record<string, unknown>;
+export {};
 //# sourceMappingURL=types.d.ts.map

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

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

package/output/cors/index.d.ts

@@ -1,3 +1,3 @@
-import type { Middleware, MiddlewareContext } from '../core/types.js';
-export declare function createCorsMiddleware<C = unknown, S = unknown>(ctx: MiddlewareContext<C, S>): Middleware;
+import type { MiddlewareContext, MiddlewareUnit } from '../core/types.js';
+export declare function createCorsMiddleware<C = unknown, S = unknown>(ctx: MiddlewareContext<C, S>): MiddlewareUnit;
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../source/cors/index.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAA;AAkBrE,wBAAgB,oBAAoB,CAAC,CAAC,GAAG,OAAO,EAAE,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,iBAAiB,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,UAAU,CA0BvG"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../source/cors/index.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAc,iBAAiB,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAA;AAkBrF,wBAAgB,oBAAoB,CAAC,CAAC,GAAG,OAAO,EAAE,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,iBAAiB,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,cAAc,CA4B3G"}

package/output/cors/index.js

@@ -1,7 +1,7 @@
 import cors from '@fastify/cors';
 import { readConfigKey } from '../core/boot/context.js';
 export function createCorsMiddleware(ctx) {
-    return async (app) => {
+    const register = async (app) => {
         let warned = false;
         // 请求期现读：`cors` 配置变化立即生效；构造期不读
         const resolveOrigins = () => {
@@ -24,4 +24,5 @@ export function createCorsMiddleware(ctx) {
             credentials: true,
         });
     };
+    return { name: 'cors', register };
 }

package/output/rate-limit/index.d.ts

@@ -1,4 +1,4 @@
-import type { Middleware, MiddlewareContext } from '../core/types.js';
+import type { MiddlewareContext, MiddlewareUnit } from '../core/types.js';
 import type { RateLimitStore } from './types.js';
 /**
  * 标准中间件单元 `rateLimit`（可替换；**不在默认预设内**）。
@@ -14,7 +14,7 @@ export interface RateLimitMiddlewareOptions {
     /** 存储后端（缺省进程内 memory） */
     store?: RateLimitStore;
 }
-export declare function createRateLimitMiddleware<C = unknown, S = unknown>(_ctx: MiddlewareContext<C, S>, options?: RateLimitMiddlewareOptions): Middleware;
+export declare function createRateLimitMiddleware<C = unknown, S = unknown>(_ctx: MiddlewareContext<C, S>, options?: RateLimitMiddlewareOptions): MiddlewareUnit;
 export { RateLimiter, createRateLimitKey } from './limiter.js';
 export { MemoryRateLimitStore } from './memory-store.js';
 export { RedisRateLimitStore } from './redis-store.js';

package/output/rate-limit/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../source/rate-limit/index.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAA;AACrE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAGhD;;;;;;;;;GASG;AAEH,MAAM,WAAW,0BAA0B;IACzC,yBAAyB;IACzB,KAAK,CAAC,EAAE,cAAc,CAAA;CACvB;AAqBD,wBAAgB,yBAAyB,CAAC,CAAC,GAAG,OAAO,EAAE,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,iBAAiB,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,OAAO,GAAE,0BAA+B,GAAG,UAAU,CAkBvJ;AAGD,OAAO,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAA;AAC9D,OAAO,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAA;AACxD,OAAO,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAA;AACtD,YAAY,EAAE,0BAA0B,EAAE,MAAM,kBAAkB,CAAA;AAClE,YAAY,EAAE,eAAe,EAAE,aAAa,EAAE,kBAAkB,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../source/rate-limit/index.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAc,iBAAiB,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAA;AACrF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAGhD;;;;;;;;;GASG;AAEH,MAAM,WAAW,0BAA0B;IACzC,yBAAyB;IACzB,KAAK,CAAC,EAAE,cAAc,CAAA;CACvB;AAqBD,wBAAgB,yBAAyB,CAAC,CAAC,GAAG,OAAO,EAAE,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,iBAAiB,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,OAAO,GAAE,0BAA+B,GAAG,cAAc,CAoB3J;AAGD,OAAO,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAA;AAC9D,OAAO,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAA;AACxD,OAAO,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAA;AACtD,YAAY,EAAE,0BAA0B,EAAE,MAAM,kBAAkB,CAAA;AAClE,YAAY,EAAE,eAAe,EAAE,aAAa,EAAE,kBAAkB,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA"}

package/output/rate-limit/index.js

@@ -20,7 +20,7 @@ function buildKeys(request, keys) {
     });
 }
 export function createRateLimitMiddleware(_ctx, options = {}) {
-    return (app) => {
+    const register = (app) => {
         const limiter = new RateLimiter({ store: options.store ?? new MemoryRateLimitStore() });
         const prefix = `${readServerIdentity(app)?.service ?? ''}:`;
         app.addHook('preValidation', async (request) => {
@@ -35,6 +35,7 @@ export function createRateLimitMiddleware(_ctx, options = {}) {
             }
         });
     };
+    return { name: 'rateLimit', register };
 }
 // ── 限流实现（与中间件同一模块）─────────────────────────────────
 export { RateLimiter, createRateLimitKey } from './limiter.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@taicode/common-server",
-  "version": "4.0.0-beta.5",
+  "version": "4.0.0-beta.7",
   "author": "Alain",
   "license": "ISC",
   "description": "",
@@ -35,7 +35,7 @@
   "peerDependencies": {
     "fastify": "^5.5.0",
     "redis": "^5.11.0",
-    "@taicode/common-base": "^4.0.0-beta.5"
+    "@taicode/common-base": "^4.0.0-beta.7"
   },
   "devDependencies": {
     "@eslint/js": "^9.39.3",
@@ -49,7 +49,7 @@
     "redis": "^5.11.0",
     "typescript-eslint": "^8.56.1",
     "vitest": "^3.2.4",
-    "@taicode/common-base": "^4.0.0-beta.5"
+    "@taicode/common-base": "^4.0.0-beta.7"
   },
   "scripts": {
     "test": "vitest run",