koa-ts-core 0.1.0-dev.0 → 0.2.0

package/dist/init/index.d.ts

@@ -1,21 +1,8 @@
-import { TErrorCallback } from '../middleware/exception_middleware';
 import { appRouter } from '../router';
-import type { AuthRouterCallback } from '../types/route';
+import { CreateKoaOptions } from '../types/core';
 import Koa from "koa";
-import { TLog4 } from "./register_log";
-export type TInitOPtions = Partial<{
-    koaInstance: Koa;
-    corsMiddleware: Koa.Middleware;
-    authCheckCallback: AuthRouterCallback;
-    catchErrorCallback: TErrorCallback;
-    registerHighPriorityMiddleware: (app: Koa) => void;
-    registerHook: (ctx: Koa.Context, type: "request" | "response" | "error") => void;
-    log4: TLog4;
-    runtimeLog: boolean;
-}>;
 /**
- * 初始化core
- * @param {TInitOPtions} options
- * @returns {[Koa, typeof appRouter]} [app, appRouter]
+ * 创建并初始化 Koa 应用
+ * @returns [app 实例, 路由对象]
  */
-export declare const initializeKoaApp: (options: TInitOPtions) => Promise<[Koa, typeof appRouter]>;
+export declare const createKoaApp: (rawOptions: Partial<CreateKoaOptions>) => Promise<[Koa, typeof appRouter]>;

package/dist/init/register_log.d.ts

@@ -1,5 +1,5 @@
-import log4js, { Log4js } from "log4js";
-export type TLog4 = boolean | ((instance: Log4js) => Log4js);
+import { TLog4 } from '../types/core';
+import log4js from "log4js";
 /**
  * 注册log4
  * 如果log4为true，则使用默认配置

package/dist/init/register_middleware.d.ts

@@ -0,0 +1,14 @@
+import { ErrorConfig, Koa2CorsFn, PhaseMiddlewareMap, TrackIdConfig } from '../types/core';
+import Koa from "koa";
+/**
+ * 注册中间件
+ * @param app
+ * @param phaseMiddlewares
+ * @param options
+ */
+declare const registerMiddleware: (app: Koa, phaseMiddlewares: PhaseMiddlewareMap, options: {
+    errorConfig?: ErrorConfig;
+    koa2Cors?: Koa2CorsFn;
+    trackConfig: TrackIdConfig;
+}) => void;
+export default registerMiddleware;

package/dist/middleware/create_trackId_middleware.d.ts

@@ -0,0 +1,6 @@
+import type Koa from "koa";
+import { TrackIdConfig } from '../types/core';
+/**
+ * 创建 trackId 中间件
+ */
+export declare const createTrackIdMiddleware: (config: TrackIdConfig) => Koa.Middleware;

package/dist/middleware/exception_middleware.d.ts

@@ -1,10 +1,10 @@
 import BaseException from '../base/exception';
 import type Koa from "koa";
-export type TErrorCallback = (error: Error | BaseException, ctx: Koa.Context) => void;
+export type ErrorFn = (error: Error | BaseException, ctx: Koa.Context) => void;
 /**
  * 错误处理中间件
- * @param {TErrorCallback} catchCallback
+ * @param {ErrorFn} catchCallback
  * @returns
  */
-declare const catchErrorMiddleware: (catchCallback?: TErrorCallback) => (ctx: Koa.Context, next: Koa.Next) => Promise<void>;
+declare const catchErrorMiddleware: (catchCallback?: ErrorFn) => (ctx: Koa.Context, next: Koa.Next) => Promise<void>;
 export default catchErrorMiddleware;

package/dist/middleware/router_middleware.d.ts

@@ -0,0 +1,6 @@
+import type { Middleware } from "koa";
+/**
+ * 路由中间件
+ */
+declare const routerMiddleware: () => Middleware;
+export default routerMiddleware;

package/dist/types/core.d.ts

@@ -0,0 +1,88 @@
+import type Koa from "koa";
+import cors from "koa2-cors";
+import type { Log4js } from "log4js";
+import { AuthRouterCallback } from "./route";
+/**
+ * 中间件分阶段
+ */
+export declare enum MiddlewarePhase {
+    AsyncContext = "AsyncContext",
+    ErrorHandling = "ErrorHandling",
+    Logging = "Logging",
+    Security = "Security",
+    BodyParsing = "BodyParsing",
+    Auth = "Auth",
+    Routing = "Routing"
+}
+/**
+ * 阶段中间件配置
+ */
+export interface PhaseMiddlewareConfig {
+    before?: Koa.Middleware[];
+    use?: Koa.Middleware[];
+    after?: Koa.Middleware[];
+}
+export type TrackIdGenerator = false | ((ctx: Koa.Context) => string | Promise<string>);
+export interface TrackIdConfig {
+    /**
+     * 生成 trackId 的函数：
+     * - 默认：从 header 透传或生成 uuid.v4
+     * - 传入 false 则不生成、不透传
+     */
+    generator?: TrackIdGenerator;
+    /**
+     * 是否将 trackId 写回响应头
+     * @default true
+     */
+    exposeHeader?: boolean;
+    /**
+     * 使用的 header 名称
+     * @default "x-request-id"
+     */
+    headerName?: string;
+}
+export type ErrorFn = (err: unknown, ctx: Koa.Context) => Promise<void> | void;
+export type TLog4 = boolean | ((instance: Log4js) => Log4js);
+export type Koa2CorsFn = (koa2Cors: typeof cors) => Koa.Middleware;
+export type HookType = "request" | "response" | "error";
+export type RegisterHookFn = (ctx: Koa.Context, type: HookType) => void;
+export type PhaseMiddlewareMap = Map<MiddlewarePhase, PhaseMiddlewareConfig>;
+export interface AuthConfig {
+    handler: AuthRouterCallback;
+}
+export interface ErrorConfig {
+    handler?: ErrorFn;
+    /** 是否在响应中暴露堆栈信息（默认 dev=true, prod=false） */
+    exposeStack?: boolean;
+}
+export interface LogConfig {
+    /** log4 配置 */
+    log4?: TLog4;
+    /** 是否记录每次请求的运行日志（旧的 runtimeLog） */
+    runtimeLog?: boolean;
+}
+export interface HookConfig {
+    /** hook 注册函数（旧的 registerHook） */
+    register?: RegisterHookFn;
+}
+/**
+ * 初始化配置
+ */
+export interface CreateKoaOptions {
+    /** 支持自定义 koa 实例 */
+    koaInstance?: Koa;
+    /** 基于 koa2-cors */
+    koa2Cors?: Koa2CorsFn;
+    /** 鉴权配置（替代 authCheckCallback） */
+    auth?: AuthConfig;
+    /** 错误处理配置（替代 catchErrorCallback） */
+    error?: ErrorConfig;
+    /** 日志相关配置（替代 log4 + runtimeLog） */
+    log?: LogConfig;
+    /** hook 配置（替代 registerHook） */
+    hooks?: HookConfig;
+    /** 分阶段中间件扩展 */
+    phaseMiddlewares?: PhaseMiddlewareMap;
+    /** trackId 配置 */
+    trackId?: TrackIdConfig;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "koa-ts-core",
-  "version": "0.1.0-dev.0",
+  "version": "0.2.0",
   "description": "koa-ts-core",
   "main": "dist/index.cjs.js",
   "module": "dist/index.esm.js",
@@ -24,14 +24,17 @@
   "license": "ISC",
   "dependencies": {
     "@koa/router": "^15.2.0",
+    "@types/koa2-cors": "^2.0.6",
     "dotenv": "^17.2.3",
     "koa": "^3.1.1",
     "koa-bodyparser": "^4.4.1",
+    "koa2-cors": "^2.0.6",
     "log4js": "^6.9.1",
     "portfinder": "^1.0.38",
     "pug": "^3.0.3",
     "rollup-plugin-copy-and-reference-dts": "0.0.2",
-    "rollup-plugin-pug": "^1.1.1"
+    "rollup-plugin-pug": "^1.1.1",
+    "uuid": "^13.0.0"
   },
   "devDependencies": {
     "@rollup/plugin-commonjs": "^29.0.0",