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

package/output/core/entries.js

@@ -0,0 +1,242 @@
+import { initServiceUnits } from './boot/lifecycle.js';
+import { attachSignalHandlers } from './boot/signal.js';
+import { buildClients, buildConfig, buildResources, buildServices, createBootContext, createDocumentContext, installShutdownHook, registerCoreStep, registerDocumentCoreStep, registerDocumentRoutersStep, registerDocumentSystemRoutesStep, registerMiddlewares, registerRouters, registerSystemRoutesStep, resolveAppEnv, setupResources, } from './boot/steps.js';
+import { loadEnvironment, resolveConfigEnv, CLEANABLE_ENVS } from './env.js';
+import { SERVER_BRAND } from './types.js';
+import { discoverTestDataModules, loadTestData } from './test-support/testdata.js';
+/** 默认监听地址 */
+const DEFAULT_HOST = '0.0.0.0';
+function resolvePort(env) {
+    const parsed = Number(env.API_PORT);
+    // `0` 是合法值：交给内核分配空闲端口（测试与多实例本地调试都靠它，而不是靠「不监听」开关）
+    if (!Number.isInteger(parsed) || parsed < 0) {
+        throw new Error(`[server] API_PORT is required to listen (got "${env.API_PORT}")`);
+    }
+    return parsed;
+}
+/**
+ * `defineServer()`（N1 §1）——**纯定义**：产出一个 `Server` 对象，不建连、不起服务。
+ *
+ * 启动是另一个函数（`startServer`）的事——同一份定义可同时喂给「启动」与「出 spec」
+ * （`generateOpenApi`）。
+ *
+ * ## 怎么用
+ *
+ * 一个服务**只在 `source/server.ts` 里写一次**，然后在三个地方消费它：
+ *
+ * ```ts
+ * // source/server.ts
+ * export const server = defineServer({ app, resources, config, clients, services, middlewares, routers })
+ * ```
+ * ```ts
+ * await startServer(server)        // source/index.ts —— 启动
+ * await generateOpenApi(server)    // build/openapi-gen.ts —— 出 spec
+ * await createTestServer(server)   // *.test.ts —— 测试
+ * ```
+ *
+ * ## 两条容易踩的规矩
+ *
+ * - **本函数不读 env、不建连、不读库**。放在模块顶层是安全的：`import { server }` 不会有副作用。
+ *   （需要 env 的工具进程自己调 `loadRuntimeEnvironment()`。）
+ * - **`clients` 可省略**，其余槽位恒定：没有业务路由也要写 `routers: () => {}`。省略 `clients`
+ *   → 空客户端包。其余槽位不留「可省略」分支，省掉一个就会让「这份定义到底声明了什么」需要靠猜。
+ *
+ * ## 扩展 env（`Env`）：`Env` 是**第一个**泛型，类型声明，不影响加载
+ *
+ * `Env` 排在泛型首位，就是为了能**单独手写**：`defineServer<{ FOO?: string }>({ ... })` 把扩展字段
+ * 的类型并进 `ctx.env`（`resources` / `config` 的 `ctx.env` 上可读、有类型）。不写即 `Env = object`
+ * （无扩展，`ctx.env` 就是 `ConfigEnv`）。
+ *
+ * ⚠️ **TypeScript 限制（务必知道）**：只要**显式写了 `Env`**，其余四个泛型
+ * （`Resources` / `Config` / `Clients` / `Services`）就**不再从工厂推导、一律退化为 `object`**
+ * —— 这是 TS「类型参数全有或全无」的规则，不是本函数能绕过的。后果：`defineServer<MyEnv>({...})`
+ * 产出的 `server` 上，`services` 等类型会塌成 `object`，`testServer.services.xxx` 之类会丢类型。
+ *
+ * 因此两种写法各有适用：
+ * - **要完整推导**（典型业务服务，依赖 `ctx.services` / `testServer.services` 的类型）：**不写泛型**，
+ *   把扩展 env 的类型写在**工厂参数标注**上——`resources: (ctx: ResourcesContext<{ FOO?: string }>) => ...`
+ *   或 point-free 传入参数已标注的命名工厂。这样 `Env` 与其余泛型**一起被推导**，不丢类型。
+ * - **只在意 `Env`、不依赖其余被推导类型**（简单服务 / 测试）：直接 `defineServer<MyEnv>({...})`。
+ *
+ * ⚠️ **只声明类型，不参与加载**：env 的加载完全走框架内置逻辑（dotenv 分层 + 进程注入），框架
+ * **不提供自定义加载**；运行期扩展字段的值就是内置加载后的 `process.env[key]`（字符串直通）。
+ *
+ * ```ts
+ * // 写法一（推荐业务服务用）：不写泛型，Env 从工厂参数标注推导，其余泛型一起推导
+ * function createResources(ctx: ResourcesContext<{ REDIS_KEY_PREFIX?: string }>) { ... }
+ * export const server = defineServer({ app, resources: createResources, config, services, middlewares, routers })
+ *
+ * // 写法二：显式手写 Env（首位）——简单；但其余泛型退化为 object
+ * export const server = defineServer<{ REDIS_KEY_PREFIX?: string }>({ app, resources, config, services, middlewares, routers })
+ * ```
+ */
+export function defineServer(config) {
+    const server = {
+        ...config,
+        __brand: SERVER_BRAND,
+    };
+    return server;
+}
+/**
+ * `startServer()`——真正跑起来：构造资源、加载配置、建客户端、建服务、装中间件、注册路由、listen、装信号。
+ *
+ * 步序**就写在本函数里**，不抽到共享的「按模式分支」的装配器：
+ * ```
+ * env → resources → core → config → clients → services → services.init() → middlewares
+ *     → systemRoutes → routers → onClose → ready → testdata → listen/signal
+ * ```
+ *
+ * - 最早阶段**固定加载 env**（`.env.dev < .env < .env.local`；`ENV=test` 追加 `.env.test.local`）。
+ * - 返回**原生 `FastifyInstance`**：不包 `fastify-plugin`、不返回包装对象。
+ * - **一定 listen**：监听端口 + 装信号处理器是这个入口的定义，没有开关。不监听端口的是
+ *   `createTestServer()`（`inject`），那是另一个入口——两个入口各自固定自己的行为，
+ *   而不是同一个入口按环境变量 / 选项改行为。
+ * - 硬性要求 `Server`（品牌）产物：传裸 `ServerConfig` 是编译错误。
+ *
+ * ## `development` / `test` 下会自动装载 `testdata/`
+ *
+ * 真启动（本地 `pnpm dev`）在 `ready()` 之后、**listen 之前**装载 `<cwd>/testdata` 下的脚本并整体
+ * `load()`（见 `test-support/testdata.ts`）：端口一旦对外，数据必须已经在位。脚本拿到的是装配好的
+ * ctx（`env` + `resources` + `log`），所以它们写数据用的就是被测服务读数据的那份连接。
+ * `ENV` 不在 `CLEANABLE_ENVS` 里（即生产）时**整段跳过**——这是 `startServer` 的唯一一处环境
+ * 分支，且是安静的：生产不需要测试数据，也没有什么东西需要失败。
+ *
+ * `cleanup()` 在 `startServer` 路径上不会被调用：真启动要的就是「数据在」，不是「数据不在」。
+ *
+ * ## 怎么用
+ *
+ * ```ts
+ * // source/index.ts —— 整个进程的启动点，只做这一件事
+ * import { startServer } from '@taicode/common-server/app'
+ * import { server } from './server'
+ *
+ * const app = await startServer(server)
+ * ```
+ *
+ * 你**不需要**写：加载 `.env`、创建 Fastify、注册响应信封 / cookie / OpenAPI / 系统路由、
+ * 装关闭钩子、装 `SIGTERM` / `SIGINT`。这些都由本函数固定完成，顺序写在下面的步序里。
+ *
+ * 你**需要**知道的两件事：
+ * - 端口只读 env 的 `API_PORT`，**不回退 `PORT`**（`PORT` 属 nginx）。`API_PORT=0` 让内核
+ *   分配空闲端口，多实例本地调试靠它。
+ * - 失败时已构造的资源会被按固定顺序释放（关闭流程八步），不会漏掉连接池；错误原样抛给
+ *   调用方——所以端口占用会让 `startServer` 直接 reject，需要在入口处接住。
+ */
+export async function startServer(server) {
+    const env = resolveAppEnv(loadEnvironment());
+    const ctx = createBootContext(server, env);
+    const { resources, units: resourceUnits, classifyResourceError } = await buildResources(ctx);
+    await setupResources(ctx, resourceUnits);
+    await registerCoreStep(ctx, classifyResourceError);
+    await buildConfig(ctx, resources);
+    const clients = await buildClients(ctx, resources);
+    const services = await buildServices(ctx, resources, clients);
+    await initServiceUnits({ service: ctx.service, log: ctx.log, services: services });
+    await registerMiddlewares(ctx, services, clients);
+    registerSystemRoutesStep(ctx, services);
+    await registerRouters(ctx, services, clients);
+    installShutdownHook(ctx, services, resourceUnits);
+    // 信号处理器「随 listen 装、随 close 卸」。但 Fastify 一旦 listening 就拒绝 `addHook`，
+    // 所以 onClose 里的 detach 必须先挂上，处理器本身等 listen 成功后再装。
+    let detachSignalHandlers = () => { };
+    ctx.app.addHook('onClose', () => {
+        detachSignalHandlers();
+    });
+    await ctx.app.ready();
+    // 服务已经完全就绪（路由 / 中间件 / 关闭钩子都装好），现在把开发用样本数据写进去，然后才开门。
+    // 顺序是**装配 → 数据 → listen**：端口一旦对外，第一条请求就必须能看到完整数据；反过来
+    // （先 listen 再 load）会留下一段「端口在响应、数据还没就位」的窗口——本地前端 / 集成脚本
+    // 恰好在这时请求，就是偶发的 404 / 空列表。
+    //
+    // 失败直接冒泡给调用方：`testdata/` 的脚本是服务能正常提供数据的前提，它失败时**不该**把端口
+    // 占着等人发现。非可清理环境（生产）整段跳过——这是本入口唯一的环境分支。
+    if (CLEANABLE_ENVS.includes(env.ENV)) {
+        const units = await discoverTestDataModules();
+        if (units.length > 0) {
+            // testdata 跑在 `ready()` 之后：`config` / `clients` / `services` 都已就绪，一并注入。
+            // `app` **不注入**（拿到它就能 `inject()`，等于用业务链路造数据，见 `TestDataContext`）。
+            const testDataCtx = {
+                env,
+                resources,
+                config: ctx.configAccess.read(),
+                clients,
+                services,
+                log: ctx.log,
+            };
+            await loadTestData({ ctx: testDataCtx, units, service: ctx.service });
+        }
+    }
+    try {
+        await ctx.app.listen({ port: resolvePort(env), host: DEFAULT_HOST });
+    }
+    catch (error) {
+        // 端口占用 / 地址不可用：把已构造的资源按固定八步释放掉，再把错误抛给调用方
+        await ctx.app.close();
+        throw error;
+    }
+    detachSignalHandlers = attachSignalHandlers(ctx.app, ctx.log);
+    return ctx.app;
+}
+/**
+ * `generateOpenApi()`——只出 spec。
+ *
+ * **文档只由「路由声明 + zod → JSON Schema 变换」决定**，因此这里只跑那两件事：
+ * ```
+ * 最小 Fastify（无 logger / 无 requestId）
+ *   → schema 契约（zod compiler + 路由守卫）+ swagger
+ *   → 5 条系统路由 → routers
+ *   → ready → swagger() → close()
+ * ```
+ *
+ * **不构造 `resources` / `config` / `clients` / `services`**：它们存在的意义是「让服务跑起来」
+ * （连接池、配置、外部客户端、业务单元及其 `init()`），而构建期不跑服务。
+ *
+ * **文档来源只有两处**：`routers` 与系统路由。其他槽位结构上就拿不到 `app`
+ * （`resources` / `config` / `clients` / `services` 的 ctx 里**没有 `app`**），因此根本无法
+ * 注册路由；于是也不需要执行它们去「发现」什么——那本来就不可能发现出接口。
+ *
+ * 代价是一条必须遵守的契约：`routers` / 系统路由在**注册期不得读取 `services` / `clients`**
+ * （只能捕获进 handler、请求期使用）。这与既有规则 B 同属一类——构造期本来就不允许
+ * 查库 / 建连 / 发请求。
+ *
+ * **红线**：全程**不得要求配置有效** —— 不跑 `config` / `clients` 槽位、不要求 `DATABASE_URL` /
+ * `REDIS_URL` 有效；`ctx.config` / `ctx.clients` 读到即抛 `CONFIG_UNAVAILABLE`。
+ *
+ * **没有关闭流程**：`init()` 与建连都没发生，无物可 flush；`close()` 只为释放 Fastify
+ * 自身句柄。
+ *
+ * ## 怎么用
+ *
+ * ```ts
+ * // build/openapi-gen.ts
+ * import { writeFile } from 'node:fs/promises'
+ * import { generateOpenApi } from '@taicode/common-server/app'
+ * import { server } from '../source/server'
+ *
+ * const document = await generateOpenApi(server)
+ * await writeFile('openapi.json', JSON.stringify(document, null, 2))
+ * ```
+ *
+ * 这一段在**构建期**跑，因此必须能离线成功：不需要数据库、不需要 Redis、不需要任何 env。
+ * 如果你的 `routers` 里写了 `services.xxx`（而不是只把它捕获进 handler），这条路会抛
+ * `CONFIG_UNAVAILABLE`——那不是 bug，是在提醒「路由注册期不该依赖运行期产物」。
+ */
+export async function generateOpenApi(server) {
+    // 不加载 .env 文件、不读配置、不跑 `resources` / `config` 槽位（出 spec 不要求 env 有效，也不构造 resources / config）
+    const env = resolveConfigEnv();
+    const ctx = createDocumentContext(server, env);
+    try {
+        await registerDocumentCoreStep(ctx);
+        registerDocumentSystemRoutesStep(ctx);
+        await registerDocumentRoutersStep(ctx);
+        await ctx.app.ready();
+        const swagger = ctx.app.swagger;
+        if (typeof swagger !== 'function') {
+            throw new Error('[generateOpenApi] @fastify/swagger is not registered');
+        }
+        return swagger.call(ctx.app);
+    }
+    finally {
+        await ctx.app.close();
+    }
+}

package/output/core/entries.test.d.ts

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

package/output/core/entries.test.d.ts.map

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