koa-ts-core 0.1.0 → 0.2.0

package/README.md

@@ -2,11 +2,14 @@
 
 基于 **TypeScript + [Koa3](https://koajs.com/)** 的轻量服务端核心库，提供：
 
-- 约定式路由（装饰器）
-- 权限与参数校验约定
+- 约定式路由（装饰器，基于 `@koa/router`）
+- 权限与参数校验约定（控制器 + 校验器目录约定）
 - 全局错误处理与统一响应体
-- 环境变量加载
-- 日志（log4js）集成
+- 环境变量加载（多环境合并）
+- 日志集成（log4，基于 log4js）
+- AsyncLocalStorage 请求上下文获取
+- 阶段式中间件管线与扩展（Phase Middleware）
+- TrackId（RequestId）生成与透传
 - 接口文档生成基础能力（配合 `koa-ts-cli` 使用）
 
 > 推荐配合脚手架工具 [koa-ts-cli](https://www.npmjs.com/package/koa-typescript-cli) 使用。
@@ -19,52 +22,98 @@
 npm i koa-ts-core
 # 或
 yarn add koa-ts-core
+# 或
+pnpm add koa-ts-core
 ```
 
 ---
 
-## 快速开始
+## 快速开始（推荐新 API）
 
-### 初始化应用
+### 初始化应用（`createKoaApp`）
 
 在项目入口文件（如 `src/main.ts`）中：
 
 ```ts
 import Koa from "koa";
 import cors from "koa2-cors";
-import { initializeKoaApp, TLog4 } from "koa-ts-core";
+import { createKoaApp } from "koa-ts-core";
 
 async function bootstrap() {
-  const [app] = await initializeKoaApp({
-    // 鉴权逻辑（配合 @AuthRouter 使用）
-    authCheckCallback: async (ctx) => {
-      // TODO: 你的权限判断
-      return true;
+  const [app] = await createKoaApp({
+    // 自定义 koa 实例（可选，不传则内部创建）
+    koaInstance: new Koa(),
+
+    // 鉴权配置（配合 @AuthRouter 使用）
+    auth: {
+      handler: async (ctx) => {
+        // TODO: 你的权限判断逻辑
+        // return true / false 或直接抛异常
+      },
     },
 
-    // CORS 中间件
-    corsMiddleware: cors(),
-
-    // 高优先级中间件（在内置中间件之前执行）
-    registerHighPriorityMiddleware: (app: Koa) => {
-      // app.use(yourMiddleware);
+    // 错误处理配置
+    error: {
+      // 自定义错误处理函数
+      handler: (error, ctx) => {
+        console.error("Global error:", error);
+        // 这里可以做统一日志、告警上报等
+      },
+      // 是否在响应中暴露堆栈（默认：非生产环境为 true，生产为 false）
+      // exposeStack: process.env.NODE_ENV !== "production",
     },
 
-    // 全局错误回调
-    catchErrorCallback: (error, ctx) => {
-      console.error("Global error:", error);
+    // 日志配置
+    log: {
+      // log4：基础日志能力（log4js）
+      // false 或不传：不启用 log4
+      // true: 使用默认 log4 配置
+      // 函数：自定义 log4 配置
+      log4: true,
+
+      // 是否开启每次请求的运行时日志
+      runtimeLog: true,
     },
 
-    // 请求生命周期 hook：request / response / error
-    registerHook: (ctx, type) => {
-      // your tracing / metrics logic
+    // Hook 配置：请求生命周期 request / response / error
+    hooks: {
+      register: (ctx, type) => {
+        // your tracing / metrics logic
+        // type: "request" | "response" | "error"
+      },
     },
 
-    // 日志：true 为默认配置，函数为自定义配置
-    log4: true as TLog4,
+    // CORS 中间件（例如 koa2-cors）
+    koa2Cors: cors(),
+
+    // TrackId（RequestId）配置
+    trackId: {
+      /**
+       * 生成 trackId 的函数：
+       * - 默认：优先从 header `x-request-id` 透传；没有就生成 uuid.v4()
+       * - 传入 false：禁用 trackId，不生成、不透传
+       */
+      // generator: false,
 
-    // 是否开启运行时日志
-    runtimeLog: true,
+      // 是否写回响应头（默认 true）
+      exposeHeader: true,
+
+      // header 名称（默认 "x-request-id"）
+      headerName: "x-request-id",
+    },
+
+    /**
+     * 阶段式中间件扩展
+     * 你可以在 AsyncContext / ErrorHandling / Logging / Security / BodyParsing / Auth / Routing
+     * 每一个阶段前/后插入自定义中间件
+     */
+    // phaseMiddlewares: {
+    //   [MiddlewarePhase.Logging]: {
+    //     before: [traceMiddleware],
+    //     use: [metricsMiddleware],
+    //     after: [yourCustomMiddleware],
+    //   },
+    // },
   });
 
   app.listen(process.env.APP_PORT ?? 3000, () => {
@@ -79,59 +128,203 @@ bootstrap();
 
 ---
 
-## 初始化配置说明
+## 初始化配置说明（`CreateKoaOptions`）
+
+`createKoaApp(options?: Partial<CreateKoaOptions>)` 支持以下配置块：
 
-`initializeKoaApp(options?: TInitOptions)` 支持以下字段：
+### 基础
 
 - **koaInstance?: Koa**  
-  自定义 Koa 实例，不传则自动创建。
+  自定义 Koa 实例，不传则内部 `new Koa()`。
+
+- **koa2Cors?: Koa.Middleware**  
+  CORS 中间件，一般为 `koa2-cors()`。
+
+- **phaseMiddlewares?: PhaseMiddlewareMap**  
+  阶段式中间件扩展，按阶段插入自定义中间件，详见「中间件链路与阶段扩展」。
+
+---
+
+### 鉴权配置：`auth?: AuthConfig`
+
+```ts
+interface AuthConfig {
+  handler?: (ctx: Koa.Context) => Promise<boolean> | boolean;
+}
+```
+
+- **handler**  
+  鉴权回调，配合 `@AuthRouter` 使用。  
+  你可以在这里检查登录态、角色、权限，抛错或返回布尔值。
 
-- **corsMiddleware?: Koa.Middleware**  
-  CORS 中间件。
+---
 
-- **authCheckCallback?: (ctx: Koa.Context) => boolean | Promise<boolean>**  
-  鉴权回调，配合 `@AuthRouter` 使用。
+### 错误处理配置：`error?: ErrorConfig`
 
-- **catchErrorCallback?: (error: Error, ctx?: Koa.Context) => void**  
-  全局错误回调，用于统一处理未捕获错误。
+```ts
+interface ErrorConfig {
+  handler?: (error: unknown, ctx: Koa.Context) => void | Promise<void>;
+  exposeStack?: boolean; // 默认：非生产环境 true，生产 false
+}
+```
 
-- **registerHighPriorityMiddleware?: (app: Koa) => void**  
-  高优先级中间件注册函数，在框架内置中间件之前执行。
+- **handler**  
+  自定义错误回调，用于统一处理未捕获错误（日志、告警等）。
 
-- **registerHook?: (ctx: Koa.Context, type: "request" | "response" | "error") => void**  
-  请求生命周期 hook。
+- **exposeStack**  
+  是否在响应中暴露错误堆栈信息，一般开发环境开启，生产关闭。
 
-- **log4?: TLog4**  
-  是否挂载 log4js 及配置方式：
+---
+
+### 日志配置：`log?: LogConfig`
+
+```ts
+type TLog4 =
+  | boolean
+  | ((instance: import("log4js").Log4js) => import("log4js").Log4js);
+
+interface LogConfig {
+  log4?: TLog4;
+  runtimeLog?: boolean;
+}
+```
+
+- **log4**
 
   - `false` / 不传：不启用 log4
   - `true`：使用默认 log4js 配置
-  - `(instance: Log4js) => Log4js`：自定义配置
+  - `(instance) => instance`: 自定义配置 log4js 实例
 
-- **runtimeLog?: boolean**  
-  是否挂载运行时日志能力到 `ctx.runtimeLog`。
+- **runtimeLog**  
+  是否开启每次请求的运行时日志（挂载到 `ctx.runtimeLog`，配合内置 `loggerMiddleware` 使用）。
 
 ---
 
-## 获取当前请求上下文
+### Hook 配置：`hooks?: HookConfig`
+
+```ts
+type HookType = "request" | "response" | "error";
+
+interface HookConfig {
+  register?: (ctx: Koa.Context, type: HookType) => void;
+}
+```
 
-框架通过 `AsyncLocalStorage` 在异步链路中保存 Koa 的 `Context`，从而在**无需显式传递 `ctx` 参数**的情况下，也能获取当前请求的上下文。
+- **register**  
+  请求生命周期 hook，在请求开始/结束/异常时被调用，可用于埋点、监控。
 
-### getCurrentContext()
+---
+
+### TrackId 配置：`trackId?: TrackIdConfig`
 
 ```ts
+export type TrackIdGenerator =
+  | false
+  | ((
+      ctx: Koa.Context
+    ) => string | null | undefined | Promise<string | null | undefined>);
+
+export interface TrackIdConfig {
+  generator?: TrackIdGenerator; // 默认：header 透传或 uuid.v4
+  exposeHeader?: boolean; // 默认 true
+  headerName?: string; // 默认 "x-request-id"
+}
+```
+
+- **generator**
+
+  - 不配置：默认使用 `x-request-id` header 或生成 `uuid.v4()`
+  - 设置为 `false`：禁用 trackId，不生成、不透传
+  - 自定义函数：可按业务需要生成（或透传） trackId
+
+- **exposeHeader**  
+  是否将 trackId 写回响应头（默认 `true`）。
+
+- **headerName**  
+  请求/响应中使用的 header 名称（默认 `"x-request-id"`）。
+
+---
+
+## 中间件链路与阶段扩展
+
+框架将中间件链路拆分为多个“阶段”（`MiddlewarePhase`），内部按顺序执行，用户可在每个阶段前/后扩展中间件。
+
+默认阶段顺序：
+
+1. **AsyncContext**  
+   AsyncLocalStorage 上下文中间件，保证在异步链路中可以获取当前请求的 `ctx`。
+
+2. **TrackId**  
+   TrackId 生成与透传中间件（根据 `trackId` 配置生成、挂载 `ctx.trackId`，并写入响应头）。
+
+3. **ErrorHandling**  
+   全局错误处理，中间件会捕获异常并调用 `error.handler`。
+
+4. **Logging**  
+   请求日志与耗时统计（结合 `log4` 和 `runtimeLog`）。
+
+5. **Security**  
+   CORS / 安全相关中间件（例如 `koa2-cors`）。
+
+6. **BodyParsing**  
+   `koa-bodyparser` + 请求参数挂载（`requestParamsMiddleware`）。
+
+7. **Auth**  
+   鉴权中间件，配合 `auth.handler` 与 `@AuthRouter`。
+
+8. **Routing**  
+   约定式路由分发（`@Router` / `@AuthRouter` + `@koa/router`）。
+
+### 阶段扩展：PhaseMiddlewareMap
+
+你可以在任意阶段插入自定义中间件：
+
+```ts
+import { MiddlewarePhase } from "koa-ts-core/types/core";
+
+createKoaApp({
+  phaseMiddlewares: {
+    [MiddlewarePhase.Logging]: {
+      before: [
+        async (ctx, next) => {
+          // 在内置 Logging 中间件之前
+          await next();
+        },
+      ],
+      use: [
+        async (ctx, next) => {
+          // 与内置 Logging 同阶段，追加在后面
+          await next();
+        },
+      ],
+      after: [
+        async (ctx, next) => {
+          // 整个 Logging 阶段之后
+          await next();
+        },
+      ],
+    },
+  },
+});
+```
+
+每个阶段都支持 `before` / `use` / `after` 三种插入点。
+
+---
+
+## 获取当前请求上下文（AsyncLocalStorage）
+
+框架通过 `AsyncLocalStorage` 在异步链路中保存 `Koa.Context`，无需层层传递 `ctx`，即可在任意业务代码中获取当前请求上下文。
+
+`context_middleware` 已在 `AsyncContext` 阶段自动挂载，你只需要在业务侧使用工具函数：
+
+```ts
+// 示例：getCurrentContext.ts（具体导出以实际实现为准）
 import { AsyncLocalStorage } from "async_hooks";
 import type { Context } from "koa";
 
-// 全局上下文存储
 export const contextStore = new AsyncLocalStorage<Context>();
 
-/**
- * 获取当前请求的 Koa Context
- *
- * 仅在被 AsyncLocalStorage 包裹的异步调用链中生效。
- * 若当前不存在上下文，将抛出异常。
- */
 export const getCurrentContext = (): Context => {
   const context = contextStore.getStore();
   if (!context) {
@@ -141,19 +334,17 @@ export const getCurrentContext = (): Context => {
 };
 ```
 
----
-
-## 中间件链路
+之后在任意位置：
 
-内置中间件按以下顺序执行：
+```ts
+import { getCurrentContext } from "koa-ts-core";
 
-1. AsyncLocalStorage 上下文中间件
-2. 全局错误处理
-3. 请求日志 / 响应时间统计
-4. CORS / 安全相关中间件
-5. Body 解析
-6. 鉴权（`authCheckCallback` + `@AuthRouter`）
-7. 约定式路由分发
+function doSomething() {
+  const ctx = getCurrentContext();
+  const trackId = (ctx as any).trackId;
+  ctx.log4?.info({ trackId }, "doSomething called");
+}
+```
 
 ---
 
@@ -210,7 +401,7 @@ export default User;
 
 ### REST 风格简写
 
-在不指定 method/path 时，`@Router` 会根据方法名进行推断：
+在不指定 method/path 时，`@Router` 会根据方法名推断：
 
 ```ts
 import Koa from "koa";
@@ -269,7 +460,7 @@ src
     └── api/v1/user.ts   # 参数校验器
 ```
 
-控制器中有方法 `userInfo` 时，对应的校验器为：
+示例：
 
 ```ts
 // src/validate/api/v1/user.ts
@@ -311,14 +502,6 @@ unSuccessRsp({ code, message, data });
 errorRsp(400, { message: "Bad Request" });
 ```
 
-类型签名（简化）：
-
-```ts
-export declare const successRsp: (options?: Options) => void;
-export declare const unSuccessRsp: (options?: Options) => void;
-export declare const errorRsp: (statusCode: number, options?: Options) => void;
-```
-
 ---
 
 ## 异常处理
@@ -340,7 +523,7 @@ export class CustomException extends BaseException {
 throw new CustomException("自定义异常");
 ```
 
-所有异常会被内置错误处理中间件捕获，并结合 `catchErrorCallback` 输出日志或自定义处理。
+所有异常会被内置错误处理中间件捕获，并结合 `error.handler` 输出日志或自定义处理。
 
 ---
 
@@ -367,65 +550,15 @@ env
 
 ## 文档生成（配合 koa-ts-cli）
 
-`koa-ts-core` 提供路由元信息，配合 `koa-ts-cli` 的 `koa-ts-cli doc` 命令，可以根据 `src/controller` 自动生成 `doc` 目录下的接口配置文件，并在运行时通过 `/doc` 路由查看渲染后的接口文档。
+`koa-ts-core` 提供路由元信息，配合 `koa-ts-cli` 的 `koa-ts-cli doc` 命令，可以根据 `src/controller` 自动生成接口配置，并在运行时通过 `/doc` 路由查看渲染后的接口文档（仅开发环境或 `DOC=true` 时启用）。
 
-具体 CLI 使用方式见：[koa-ts-cli](https://www.npmjs.com/package/koa-typescript-cli)（或对应仓库）。
+详细 CLI 使用方式参考：[koa-ts-cli](https://www.npmjs.com/package/koa-typescript-cli)。
 
 ---
 
-## 日志：log4js 集成
-
-配置项类型：
-
-```ts
-type TLog4 = boolean | ((instance: Log4js) => Log4js);
-```
-
-- 传入 `false` 或不传：不启用 log4
-- 传入 `true`：使用默认 log4 配置
-- 传入函数：自定义 log4 配置
-
-默认配置示例（`log4: true`）：
-
-```js
-log4js.configure({
-  appenders: {
-    console: { type: "console" },
-    file: {
-      type: "dateFile",
-      filename: "logs/app.log",
-      pattern: ".yyyy-MM-dd",
-      compress: true,
-      numBackups: 7,
-      alwaysIncludePattern: true,
-    },
-  },
-  categories: {
-    default: { appenders: ["console", "file"], level: "info" },
-  },
-});
-```
+## Context 扩展（部分示意）
 
-自定义示例：
-
-```ts
-initializeKoaApp({
-  log4: (instance) => {
-    return instance.configure({
-      appenders: { console: { type: "console" } },
-      categories: {
-        default: { appenders: ["console"], level: "debug" },
-      },
-    });
-  },
-});
-```
-
----
-
-## Context 扩展
-
-`koa-ts-core` 对 `Koa.Context` 做了类型拓展：
+框架对 `Koa.Context` 做了类型拓展，你可以在业务代码中使用这些字段：
 
 ```ts
 declare module "koa" {
@@ -446,6 +579,9 @@ declare module "koa" {
       post: Record<string, any>;
     };
 
+    // trackId（请求 ID）
+    trackId?: string;
+
     // 业务扩展字段
     extra: {
       get: Record<string, any>;
@@ -455,8 +591,6 @@ declare module "koa" {
 }
 ```
 
----
-
 ## 相关项目
 
 - [koa-ts-cli](https://www.npmjs.com/package/koa-typescript-cli)：基于 `koa-ts-core` 的脚手架 CLI 工具，支持项目创建、开发、生成文档、自动生成控制器与校验器等。

package/dist/global.d.ts

@@ -2,6 +2,8 @@ import "koa";
 
 declare module "koa" {
   interface DefaultContext {
+    // trackId
+    trackId?: string;
     // log4js
     log4?: import("log4js").Log4js;
     // hook