koa-ts-core 0.0.31 → 0.0.33

package/README.md

@@ -1,106 +1,173 @@
-# Koa Application Initialization
+# koa-ts-core
 
-使用`typescript`开发`koa`, 提供约定式路由、权限校验、加载环境变量
+基于 **TypeScript + Koa** 的轻量服务端核心库，提供：
+
+- 约定式路由（装饰器）
+- 权限与参数校验约定
+- 全局错误处理与统一响应体
+- 环境变量加载
+- 日志（log4js）集成
+- 接口文档生成基础能力（配合 `koa-ts-cli` 使用）
+
+> 推荐配合脚手架工具 [koa-ts-cli](https://www.npmjs.com/package/koa-typescript-cli) 使用。
+
+---
 
 ## 安装
 
-```shell
+```bash
 npm i koa-ts-core
+# 或
+yarn add koa-ts-core
 ```
 
-## 初始化
+---
 
-```typescript
-import { initializeKoaApp } from "koa-ts-core";
+## 快速开始
 
-const [app] = await initializeKoaApp({
-  // 权限校验
-  authCheckCallback: () => {
-    return Promise.resolve(true);
-  },
-  // 高优先级中间件注册
-  registerHighPriorityMiddleware: (app: Koa) => void,
-  // 异常处理
-  catchErrorCallback: (error: Error) => void,
-  // hook
-  registerHook: (
-    ctx: Koa.Context,
-    type: "request" | "response" | "error"
-  ) => void;
-  // 是否挂载log4到context
-  log4: TLog4;
-  // 是否挂载运行时日志
-  runtimeLog: boolean;
-});
+### 初始化应用
+
+在项目入口文件（如 `src/main.ts`）中：
 
-app.listen();
+```ts
+import Koa from "koa";
+import cors from "koa2-cors";
+import { initializeKoaApp, TLog4 } from "koa-ts-core";
+
+async function bootstrap() {
+  const [app] = await initializeKoaApp({
+    // 鉴权逻辑（配合 @AuthRouter 使用）
+    authCheckCallback: async (ctx) => {
+      // TODO: 你的权限判断
+      return true;
+    },
+
+    // CORS 中间件
+    corsMiddleware: cors(),
+
+    // 高优先级中间件（在内置中间件之前执行）
+    registerHighPriorityMiddleware: (app: Koa) => {
+      // app.use(yourMiddleware);
+    },
+
+    // 全局错误回调
+    catchErrorCallback: (error, ctx) => {
+      console.error("Global error:", error);
+    },
+
+    // 请求生命周期 hook：request / response / error
+    registerHook: (ctx, type) => {
+      // your tracing / metrics logic
+    },
+
+    // 日志：true 为默认配置，函数为自定义配置
+    log4: true as TLog4,
+
+    // 是否开启运行时日志
+    runtimeLog: true,
+  });
+
+  app.listen(process.env.APP_PORT ?? 3000, () => {
+    console.log(
+      `Server running at http://localhost:${process.env.APP_PORT ?? 3000}`
+    );
+  });
+}
+
+bootstrap();
 ```
 
-## 函数说明
+---
 
-### `init`
+## 初始化配置说明
 
-- options (TInitOPtions)：该参数是一组可选的配置对象，包含以下字段：
+`initializeKoaApp(options?: TInitOptions)` 支持以下字段：
 
-  - koaInstance (Koa)：自定义 Koa 实例。如果未提供，将创建一个新的 Koa 实例。
+- **koaInstance?: Koa**  
+  自定义 Koa 实例，不传则自动创建。
 
-  - authCheckCallback (AuthRouterCallback)：鉴权路由回调函数，用于处理鉴权逻辑。
+- **corsMiddleware?: Koa.Middleware**  
+  CORS 中间件。
 
-  - catchErrorCallback (TErrorCallback)：用于捕获错误时的回调函数。
+- **authCheckCallback?: (ctx: Koa.Context) => boolean | Promise<boolean>**  
+  鉴权回调，配合 `@AuthRouter` 使用。
 
-  - registerHighPriorityMiddleware ((app: Koa) => void)) : 高优先级中间件注册函数，用于注册一些高优先级中间件。
+- **catchErrorCallback?: (error: Error, ctx?: Koa.Context) => void**  
+  全局错误回调，用于统一处理未捕获错误。
 
-  - registerHook ((ctx: Koa.Context, type: "request" | "response" | "error") => void) : hook 注册函数，用于注册一些 hook
+- **registerHighPriorityMiddleware?: (app: Koa) => void**  
+  高优先级中间件注册函数，在框架内置中间件之前执行。
 
-  - log4 (TLog4) : 是否挂载 log4 到 context
+- **registerHook?: (ctx: Koa.Context, type: "request" | "response" | "error") => void**  
+  请求生命周期 hook。
 
-  - runtimeLog (boolean) : 是否挂载运行时日志
+- **log4?: TLog4**  
+  是否挂载 log4js 及配置方式：
 
-## 能力
+  - `false` / 不传：不启用 log4
+  - `true`：使用默认 log4js 配置
+  - `(instance: Log4js) => Log4js`：自定义配置
 
-### 内置部分中间件
+- **runtimeLog?: boolean**  
+  是否挂载运行时日志能力到 `ctx.runtimeLog`。
 
-#### 按优先级排序
+---
 
-AsyncLocalStorage 上下文中间件 => 全局错误处理 => 请求日志 / 响应时间统计 => CORS / 安全相关 => 解析 body => 鉴权 => 路由
+## 中间件链路
 
-### 约定式路由
+内置中间件按以下顺序执行：
 
-控制器注册路由，约定在`src/controller`目录下.ts 文件，使用`@Router`和`@AuthRouter`装饰器注册路由
+1. AsyncLocalStorage 上下文中间件
+2. 全局错误处理
+3. 请求日志 / 响应时间统计
+4. CORS / 安全相关中间件
+5. Body 解析
+6. 鉴权（`authCheckCallback` + `@AuthRouter`）
+7. 约定式路由分发
 
-```
---src
-  --controller
-    --user
-      --user.ts
+---
+
+## 约定式路由
+
+### 目录约定
+
+控制器统一放在 `src/controller` 目录下，例如：
+
+```text
+src
+└── controller
+    └── api
+        └── v1
+            └── user.ts
 ```
 
-```typescript
-# src/controller/api/v1/user.ts
-import { Router, AuthRouter } from "koa-ts-core";
+### 基础用法：@Router 与 @AuthRouter
+
+```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,
     };
   }
 
-  // 可选路由参数
+  // 支持可选路由参数
   @Router("get", "/user_list{/:user_name}")
   async userList(ctx: Context) {
-    const userName = ctx.params.user_name;
     ctx.body = {
       success: true,
-      userName
+      userName: ctx.params.user_name,
     };
   }
 
-  @AuthRouter("post")
-  // 注册权限路由
+  // 需要鉴权的路由
+  @AuthRouter("post", "/set_user_info")
   async setUserInfo(ctx: Context) {
     ctx.body = {
       success: true,
@@ -111,78 +178,77 @@ class User {
 export default User;
 ```
 
-#### 支持 REST 风格定义
+### REST 风格简写
 
-```typescript
+在不指定 method/path 时，`@Router` 会根据方法名进行推断：
+
+```ts
 import Koa from "koa";
 import { Router, successRsp } from "koa-ts-core";
 
 class Test {
   @Router()
   async get_(ctx: Koa.Context) {
-    successRsp({
-      data: "get request",
-    });
+    successRsp({ data: "get request" });
   }
 
   @Router()
   async post(ctx: Koa.Context) {
-    successRsp({
-      data: "post request",
-    });
+    successRsp({ data: "post request" });
   }
 
   @Router()
   async put(ctx: Koa.Context) {
-    successRsp({
-      data: "put request",
-    });
+    successRsp({ data: "put request" });
   }
 
   @Router()
   async delete(ctx: Koa.Context) {
-    successRsp({
-      data: "delete request",
-    });
+    successRsp({ data: "delete request" });
   }
 
   @Router()
   async patch(ctx: Koa.Context) {
-    successRsp({
-      data: "patch request",
-    });
+    successRsp({ data: "patch request" });
   }
 
   @Router()
   async options(ctx: Koa.Context) {
-    successRsp({
-      data: "options request",
-    });
+    successRsp({ data: "options request" });
   }
 }
 
 export default Test;
 ```
 
-#### 装饰器实现
+> 实现基于 [`@koa/router`](https://www.npmjs.com/package/@koa/router)，路由参数格式参考 [`path-to-regexp`](https://github.com/pillarjs/path-to-regexp)。
 
-`@Router`和`@AuthRouter`装饰器实现是基于[@koa/router](https://www.npmjs.com/package/@koa/router)进行封装
+---
 
-ps:路由参数参考[path-to-regexp](https://github.com/pillarjs/path-to-regexp)
+## 参数与权限校验约定
 
-### 权限校验
+### 目录结构
 
-每一个控制器的路由注册方法有一个唯一对应的参数校验器，例如：目录`src/controller/api/v1/user.ts`中`userInfo`方法对应的校验器为`src/validate/api/v1/user.ts`中的静态方法`userInfo`
+每个控制器方法对应一个校验器静态方法，目录约定如下：
 
-```typescript
-# src/validate/api/v1/user.ts
+```text
+src
+├── controller
+│   └── api/v1/user.ts   # 控制器
+└── validate
+    └── api/v1/user.ts   # 参数校验器
+```
+
+控制器中有方法 `userInfo` 时，对应的校验器为：
 
-import { Context } from 'koa';
+```ts
+// src/validate/api/v1/user.ts
+import { Context } from "koa";
 
 class UserValidate {
   static userInfo(ctx: Context) {
     if (!ctx.query.id) {
-      throw new Error('id is required');
+      throw new Error("id is required");
     }
   }
 }
@@ -190,36 +256,49 @@ class UserValidate {
 export default UserValidate;
 ```
 
-### 无 Context 请求响应
+当路由命中 `userInfo` 时，会自动调用 `UserValidate.userInfo`，抛出的异常会进入统一错误处理。
+
+---
+
+## 统一响应工具
 
-```typescript
+无需频繁访问 `ctx`，可使用以下工具构造统一格式响应：
+
+```ts
 /**
- * 构建成功的请求响应
- * @param options - 成功响应的选项，如数据和消息
+ * 成功响应（HTTP 状态码 200）
  */
-export declare const successRsp: (options?: Options) => void;
+successRsp({ data, message });
+
 /**
- * 构建不成功的请求响应，但 HTTP 状态码仍为 200
- * @param options - 包含可能的错误码、消息和数据
+ * 业务失败响应（HTTP 状态码仍为 200，但业务 code 非 0）
  */
-export declare const unSuccessRsp: (options?: Options) => void;
+unSuccessRsp({ code, message, data });
+
 /**
- * 构建异常请求响应，HTTP 状态码不为 200
- * @param statusCode - 要返回的 HTTP 状态码
- * @param options - 包含可能的错误信息、数据等
+ * 异常响应（HTTP 状态码非 200）
  */
+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;
 ```
 
-### 异常处理
+---
+
+## 异常处理
 
-```typescript
+提供基础异常类 `BaseException`，可扩展自定义业务异常：
+
+```ts
 import { BaseException } from "koa-ts-core";
-/**
- * 自定义异常
- */
+
 export class CustomException extends BaseException {
-  // 自定义异常码
   code = 1000;
 
   constructor(message: string) {
@@ -227,75 +306,61 @@ export class CustomException extends BaseException {
   }
 }
 
+// 使用
 throw new CustomException("自定义异常");
 ```
 
-### 加载环境变量
+所有异常会被内置错误处理中间件捕获，并结合 `catchErrorCallback` 输出日志或自定义处理。
 
-使用[dotenv](https://www.npmjs.com/package/dotenv)库对.env 文件进行预加载，约定目录为`env`，支持以下文件约定
+---
 
-```
---env
-  --.development.env
-  --.production.env
-  --.test.env
-  --.common.env
+## 环境变量加载
+
+约定使用 [dotenv](https://www.npmjs.com/package/dotenv) 自动加载 `env` 目录：
+
+```text
+env
+├── .common.env       # 所有环境公用
+├── .development.env  # 开发环境
+├── .production.env   # 生产环境
+└── .test.env         # 测试环境
 ```
 
-### 根据配置生成文档
+根据 `NODE_ENV` 加载对应文件，并合并 `.common.env`。
 
-在项目目录下执行`koa-ts-cli doc`，根据`controller`目录下生成在根目录`doc`目录下的配置文档
+常用环境变量：
 
-```typescript
-# 控制器目录 src/controller/test.ts
-import Koa from 'koa';
-import { successRsp, Router, AuthRouter } from 'koa-ts-core';
+- `process.env.APP_PORT`：服务监听端口
+- 其他自定义业务配置
 
-class Test {
-  @Router('get')
-  async get_test(ctx: Koa.Context) {
-    successRsp();
-  }
-}
+---
 
-export default Test;
+## 文档生成（配合 koa-ts-cli）
 
-# 构建生成的文档 doc/test.ts
-export default class Test {
-  static desc = '';
-  get_test() {
-    return {
-      method: 'get',
-      description: '',
-      path: '/get_test',
-      request: {
-        header: { 'Content-Type': 'application/json', Authorization: '' },
-        body: {},
-        query: {}
-      },
-      response: { body: {} }
-    };
-  }
-}
+`koa-ts-core` 提供路由元信息，配合 `koa-ts-cli` 的 `koa-ts-cli doc` 命令，可以根据 `src/controller` 自动生成 `doc` 目录下的接口配置文件，并在运行时通过 `/doc` 路由查看渲染后的接口文档。
 
-```
+具体 CLI 使用方式见：[koa-ts-cli](https://www.npmjs.com/package/koa-typescript-cli)（或对应仓库）。
 
-打开`/doc`路由地址，渲染文档
+---
 
-### 挂载 log4
+## 日志：log4js 集成
 
-使用[log4js](https://www.npmjs.com/package/log4js)库对日志进行预加载
+配置项类型：
 
-```typescript
+```ts
 type TLog4 = boolean | ((instance: Log4js) => Log4js);
 ```
 
-如果传入值为`true`，则使用默认配置
+- 传入 `false` 或不传：不启用 log4
+- 传入 `true`：使用默认 log4 配置
+- 传入函数：自定义 log4 配置
+
+默认配置示例（`log4: true`）：
 
 ```js
 log4js.configure({
   appenders: {
-    console: { type: "console" }, // 控制台输出
+    console: { type: "console" },
     file: {
       type: "dateFile",
       filename: "logs/app.log",
@@ -311,22 +376,57 @@ log4js.configure({
 });
 ```
 
-如需覆盖默认配置，传入函数
+自定义示例：
 
-```typescript
+```ts
 initializeKoaApp({
   log4: (instance) => {
     return instance.configure({
-      appenders: {
-        console: { type: "console" }, // 控制台输出
+      appenders: { console: { type: "console" } },
+      categories: {
+        default: { appenders: ["console"], level: "debug" },
       },
     });
   },
 });
 ```
 
-### 配置项
+---
+
+## Context 扩展
+
+`koa-ts-core` 对 `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>;
+    };
+
+    // 业务扩展字段
+    extra: {
+      get: Record<string, any>;
+      post: Record<string, any>;
+    };
+  }
+}
+```
+
+---
 
-#### process.env.APP_PORT
+## 相关项目
 
-koa 应用启动端口
+- [koa-ts-cli](https://www.npmjs.com/package/koa-typescript-cli)：基于 `koa-ts-core` 的脚手架 CLI 工具，支持项目创建、开发、生成文档、自动生成控制器与校验器等。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "koa-ts-core",
-  "version": "0.0.31",
+  "version": "0.0.33",
   "description": "koa-ts-core",
   "main": "dist/index.cjs.js",
   "module": "dist/index.esm.js",