koa-ts-core 0.0.3 → 0.0.4

package/README.md

@@ -0,0 +1,199 @@
+# Koa Application Initialization
+
+使用`typescript`开发`koa`, 提供约定式路由、权限校验、加载环境变量
+
+## 安装
+
+```shell
+npm i koa-ts-core
+```
+
+宿主项目需要安装库
+
+```shell
+npm i koa koa-router dotenv
+```
+
+## 初始化
+
+```typescript
+import { initializeKoaApp } from "koa-ts-core";
+
+const [app] = await initializeKoaApp({
+  // 权限校验
+  authCheckCallback: () => {
+    return Promise.resolve(true);
+  },
+  // 高优先级中间件注册
+  registerHighPriorityMiddleware: (app: Koa) => void,
+  // 异常处理
+  catchErrorCallback: (error: Error) => void,
+});
+
+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
+```
+
+```typescript
+# 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`
+
+```typescript
+# 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 请求响应
+
+```typescript
+/**
+ * 构建成功的请求响应
+ * @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;
+```
+
+### 异常处理
+
+```typescript
+import { BaseException } from "koa-ts-core";
+/**
+ * 自定义异常
+ */
+export class CustomException extends BaseException {
+  // 自定义异常码
+  code = 1000;
+
+  constructor(message: string) {
+    super(message);
+  }
+}
+
+throw new CustomException("自定义异常");
+```
+
+### 加载环境变量
+
+使用[dotenv](https://www.npmjs.com/package/dotenv)库对.env 文件进行预加载，约定目录为`env`，支持以下文件约定
+
+```
+--env
+  --.development.env
+  --.production.env
+  --.test.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';
+
+class Test {
+  @Router('get')
+  async get_test(ctx: Koa.Context) {
+    successRsp();
+  }
+}
+
+export default Test;
+
+# 构建生成的文档 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: {} }
+    };
+  }
+}
+
+```
+
+打开`/doc`路由地址，渲染文档

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "koa-ts-core",
-  "version": "0.0.3",
-  "description": "",
+  "version": "0.0.4",
+  "description": "koa-ts-core",
   "main": "dist/index.cjs.js",
   "module": "dist/index.esm.js",
   "types": "dist/index.d.ts",
@@ -9,25 +9,41 @@
     "dist"
   ],
   "scripts": {
-    "build": "npx rollup -c --bundleConfigAsCjs",
-    "build:dev": "NODE_ENV=development npx rollup -c --bundleConfigAsCjs"
+    "dev": "npx rollup -c -w",
+    "build": "npx rollup -c",
+    "link": "npm run build:dev && pnpm link --dir ..",
+    "build:dev": "NODE_ENV=development npx rollup -c --bundleConfigAsCjs",
+    "publish": "npm run build &&release-it",
+    "gen-doc": "npx ts-node src/generate.ts"
   },
-  "keywords": [],
+  "keywords": [
+    "koa",
+    "koa-ts",
+    "node-web"
+  ],
   "author": "",
   "license": "ISC",
   "dependencies": {
     "dotenv": "^16.4.7",
     "koa": "^2.15.4",
-    "koa-router": "^13.0.1"
+    "koa-router": "^13.0.1",
+    "pug": "^3.0.3",
+    "rollup-plugin-pug": "^1.1.1"
   },
   "devDependencies": {
+    "@rollup/plugin-commonjs": "^28.0.3",
+    "@rollup/plugin-node-resolve": "^16.0.0",
     "@rollup/plugin-terser": "^0.4.4",
     "@rollup/plugin-typescript": "^12.1.2",
     "@types/koa": "^2.15.0",
     "@types/koa-router": "^7.4.8",
     "@types/node": "^22.13.4",
+    "@types/pug": "^2.0.10",
+    "release-it": "^18.1.2",
+    "rollup": "^4.34.9",
+    "rollup-plugin-copy": "^3.5.0",
     "rollup-plugin-delete": "^2.1.0",
-    "typeorm": "^0.3.20",
+    "rollup-plugin-dts-alias": "^0.0.4",
     "typescript": "^5.7.3"
   },
   "engines": {