koa-ts-core v0.0.2

Koa Application Initialization

使用typescript开发koa, 提供约定式路由、权限校验、加载环境变量

安装

npm i koa-ts-core

宿主项目需要安装库

npm i koa koa-router dotenv

初始化

import { initializeKoaApp } from "koa-ts-core";

const [app] = await initializeKoaApp({
  // 权限校验
  authCheckCallback: () => {
    return Promise.resolve(true);
  },
});

app.listen();

函数说明

init

• options (TInitOPtions)：该参数是一组可选的配置对象，包含以下字段：

  • koaInstance (Koa)：自定义 Koa 实例。如果未提供，将创建一个新的 Koa 实例。

  • authCheckCallback (AuthRouterCallback)：鉴权路由回调函数，用于处理鉴权逻辑。

  • catchErrorCallback (TErrorCallback)：用于捕获错误时的回调函数。

  • registerHighPriorityMiddleware ((app: Koa) => void)) : 高优先级中间件注册函数，用于注册一些高优先级中间件。

能力

约定式路由

控制器注册路由，约定在src/controller目录下.ts 文件，使用@Router和@AuthRouter装饰器注册路由

--src
  --controller
    --user
      --user.ts

# src/controller/api/v1/user.ts
import { Router, AuthRouter } from "koa-ts-core";
import { Context } from "koa";

class User {
  @Router("get")
  // 注册普通路由
  async userInfo(ctx: Context) {
    ctx.body = {
      success: true,
    };
  }

  @AuthRouter("post")
  // 注册权限路由
  async setUserInfo(ctx: Context) {
    ctx.body = {
      success: true,
    };
  }
}

export default User;

权限校验

每一个控制器的路由注册方法有一个唯一对应的参数校验器，例如：目录src/controller/api/v1/user.ts中userInfo方法对应的校验器为src/validate/api/v1/user.ts中的静态方法userInfo

# 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');
    }
  }
}

export default UserValidate;

无 Context 请求响应

/**
 * 构建成功的请求响应
 * @param options - 成功响应的选项，如数据和消息
 */
export declare const successRsp: (options?: Options) => void;
/**
 * 构建不成功的请求响应，但 HTTP 状态码仍为 200
 * @param options - 包含可能的错误码、消息和数据
 */
export declare const unSuccessRsp: (options?: Options) => void;
/**
 * 构建异常请求响应，HTTP 状态码不为 200
 * @param statusCode - 要返回的 HTTP 状态码
 * @param options - 包含可能的错误信息、数据等
 */
export declare const errorRsp: (statusCode: number, options?: Options) => void;

异常处理

import { BaseException } from "koa-ts-core";
/**
 * 自定义异常
 */
export class CustomException extends BaseException {
  // 自定义异常码
  code = 1000;

  constructor(message: string) {
    super(message);
  }
}

throw new CustomException("自定义异常");

加载环境变量

使用dotenv库对.env 文件进行预加载，约定目录为env，支持以下文件约定

--env
  --.development.env
  --.production.env
  --.test.env
  --.common.env