@x-9lab/xlab 1.6.0 → 2.0.0

package/@types/cluster.d.ts

@@ -1,5 +1,17 @@
-/// <reference types="node" />
 import type { Server } from "http";
-/**尝试以 cluster 模式启动服务 */
-declare function start(): Server;
+import type Koa from "koa";
+/**
+ * 启动服务监听
+
+ * master 且配置了 workers 时 fork 集群, 否则当前进程直接 listen
+ * @param app Koa 实例
+ * @return    直接监听时返回 http.Server, master fork 模式下无返回
+ */
+declare function start(app: Koa): Server<typeof import("http").IncomingMessage, typeof import("http").ServerResponse>;
 export default start;
+/**
+ * 通知全部 worker 退出并等待其结束
+ * @param timeout 等待超时(毫秒), 超时后不再等待
+ */
+declare function shutdownWorkers(timeout?: number): Promise<void>;
+export { shutdownWorkers };

package/@types/components/common/index.d.ts

@@ -1,4 +1,3 @@
-/// <reference types="node" />
 import { sleep, labelReplace, fix0, numberFormat } from "@x-drive/utils";
 import fs from "fs";
 export { labelReplace, fix0, numberFormat, sleep };
@@ -83,7 +82,7 @@ export { toJsonp };
  * 查找到文件时的处理函数
  * @param tmpPath 文件地址
  */
-declare type WalkCallback = (tmpPath: string, item: string) => void;
+type WalkCallback = (tmpPath: string, item: string) => void;
 /**
  * 递归处理文件夹
  * @param  path      文件目录

package/@types/components/cron/index.d.ts

@@ -2,14 +2,14 @@ declare global {
     namespace XLab {
         /**定时任务配置对象 */
         interface IConfigCronItem {
-            /**定时任务执行间隔 */
+            /**定时任务执行间隔, 单位秒 */
             delay?: number;
             /**是否启用 */
             enable?: boolean;
         }
         interface IConfig {
             /**
-             * 定时任务配置
+             * 定时任务配置, 键名为任务文件名
              * @see `@components/cron`
             */
             crons?: {
@@ -25,7 +25,7 @@ interface ICronJob {
     (): void;
     /**定时任务 */
     default?: () => void;
-    /**获取定时任务间隔时间 */
+    /**获取定时任务间隔时间, 单位毫秒 */
     getDelay?: () => number;
     /**获取定时任务开启状态 */
     enable?: () => boolean;
@@ -42,5 +42,5 @@ export { on };
  * 停止一个或所有的计时器
  * @param  name 计时器名称
  */
-declare function kill(name: string): void;
+declare function kill(name?: string): void;
 export { kill };

package/@types/components/log/index.d.ts

@@ -1,4 +1,39 @@
-declare function Log(config: Record<string, any>): void;
+import log4js from "log4js";
+/**日志配置 */
+interface ILogConfig {
+    /**日志名称,文件日志的文件名 */
+    name?: string;
+    /**日志输出等级 */
+    level?: string;
+    /**文件日志存放目录 */
+    dir?: string;
+    /**是否输出文件日志 */
+    fileLog?: boolean;
+    /**自定义 layout 配置 */
+    layout?: Record<string, any>;
+}
+/**日志模块 */
+declare class Log {
+    /**当前实例配置 */
+    private config;
+    /**日志实例缓存 */
+    private loggers;
+    constructor(config?: ILogConfig);
+    /**
+     * 获取分类日志实例
+     * @param  cat 实例分类名称
+     * @return     日志实例对象
+     */
+    getLogger(cat: string): log4js.Logger;
+}
 export { Log };
-declare const globalLog: any;
+/**框架全局日志实例 */
+declare const globalLog: Log;
 export { globalLog };
+/**
+ * 获取分类日志实例
+ * @param  cat 实例分类名称
+ * @return     日志实例对象
+ */
+declare function getLogger(cat: string): log4js.Logger;
+export { getLogger };

package/@types/config/index.d.ts

@@ -1,15 +1,19 @@
 /**
- * 通用日志方法
+ * 通用日志方法, 只在 master 进程上输出
  * @param  cat  业务类型
  * @param  type 日志等级
  */
-declare function commonLog(cat: string, type: string, ...rest: any[]): void;
+declare function commonLog(cat?: string, type?: string, ...rest: any[]): void;
 export { commonLog as log };
 /**
- * 默认配置
+ * 装载系统配置
+
+ * 解析命令行参数与环境, 按「内置默认 -> 业务生产配置 -> 环境配置 -> 本地配置 -> 命令行参数」
+ * 顺序合并配置, 重复调用直接返回已装载的配置
  */
-declare const CONFIG: XLab.IConfig;
-export default CONFIG;
+declare function loadConfig(): XLab.IConfig;
+export default loadConfig;
+/**获取系统配置对象 */
 declare function get(): XLab.IConfig;
 export { get };
 /**更新配置 */

package/@types/custom.d.ts

@@ -1,3 +1,25 @@
-/**处理自定义业务 */
-declare function processCustom(): Promise<void>;
-export default processCustom;
+/**自定义模块生命周期钩子 */
+interface ICustomHooks {
+    /**服务装配前执行, 接收 custom 配置中声明的参数 */
+    setup?: (conf?: XLab.CompositeValue) => void | Promise<void>;
+    /**服务启动完成(listen 成功)后执行 */
+    ready?: () => void | Promise<void>;
+    /**服务退出前执行 */
+    shutdown?: () => void | Promise<void>;
+}
+export type { ICustomHooks };
+/**
+ * 装载自定义业务模块并执行 setup 阶段
+
+ * 模块支持两种导出形态:
+ * 1. 导出函数, 视为 setup 钩子
+ * 2. 导出 `{ setup?, ready?, shutdown? }` 钩子对象
+ */
+declare function loadCustom(): Promise<void>;
+export { loadCustom };
+/**执行全部 ready 钩子 */
+declare function runReady(): Promise<void>;
+export { runReady };
+/**执行全部 shutdown 钩子 */
+declare function runShutdown(): Promise<void>;
+export { runShutdown };

package/@types/dot-file.d.ts

@@ -1,3 +1,9 @@
+/**
+ * 获取 `.xlab` 系列文件定义的环境数据
+ * @return 环境数据对象
+ */
+declare function getXlabEnv(): Record<string, XLab.JsonValue>;
+export { getXlabEnv };
 /**处理根目录下可能存在的配置文件 */
 declare function processDotFile(env: string, logger: any): void;
 export { processDotFile };

package/@types/global.d.ts

@@ -1,53 +1,5 @@
 import type { InternalComponents } from "./components";
-import type Koa from "koa";
 declare global {
-    /**全局日志对象 */
-    var log: any;
-    /**只在 master 上输出的日志 */
-    var masterLog: any;
-    /**
-    * 获取应用实例对象
-    */
-    function getApp(): Koa;
-    /**
-    * 获取内置组件
-    * @param  name 模块名
-    * @return      模块对象
-    */
-    function requireMod<T extends InternalComponents[K], K extends keyof InternalComponents>(name: K): T;
-    /**
-    * 全局获取 model 的方法
-    * @param  name model 名称
-    * @return      model 模块
-    */
-    function requireModel<T extends XLab.IModels[K], K extends keyof XLab.IModels>(name: K): T;
-    /**
-    * 全局获取 service 的方法
-    * @param  name service 名称
-    * @return      service 模块
-    */
-    function requireService<T extends XLab.IServices[K], K extends keyof XLab.IServices>(name: K): T;
-    /**
-     * 获取系统配置
-     */
-    function getSysConfig(): XLab.IConfig;
-    /**
-     * 获取系统配置
-     * @param  key 配置项
-     */
-    function getSysConfig<T extends XLab.IConfig[K], K extends keyof XLab.IConfig>(key?: K): T;
-    /**
-     * 获取系统配置
-     * @param  key 配置项
-     */
-    function getSysConfig(key?: any): any;
-    /**
-    * 更新系统配置
-    * @param  conf 配置项
-    */
-    function setSysConfig(conf: XLab.IConfig): void;
-    /**全局注入挂在对象 */
-    var XLAB: Record<string, XLab.JsonValue>;
     namespace XLab {
         /**JSON 基本数据类型 */
         type JsonValue = boolean | string | number | null | undefined | JsonArray | JsonObject;
@@ -94,6 +46,8 @@ declare global {
         interface IConfig {
             /**服务(应用)名称 */
             name?: string;
+            /**服务标识, 默认取 name */
+            mark?: string;
             /**版本 */
             version?: string;
             /**环境标识 */
@@ -120,15 +74,10 @@ declare global {
             enableCron?: boolean;
             /**是否允许 worker 上也执行定时任务 */
             enableWorkerCron?: boolean;
-            /**
-             * 开启的中间件列表
-             * @deprecated since version 1.1.0, 已弃用, 请使用改用 `middlewares` 配置项
-             */
-            middleware?: (string | (string | Record<string, any>)[])[];
             /**开启的中间件列表 */
             middlewares?: Record<string, boolean | MiddlewareConfig>;
             /**自定模块配置 */
-            custom?: string[];
+            custom?: (string | [string, CompositeValue])[];
             /**是否启用严格 ssl */
             strictSSL?: boolean;
             /**页端注入的 api 设置 */
@@ -163,6 +112,8 @@ declare global {
             cron?: {
                 def?: number;
             };
+            /**优雅退出时等待在途请求/worker 结束的超时时间(毫秒), 默认 10000 */
+            shutdownTimeout?: number;
             /**注入参数列表 */
             injection?: string[];
             /**首页缓存时间 */
@@ -218,3 +169,42 @@ declare global {
         }
     }
 }
+/**
+ * 获取内置组件
+ * @param  name 模块名
+ * @return      模块对象
+ */
+declare function requireMod<T extends InternalComponents[K], K extends keyof InternalComponents>(name: K): T;
+export { requireMod };
+/**
+ * 获取业务 model (business/@models)
+ * @param  name model 名称
+ * @return      model 模块
+ */
+declare function requireModel<T extends XLab.IModels[K], K extends keyof XLab.IModels>(name: K): T;
+declare function requireModel(name: string): any;
+export { requireModel };
+/**
+ * 获取业务 service (business/@services)
+ * @param  name service 名称
+ * @return      service 模块
+ */
+declare function requireService<T extends XLab.IServices[K], K extends keyof XLab.IServices>(name: K): T;
+declare function requireService(name: string): any;
+export { requireService };
+/**
+ * 获取全部系统配置
+ */
+declare function getSysConfig(): XLab.IConfig;
+/**
+ * 获取系统配置
+ * @param  key 配置项
+ */
+declare function getSysConfig<T extends XLab.IConfig[K], K extends keyof XLab.IConfig>(key?: K): T;
+export { getSysConfig };
+/**
+ * 更新系统配置
+ * @param  conf 配置项
+ */
+declare function setSysConfig(conf: XLab.IConfig): void;
+export { setSysConfig };

package/@types/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * `@x-9lab/xlab` 包入口
+ *
+ * v2 起框架 API 由此显式导出, 不再挂载到 global。
+ * 业务代码使用 `require("@x-9lab/xlab")` / `import ... from "@x-9lab/xlab"` 获取。
+ */
+export { app, getApp, boot, shutdown, exit } from "./server";
+export { requireMod, requireModel, requireService, getSysConfig, setSysConfig } from "./global";
+export { Log, globalLog, getLogger } from "./components/log";
+export { log as masterLog } from "./config";
+export { getXlabEnv } from "./dot-file";
+export { defineApi } from "./router";
+export type { IApiDefinition } from "./router";
+export type { ICustomHooks } from "./custom";
+export type { ICronJob } from "./components/cron";
+export type { InternalComponents } from "./components";
+import app from "./server";
+export default app;

package/@types/init-env.d.ts

@@ -1 +1,3 @@
-export {};
+/**执行业务的 @env 环境预处理模块 */
+declare function initEnv(): void;
+export default initEnv;

package/@types/middleware/handle-pre-dir.d.ts

@@ -1,6 +1,2 @@
 import type Koa from "koa";
-/**
- * 处理代理过来多余的地址层级
- */
-declare function handlPreDir(ctx: Koa.Context, next: Koa.Next): Promise<void>;
-export default handlPreDir;
+export default function (): (ctx: Koa.Context, next: Koa.Next) => Promise<void>;

package/@types/middleware/request-filter.d.ts

@@ -1,4 +1,3 @@
-/// <reference types="node" />
 import type Koa from "koa";
 import url from "url";
 /**资源类型 */

package/@types/middleware/service-mark.d.ts

@@ -1,7 +1,2 @@
 import type Koa from "koa";
-/**
- * 处理函数
- */
-declare function handler(ctx: Koa.Context, next: Koa.Next): Promise<void>;
-export default function (): typeof handler;
-export {};
+export default function (): (ctx: Koa.Context, next: Koa.Next) => Promise<void>;

package/@types/router.d.ts

@@ -1,4 +1,29 @@
 import type Router from "koa-router";
+/**支持的请求方法, 同时也是「文件名即方法」约定支持的文件名 */
+declare const HTTP_METHODS: readonly ["get", "post", "put", "delete", "patch", "head", "options", "all"];
+/**支持的请求方法 */
+type HttpMethod = typeof HTTP_METHODS[number];
+/**路由定义对象 */
+interface IApiDefinition {
+    /**API 请求方法, 不指定时由文件名约定或默认 get 决定 */
+    method?: HttpMethod;
+    /**业务 api 地址, 不指定时由文件路径生成 */
+    api?: string;
+    /**接口中间件 */
+    middleware?: Router.IMiddleware[];
+    /**业务处理函数 */
+    handler: Router.IMiddleware;
+    /**是否忽略 API 名称检测(不强制 /api 前缀) */
+    ignoreApiNameCheck?: boolean;
+}
+export type { IApiDefinition };
+/**
+ * 定义一个业务接口
+
+ * 运行时恒等返回, 仅为路由模块提供类型推导
+ */
+declare function defineApi(def: IApiDefinition): IApiDefinition;
+export { defineApi };
 /**加载业务服务接口 */
 declare function appRouter(router: Router): void;
 export default appRouter;

package/@types/server.d.ts

@@ -1,12 +1,34 @@
-import "./global";
-import "./init-env";
 import koa from "koa";
+/**服务实例 */
 declare const app: koa<koa.DefaultState, koa.DefaultContext>;
 export { app };
-/**启动服务 */
-declare function boot(): void;
-export { boot };
-/**退出服务 */
+/**
+ * 获取应用实例对象
+ * @return 实例对象
+ */
+declare function getApp(): koa<koa.DefaultState, koa.DefaultContext>;
+export { getApp };
+/**
+ * 退出服务
+
+ * 停止定时任务 -> 通知 worker 退出(master) -> 等待在途请求 -> 执行 shutdown 钩子 -> 退出进程
+ * @param code 进程退出码
+ */
+declare function shutdown(code?: number): Promise<void>;
+export { shutdown };
+/**
+ * 退出服务
+ * @deprecated 请使用 shutdown
+ */
 declare function exit(): void;
 export { exit };
+/**
+ * 启动服务
+
+ * 按固定顺序执行启动阶段:
+ * initEnv -> loadConfig -> dotFile -> custom(setup) -> middleware
+ * -> router -> static/badRequest -> cron -> listen -> custom(ready)
+ */
+declare function boot(): Promise<void>;
+export { boot };
 export default app;

package/MIGRATION.md

@@ -0,0 +1,170 @@
+v1 → v2 升级指南
+========
+
+v2 是一次 breaking 升级,核心变化:**框架 API 不再挂载到 global,改为从包显式导入**;新增显式生命周期与优雅退出;路由定义形态收敛。本文按步骤指引业务完成迁移,预计单个业务的迁移工作量在半天以内。
+
+## 前置要求
+
+- Node.js **>= 20**(koa 3 要求 >= 18,Node 18 已 EOL)
+- 部署脚本/容器基础镜像同步检查 Node 版本
+
+## 升级步骤
+
+### 1. 升级依赖
+
+```bash
+yarn add @x-9lab/xlab@^2.0.0
+```
+
+启动方式不变:`package.json` 里仍然是 `"start-dev": "xlab"`,`xlab.config.js`、`.xlab` 系列文件、`@server` 目录约定均不变。
+
+### 2. 全局 API 改为导入(必做)
+
+v1 挂在 global 上的所有 API 均已移除,对照表:
+
+| v1(global) | v2(从 `@x-9lab/xlab` 导入) |
+|---|---|
+| `log.getLogger(cat)` | `getLogger(cat)` |
+| `masterLog(cat, type?, ...msg)` | `masterLog(cat, type?, ...msg)` |
+| `getSysConfig(key?)` | `getSysConfig(key?)` |
+| `setSysConfig(conf)` | `setSysConfig(conf)` |
+| `requireMod(name)` | `requireMod(name)` |
+| `requireModel(name)` | `requireModel(name)` |
+| `requireService(name)` | `requireService(name)` |
+| `getApp()` | `getApp()` |
+| `XLAB`(`.xlab` 数据) | `getXlabEnv()` |
+
+除 `log` 与 `XLAB` 外名称均不变,迁移就是在文件头部加一行导入:
+
+```js
+// v1
+const { ErrorTypes } = requireMod("return-code");
+
+// v2
+const { requireMod } = require("@x-9lab/xlab");
+const { ErrorTypes } = requireMod("return-code");
+```
+
+```js
+// v1
+const secret = XLAB.MY_SECRET;
+log.getLogger("biz").info("hi");
+
+// v2
+const { getXlabEnv, getLogger } = require("@x-9lab/xlab");
+const secret = getXlabEnv().MY_SECRET;
+getLogger("biz").info("hi");
+```
+
+可以用下面的命令快速找出需要迁移的文件:
+
+```bash
+grep -rln "requireMod\|requireModel\|requireService\|getSysConfig\|setSysConfig\|masterLog\|getApp\|XLAB\|log\.getLogger" @server/
+```
+
+**类型支持不变**:`XLab` 命名空间仍是全局类型,`XLab.IModels` / `XLab.IServices` / `XLab.IConfig` 的 declaration merging 扩展方式与 v1 完全一致,业务的 `.d.ts` 无需修改。纯 JS 项目在 JSDoc 中使用 `XLab.IConfig` 等类型时,若编辑器提示找不到命名空间,在任一被 tsconfig/jsconfig 覆盖的文件中加一行 `/// <reference types="@x-9lab/xlab" />` 即可。
+
+**注意**:业务代码里 `require("@x-9lab/xlab")` 拿到的必须与运行中的服务是同一个包实例(正常通过依赖安装即满足;不要全局安装一份再混用)。
+
+### 3. 数组形式的路由改写(必做,如有)
+
+数组导出(文件名当方法名)已移除,启动时命中会直接报错。改写方式二选一:
+
+```js
+// v1: @server/business/user/post.js —— 数组形式
+module.exports = [checkAuth, function (ctx) { /* ... */ }];
+```
+
+方式一,「文件名即方法」约定(v2 新增):文件名是 `get/post/put/delete/patch/head/options/all` 之一时,自动作为请求方法且不进入 api 路径。无中间件的场景直接导出函数即可:
+
+```js
+// v2: @server/business/user/post.js -> POST /api/user
+module.exports = function (ctx) { /* ... */ };
+```
+
+方式二,对象形式(推荐,配合 `defineApi` 获得类型推导):
+
+```js
+// v2: @server/business/user/post.js -> POST /api/user
+const { defineApi } = require("@x-9lab/xlab");
+module.exports = defineApi({
+    "middleware": [checkAuth]
+    , handler(ctx) { /* ... */ }
+});
+```
+
+函数与对象两种导出形态的行为与 v1 一致,无需改动。
+
+### 4. custom 模块与生命周期钩子(可选)
+
+v1 的「导出一个函数」形态仍然兼容(视为 `setup`)。v2 起可以导出钩子对象:
+
+```js
+// @server/custom/db.js
+module.exports = {
+    async setup(conf) { /* 服务装配前, 收到 config.custom 里声明的参数 */ }
+    , async ready() { /* listen 成功后 */ }
+    , async shutdown() { /* 进程退出前, 用于释放连接等 */ }
+};
+```
+
+### 5. 检查行为变化(必读)
+
+以下变化不需要改代码,但需要确认对业务无影响:
+
+1. **优雅退出**:收到 SIGTERM/SIGINT 后,服务会停止定时任务 → 等待在途请求(默认 10s,可用配置项 `shutdownTimeout` 调整,单位毫秒)→ 执行 `shutdown` 钩子 → 退出。**部署侧注意**:k8s 的 `terminationGracePeriodSeconds`、pm2 的 `kill_timeout` 需要大于 `shutdownTimeout`,否则会被强杀。
+2. **worker 崩溃重启退避**:cluster 模式下 worker 10 秒内连续快速崩溃 5 次后不再自动拉起(v1 无条件立即重启,会造成 crash-loop)。依赖「无限重启」兜底的业务需要检查告警。
+3. **business 根级 `$` 中间件开始生效**:v1 因 bug 从不生效,v2 按文档约定对全部业务路由生效。如果 business 根下有 `$` 目录,确认其中间件对所有接口执行是否符合预期。
+4. **`crons` 按任务配置开始生效**:配置项 `crons: { 任务文件名: { delay, enable } }` v1 只有类型声明没有实现,v2 起真实生效,优先级高于任务模块自身的 `getDelay()` / `enable()`。注意 `delay` 单位是**秒**(与 `cron.def` 一致),模块 `getDelay()` 返回值仍是毫秒。
+5. **`middleware` 数组配置移除**:v1.1.0 起已弃用且实际不被读取,配置里如仍保留该字段可直接删除,只认 `middlewares`。
+6. **`custom` 的执行时机**:v1 对 async 自定义模块不等待;v2 会 await 完 `setup` 才继续装配中间件与路由,时序更明确。
+7. **方法名文件的 api 路径会变化(重要)**:v1 中名为 `get.js` / `post.js` 等的函数或对象形态路由文件,文件名会进入 api 路径(如 `business/foo/post.js` → `POST /api/foo/post`);v2 按「文件名即方法」约定,文件名不再进入路径(→ `POST /api/foo`)。**这是路由地址的静默变更**,升级前用下面命令找出此类文件,逐个确认调用方,必要时用 `defineApi` 的 `api` 字段固定回原地址:
+
+    ```bash
+    find @server/business -type f \( -name "get.js" -o -name "post.js" -o -name "put.js" -o -name "delete.js" -o -name "patch.js" -o -name "head.js" -o -name "options.js" -o -name "all.js" \)
+    ```
+
+8. **其余路由生成规则不变**:`index` 文件名去除、`@` 目录不参与路由、`:name` 路径参数等均与 v1 一致。
+
+### 6. 验证
+
+```bash
+# 开发环境跑起来,观察启动日志中的 API 注册与中间件加载是否与 v1 一致
+yarn start-dev
+
+# 逐条核对启动日志里的 "Handling API >>>" 输出与线上路由清单
+```
+
+## 完整 API 一览(v2)
+
+```ts
+import {
+    boot, shutdown          // 生命周期
+    , app, getApp           // Koa 应用实例
+    , getSysConfig, setSysConfig
+    , requireMod, requireModel, requireService
+    , getLogger, masterLog, Log, globalLog
+    , getXlabEnv            // .xlab 环境数据
+    , defineApi             // 路由定义帮助函数
+} from "@x-9lab/xlab";
+```
+
+## 常见问题
+
+**Q: 迁移时想先跑起来再逐步改,有没有临时兼容方案?**
+可以在业务自己的 `@server/@env/index.js`(启动最早执行)里临时把 API 挂回 global,迁移完成后删除:
+
+```js
+const xlab = require("@x-9lab/xlab");
+["requireMod", "requireModel", "requireService", "getSysConfig", "setSysConfig", "getApp"]
+    .forEach(name => { global[name] = xlab[name]; });
+global.masterLog = xlab.masterLog;
+global.log = xlab.globalLog;
+global.XLAB = xlab.getXlabEnv();
+```
+
+**Q: `getApp()` 还能用吗?**
+能,且不再是弃用状态;也可以直接 `const { app } = require("@x-9lab/xlab")`。
+
+**Q: 日志格式变了吗?**
+日志库从 log4js 1.x 升级到 6.x,框架通过默认 layout 保持了 v1 的输出格式(时间戳仍为 `yyyy-MM-dd hh:mm:ss.SSS` 空格分隔),日志采集无需调整;`new Log({ layout })` 自定义 layout 的行为不变。