koa-ts-core 0.2.1 → 0.3.0

package/README.md

@@ -1,125 +1,81 @@
 # koa-ts-core
 
-基于 **TypeScript + [Koa3](https://koajs.com/)** 的轻量服务端核心库，提供：
+基于 **TypeScript + [Koa3](https://koajs.com/)** 的轻量级企业级服务端核心框架。
 
-- 约定式路由（装饰器，基于 `@koa/router`）
-- 权限与参数校验约定（控制器 + 校验器目录约定）
-- 全局错误处理与统一响应体
-- 环境变量加载（多环境合并）
-- 日志集成（log4，基于 log4js）
-- AsyncLocalStorage 请求上下文获取
-- 阶段式中间件管线与扩展（Phase Middleware）
-- TrackId（RequestId）生成与透传
-- 接口文档生成基础能力（配合 `koa-ts-cli` 使用）
+它提供了一套完整的开发约定与核心能力封装，包括装饰器路由、自动文档生成、链路追踪、全局异常处理等，旨在提升 Koa 项目的开发规范与效率。
 
-> 推荐配合脚手架工具 [koa-ts-cli](https://www.npmjs.com/package/koa-typescript-cli) 使用。
+> 推荐配合脚手架工具 [koa-ts-cli](https://www.npmjs.com/package/koa-typescript-cli) 使用最佳。
+
+## 🌟 核心特性
+
+- **装饰器路由**: 基于 `@koa/router` 封装，支持 `@Router`, `@AuthRouter`，风格类似 NestJS/Spring Boot。
+- **Swagger/OpenAPI 自动生成**: 支持“零配置”扫描模式（配合 CLI）和“装饰器”定义模式。自动识别 Path/Query/Header/Body 参数。
+- **全链路追踪 (Trace/Request ID)**: 基于 `AsyncLocalStorage`，内置 RequestId 生成与透传，支持全链路日志串联。
+- **全局异常处理**: 统一捕获异常，规范化错误响应。
+- **统一响应体**: 提供 `successRsp`, `errorRsp` 等工具函数，统一 API 返回格式。
+- **阶段式中间件 (Phase Middleware)**: 独创的生命周期阶段管理，允许在 AsyncContext、Auth、Routing 等任意阶段前后注入中间件。
+- **环境配置**: 自动加载 `.env.{environment}` 配置文件。
 
 ---
 
-## 安装
+## 🚀 快速开始
+
+### 安装
 
 ```bash
-npm i koa-ts-core
+npm install koa-ts-core reflect-metadata
 # 或
-yarn add koa-ts-core
-# 或
-pnpm add koa-ts-core
+pnpm add koa-ts-core reflect-metadata
 ```
 
----
-
-## 快速开始（推荐新 API）
+> ⚠️ 注意：必须在入口文件顶部引入 `reflect-metadata`，且 `tsconfig.json` 需开启 `experimentalDecorators` 和 `emitDecoratorMetadata`。
 
-### 初始化应用（`createKoaApp`）
+### 初始化
 
-在项目入口文件（如 `src/main.ts`）中：
+在入口文件 (如 `src/main.ts`) 中初始化应用：
 
 ```ts
-import Koa from "koa";
-import cors from "koa2-cors";
+import "reflect-metadata"; // 必须第一行引入
 import { createKoaApp } from "koa-ts-core";
+import Koa from "koa";
 
 async function bootstrap() {
   const [app] = await createKoaApp({
-    // 自定义 koa 实例（可选，不传则内部创建）
-    koaInstance: new Koa(),
-
-    // 鉴权配置（配合 @AuthRouter 使用）
-    auth: {
-      handler: async (ctx) => {
-        // TODO: 你的权限判断逻辑
-        // return true / false 或直接抛异常
-      },
+    // 基础配置
+    koaInstance: new Koa(), // 可选：传入自定义 Koa 实例
+    
+    // Swagger 文档配置
+    swagger: {
+      enabled: true,
+      path: "/swagger-ui",
+      title: "My API Service",
+      version: "1.0.0"
     },
 
-    // 错误处理配置
+    // 错误处理
     error: {
-      // 自定义错误处理函数
-      handler: (error, ctx) => {
-        console.error("Global error:", error);
-        // 这里可以做统一日志、告警上报等
-      },
-      // 是否在响应中暴露堆栈（默认：非生产环境为 true，生产为 false）
-      // exposeStack: process.env.NODE_ENV !== "production",
-    },
-
-    // 日志配置
-    log: {
-      // log4：基础日志能力（log4js）
-      // false 或不传：不启用 log4
-      // true: 使用默认 log4 配置
-      // 函数：自定义 log4 配置
-      log4: true,
-
-      // 是否开启每次请求的运行时日志
-      runtimeLog: true,
-    },
-
-    // Hook 配置：请求生命周期 request / response / error
-    hooks: {
-      register: (ctx, type) => {
-        // your tracing / metrics logic
-        // type: "request" | "response" | "error"
-      },
-    },
-
-    // CORS 中间件（例如 koa2-cors）
-    koa2Cors: cors(),
-
-    // TrackId（RequestId）配置
-    trackId: {
-      /**
-       * 生成 trackId 的函数：
-       * - 默认：优先从 header `x-request-id` 透传；没有就生成 uuid.v4()
-       * - 传入 false：禁用 trackId，不生成、不透传
-       */
-      // generator: false,
-
-      // 是否写回响应头（默认 true）
-      exposeHeader: true,
-
-      // header 名称（默认 "x-request-id"）
-      headerName: "x-request-id",
+      exposeStack: process.env.NODE_ENV === "development", // 开发环境暴露堆栈
+      handler: (err, ctx) => {
+        // 自定义错误上报逻辑 (如 Sentry)
+        console.error("Global Error Caught:", err);
+      }
     },
-
-    /**
-     * 阶段式中间件扩展
-     * 你可以在 AsyncContext / ErrorHandling / Logging / Security / BodyParsing / Auth / Routing
-     * 每一个阶段前/后插入自定义中间件
-     */
-    // phaseMiddlewares: {
-    //   [MiddlewarePhase.Logging]: {
-    //     before: [traceMiddleware],
-    //     use: [metricsMiddleware],
-    //     after: [yourCustomMiddleware],
-    //   },
-    // },
+    
+    // 全局鉴权回调 (配合 @AuthRouter)
+    auth: {
+      handler: async (ctx) => {
+        const token = ctx.header.authorization;
+        if (!token) throw new Error("Unauthorized");
+        // return true 表示通过
+        return true; 
+      }
+    }
   });
 
-  app.listen(process.env.APP_PORT ?? 3000, () => {
-    console.log(
-      `Server running at http://localhost:${process.env.APP_PORT ?? 3000}`
-    );
+  const port = process.env.APP_PORT || 3000;
+  app.listen(port, () => {
+    console.log(`Server running at http://localhost:${port}`);
+    console.log(`Swagger UI: http://localhost:${port}/swagger-ui`);
   });
 }
 
@@ -128,470 +84,167 @@ bootstrap();
 
 ---
 
-## 初始化配置说明（`CreateKoaOptions`）
-
-`createKoaApp(options?: Partial<CreateKoaOptions>)` 支持以下配置块：
-
-### 基础
-
-- **koaInstance?: 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` 使用。  
-  你可以在这里检查登录态、角色、权限，抛错或返回布尔值。
-
----
-
-### 错误处理配置：`error?: ErrorConfig`
-
-```ts
-interface ErrorConfig {
-  handler?: (error: unknown, ctx: Koa.Context) => void | Promise<void>;
-  exposeStack?: boolean; // 默认：非生产环境 true，生产 false
-}
-```
-
-- **handler**  
-  自定义错误回调，用于统一处理未捕获错误（日志、告警等）。
+## 📚 API 参考
 
-- **exposeStack**  
-  是否在响应中暴露错误堆栈信息，一般开发环境开启，生产关闭。
+### 1. 路由装饰器 (Routing Decorators)
 
----
+`koa-ts-core` 提供类级别和方法级别的路由定义。
 
-### 日志配置：`log?: LogConfig`
+#### `@Router(method, path)`
+普通路由装饰器。
+- `method`: 'get' | 'post' | 'put' | 'delete' | 'patch' | 'all' (默认 'get')
+- `path`: 路由路径 (支持 path-to-regexp 语法，如 `/:id`)
 
 ```ts
-type TLog4 =
-  | boolean
-  | ((instance: import("log4js").Log4js) => import("log4js").Log4js);
-
-interface LogConfig {
-  log4?: TLog4;
-  runtimeLog?: boolean;
+import { Router, Context } from "koa-ts-core";
+
+class UserController {
+  // GET /user/:id
+  @Router("get", "/user/:id")
+  async getUser(ctx: Context) {
+    const { id } = ctx.params;
+    ctx.body = { id };
+  }
+  
+  // 简写：不传参数默认 method='get', path='/方法名'
+  // GET /list
+  @Router() 
+  async list(ctx: Context) { ... }
 }
 ```
 
-- **log4**
-
-  - `false` / 不传：不启用 log4
-  - `true`：使用默认 log4js 配置
-  - `(instance) => instance`: 自定义配置 log4js 实例
-
-- **runtimeLog**  
-  是否开启每次请求的运行时日志（挂载到 `ctx.runtimeLog`，配合内置 `loggerMiddleware` 使用）。
-
----
-
-### Hook 配置：`hooks?: HookConfig`
+#### `@AuthRouter(method, path)`
+鉴权路由装饰器。
+执行前会先调用 `createKoaApp` 中配置的 `auth.handler`，只有返回 `true` 才放行。
 
 ```ts
-type HookType = "request" | "response" | "error";
-
-interface HookConfig {
-  register?: (ctx: Koa.Context, type: HookType) => void;
+@AuthRouter("post", "/admin/update")
+async update(ctx: Context) {
+  // 只有鉴权通过才会执行这里
 }
 ```
 
-- **register**  
-  请求生命周期 hook，在请求开始/结束/异常时被调用，可用于埋点、监控。
+### 2. Swagger / OpenAPI 装饰器
 
----
+完全支持 OpenAPI 3.0 标准元数据定义。
 
-### TrackId 配置：`trackId?: TrackIdConfig`
+- `@ApiTags(tags: string[])`: 定义 Controller 标签
+- `@ApiOperation(summary, description)`: 接口摘要
+- `@ApiParam(options)`: 定义 path 参数 (如 `/:id`)
+- `@ApiQuery(options)`: 定义 query 参数
+- `@ApiBody(options)`: 定义 request body
+- `@ApiResponse(options)`: 定义响应结构
 
 ```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"
+import { ApiTags, ApiOperation, ApiParam, ApiQuery, Router } from "koa-ts-core";
+
+@ApiTags(["Order"])
+class OrderController {
+  
+  @Router("get", "/order/:orderId")
+  @ApiOperation("获取订单详情")
+  @ApiParam({ name: "orderId", description: "订单ID", example: "123" })
+  @ApiQuery({ name: "detail", required: false, description: "是否返回详情" })
+  async getOrder(ctx: Context) { ... }
 }
 ```
 
-- **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-ts-cli doc` 生成了 `doc/` 目录，`swagger_collector` 会自动合并这些文档配置，无需手写繁琐的装饰器。
 
-export const getCurrentContext = (): Context => {
-  const context = contextStore.getStore();
-  if (!context) {
-    throw new Error("context is not exist");
-  }
-  return context;
-};
-```
+### 3. 取用上下文 (Context Store)
 
-之后在任意位置：
+无需在所有函数中透传 `ctx`。
 
 ```ts
 import { getCurrentContext } from "koa-ts-core";
 
+// 在任意 Service 或 Utils 中
 function doSomething() {
   const ctx = getCurrentContext();
-  const trackId = (ctx as any).trackId;
-  ctx.log4?.info({ trackId }, "doSomething called");
+  // 获取当前请求的 trackId
+  const traceId = ctx.trackId;
 }
 ```
 
----
-
-## 约定式路由
-
-### 目录约定
+### 4. 统一响应工具 (Response Helpers)
 
-控制器统一放在 `src/controller` 目录下，例如：
-
-```text
-src
-└── controller
-    └── api
-        └── v1
-            └── user.ts
-```
-
-### 基础用法：@Router 与 @AuthRouter
+提供了一组工具函数来标准化 API 返回结构 `{ code, message, data, trackId }`。
 
 ```ts
-// src/controller/api/v1/user.ts
-import { Context } from "koa";
-import { Router, AuthRouter } from "koa-ts-core";
-
-class User {
-  @Router("get", "/index/:userId")
-  async userInfo(ctx: Context) {
-    ctx.body = {
-      success: true,
-      userId: ctx.params.userId,
-    };
-  }
+import { successRsp, errorRsp, unSuccessRsp } from "koa-ts-core";
 
-  // 支持可选路由参数
-  @Router("get", "/user_list{/:user_name}")
-  async userList(ctx: Context) {
-    ctx.body = {
-      success: true,
-      userName: ctx.params.user_name,
-    };
-  }
+// 成功：HTTP 200, code=0
+successRsp({ data: { id: 1 } }); 
+// -> { code: 0, message: "success", data: { id: 1 }, trackId: "..." }
 
-  // 需要鉴权的路由
-  @AuthRouter("post", "/set_user_info")
-  async setUserInfo(ctx: Context) {
-    ctx.body = {
-      success: true,
-    };
-  }
-}
+// 业务失败：HTTP 200, code!=0
+unSuccessRsp({ code: 1001, message: "库存不足" });
 
-export default User;
+// 异常：HTTP 400/500...
+errorRsp(403, { message: "禁止访问" });
 ```
 
-### REST 风格简写
+### 5. 异常处理 (BaseException)
 
-在不指定 method/path 时，`@Router` 会根据方法名推断：
+推荐继承 `BaseException` 来抛出业务异常，通过全局错误中间件统一处理。
 
 ```ts
-import Koa from "koa";
-import { Router, successRsp } from "koa-ts-core";
-
-class Test {
-  @Router()
-  async get_(ctx: Koa.Context) {
-    successRsp({ data: "get request" });
-  }
-
-  @Router()
-  async post(ctx: Koa.Context) {
-    successRsp({ data: "post request" });
-  }
-
-  @Router()
-  async put(ctx: Koa.Context) {
-    successRsp({ data: "put request" });
-  }
-
-  @Router()
-  async delete(ctx: Koa.Context) {
-    successRsp({ data: "delete request" });
-  }
-
-  @Router()
-  async patch(ctx: Koa.Context) {
-    successRsp({ data: "patch request" });
-  }
+import { BaseException } from "koa-ts-core";
 
-  @Router()
-  async options(ctx: Koa.Context) {
-    successRsp({ data: "options request" });
+export class UserNotFoundException extends BaseException {
+  constructor() {
+    super("User not found");
+    this.code = 404001; 
   }
 }
 
-export default Test;
+// 在业务中：
+throw new UserNotFoundException();
+// 响应: HTTP 500 (默认), body: { code: 404001, message: "User not found" ... }
 ```
 
-> 实现基于 [`@koa/router`](https://www.npmjs.com/package/@koa/router)，路由参数格式参考 [`path-to-regexp`](https://github.com/pillarjs/path-to-regexp)。
-
 ---
 
-## 参数与权限校验约定
+## 🛠 高级配置
 
-### 目录结构
+### 阶段式中间件 (Phase Middleware)
 
-每个控制器方法对应一个校验器静态方法，目录约定如下：
+`koa-ts-core` 将请求生命周期划分为多个阶段：
+1. `AsyncContext` (上下文初始化)
+2. `TrackId` (追踪ID生成)
+3. `ErrorHandling` (全局错误捕获)
+4. `Logging` (日志记录)
+5. `Security` (Cors等)
+6. `BodyParsing` (请求体解析)
+7. `Auth` (鉴权)
+8. `Routing` (路由执行)
 
-```text
-src
-├── controller
-│   └── api/v1/user.ts   # 控制器
-└── validate
-    └── api/v1/user.ts   # 参数校验器
-```
-
-示例：
+您可以在 `createKoaApp` 时通过 `phaseMiddlewares` 选项，在任意阶段的前 (`before`)、后 (`after`) 或替换 (`use`) 该阶段。
 
 ```ts
-// src/validate/api/v1/user.ts
-import { Context } from "koa";
+import { MiddlewarePhase } from "koa-ts-core";
 
-class UserValidate {
-  static userInfo(ctx: Context) {
-    if (!ctx.query.id) {
-      throw new Error("id is required");
+createKoaApp({
+  phaseMiddlewares: {
+    [MiddlewarePhase.Auth]: {
+      before: [myCustomAuthCheckMiddleware] // 在内置 Auth 之前执行
     }
   }
-}
-
-export default UserValidate;
-```
-
-当路由命中 `userInfo` 时，会自动调用 `UserValidate.userInfo`，抛出的异常会进入统一错误处理。
-
----
-
-## 统一响应工具
-
-无需频繁访问 `ctx`，可使用以下工具构造统一格式响应：
-
-```ts
-/**
- * 成功响应（HTTP 状态码 200）
- */
-successRsp({ data, message });
-
-/**
- * 业务失败响应（HTTP 状态码仍为 200，但业务 code 非 0）
- */
-unSuccessRsp({ code, message, data });
-
-/**
- * 异常响应（HTTP 状态码非 200）
- */
-errorRsp(400, { message: "Bad Request" });
-```
-
----
-
-## 异常处理
-
-提供基础异常类 `BaseException`，可扩展自定义业务异常：
-
-```ts
-import { BaseException } from "koa-ts-core";
-
-export class CustomException extends BaseException {
-  code = 1000;
-
-  constructor(message: string) {
-    super(message);
-  }
-}
-
-// 使用
-throw new CustomException("自定义异常");
-```
-
-所有异常会被内置错误处理中间件捕获，并结合 `error.handler` 输出日志或自定义处理。
-
----
-
-## 环境变量加载
-
-约定使用 [dotenv](https://www.npmjs.com/package/dotenv) 自动加载 `env` 目录：
-
-```text
-env
-├── .common.env       # 所有环境公用
-├── .development.env  # 开发环境
-├── .production.env   # 生产环境
-└── .test.env         # 测试环境
+})
 ```
 
-根据 `NODE_ENV` 加载对应文件，并合并 `.common.env`。
-
-常用环境变量：
-
-- `process.env.APP_PORT`：服务监听端口
-- `process.env.ENV_DIR`：环境变量目录
-- 其他自定义业务配置
-
 ---
 
-## 文档生成（配合 koa-ts-cli）
-
-`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)。
+约定根目录下 `env/` 文件夹：
+- `.common.env` (公共配置)
+- `.development.env` (开发环境)
+- `.production.env` (生产环境)
 
 ---
 
-## Context 扩展（部分示意）
-
-框架对 `Koa.Context` 做了类型拓展，你可以在业务代码中使用这些字段：
-
-```ts
-declare module "koa" {
-  interface DefaultContext {
-    // log4js 实例
-    log4?: import("log4js").Log4js;
-
-    // 生命周期 hook
-    hook?: (ctx: Koa.Context, type: "request" | "response" | "error") => void;
-
-    // 是否启用运行时日志
-    runtimeLog: boolean;
-
-    // 校验后的参数
-    validated: {
-      params: Record<string, any>;
-      get: Record<string, any>;
-      post: Record<string, any>;
-    };
-
-    // trackId（请求 ID）
-    trackId?: string;
-
-    // 业务扩展字段
-    extra: {
-      get: Record<string, any>;
-      post: Record<string, any>;
-    };
-  }
-}
-```
-
-## 相关项目
+## 🔗 相关链接
 
-- [koa-ts-cli](https://www.npmjs.com/package/koa-typescript-cli)：基于 `koa-ts-core` 的脚手架 CLI 工具，支持项目创建、开发、生成文档、自动生成控制器与校验器等。
+- [GitHub仓库](https://github.com/SuPeiSen/koa-ts-core)
+- [koa-ts-cli 脚手架](https://github.com/SuPeiSen/koa-ts-cli)