kb-server 0.0.1-beta.1

package/README.md

@@ -0,0 +1,5 @@
+# KB Server
+
+快速创建一个 Node 服务
+
+快速创建API、标准错误码、Server

package/dist/common/api-middleware.d.ts

@@ -0,0 +1,25 @@
+import express from "express";
+import { AnyAPIExecution } from "./create-api";
+export interface APIResponse {
+    Response: {
+        Data: {
+            [key: string]: any;
+        };
+        RequestId: string;
+    };
+}
+export interface APIErrorResponse {
+    Response: {
+        Error: {
+            Code: string;
+            Message: string;
+        };
+        RequestId: string;
+    };
+}
+/**
+ * API包装函数
+ * @param apis API列表
+ * @returns
+ */
+export declare const packAPI: (apis: Record<string, AnyAPIExecution>) => (req: express.Request, res: express.Response) => Promise<express.Response<any, Record<string, any>>>;

package/dist/common/api-middleware.js

@@ -0,0 +1,79 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.packAPI = void 0;
+const create_errors_1 = require("./create-errors");
+const uuid_1 = require("uuid");
+/**
+ * API包装函数
+ * @param apis API列表
+ * @returns
+ */
+const packAPI = (apis) => {
+    return async (req, res) => {
+        // 生成API映射
+        const apiMap = new Map(Object.entries(apis).map(([action, execution]) => [action, execution]));
+        // 请求开始时间
+        const start = Date.now();
+        let took = 0;
+        // 生成请求ID
+        const requestId = (0, uuid_1.v4)();
+        // 上下文
+        const ctx = {
+            RequestId: requestId,
+        };
+        try {
+            console.log(req.body);
+            // API 解析
+            const { Action, ...params } = req.body || {};
+            // 接口未定义
+            if (!Action) {
+                throw new create_errors_1.CommonErrors.InvalidParameter.EmptyAPIRequest();
+            }
+            // API 处理
+            const execution = apiMap.get(Action);
+            if (typeof execution !== "function") {
+                throw new create_errors_1.CommonErrors.ResourceNotFound.APINotFound();
+            }
+            const result = await execution(params, ctx);
+            const response = {
+                Response: {
+                    Data: {
+                        ...(result || {}),
+                    },
+                    RequestId: requestId,
+                },
+            };
+            // 完成响应
+            took = Date.now() - start;
+            console.log("响应：", took, JSON.stringify(response));
+            return res.send(response);
+        }
+        catch (rawError) {
+            console.log("原始错误：", rawError);
+            // 未知错误
+            let error = new create_errors_1.CommonErrors.InternalError.UnknownError();
+            // 可控错误
+            if (rawError instanceof create_errors_1.BaseError) {
+                error = rawError;
+            }
+            // DB错误
+            if (rawError?.sql) {
+                error = new create_errors_1.CommonErrors.InternalError.DatabaseError();
+            }
+            const response = {
+                Response: {
+                    Error: {
+                        Code: error.code,
+                        Message: error.message,
+                    },
+                    RequestId: requestId,
+                },
+            };
+            // 完成响应
+            took = Date.now() - start;
+            console.log("响应：", took, JSON.stringify(response));
+            return res.send(response);
+        }
+    };
+};
+exports.packAPI = packAPI;

package/dist/common/create-api.d.ts

@@ -0,0 +1,14 @@
+import { Class } from "utility-types";
+export interface ServerContext {
+    /** 被调用方的 RequestId */
+    RequestId: string;
+    /** 用户ID */
+    UserId?: number;
+}
+export type API<P, R> = (param: P) => Promise<R>;
+export type APIExecution<P, R> = (params: P, ctx: ServerContext) => Promise<R>;
+export type AnyAPIExecution = APIExecution<any, any>;
+export declare function createAPI<P, R>(ParamsClass: Class<P>, execution: APIExecution<P, R>): API<P, R>;
+type StubParam<T> = T extends (params: infer P) => any ? P : never;
+export declare function implementAPI<A extends (params: any) => any>(_actionStub: A, ParamsClass: Class<StubParam<A>>, execution: APIExecution<StubParam<A>, ReturnType<A>>): API<StubParam<A>, ReturnType<A>>;
+export {};

package/dist/common/create-api.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.implementAPI = exports.createAPI = void 0;
+const class_transformer_1 = require("class-transformer");
+const class_validator_1 = require("class-validator");
+const create_errors_1 = require("./create-errors");
+function createAPI(ParamsClass, execution) {
+    const runtime = async (params, ctx) => {
+        if (!params) {
+            throw new create_errors_1.CommonErrors.InvalidParameter.EmptyParameter();
+        }
+        // 校验参数
+        const paramsToCheck = params instanceof ParamsClass
+            ? params
+            : (0, class_transformer_1.plainToClass)(ParamsClass, params);
+        const errors = await (0, class_validator_1.validate)(paramsToCheck || {});
+        if (errors?.length) {
+            const messages = errors.map((x, index) => {
+                return `\n${index}.<${x.property}>:${Object.values(x.constraints || { unknown: "reason unknown" }).join(", ")}`;
+            });
+            throw new create_errors_1.CommonErrors.InvalidParameter.ValidationError(messages.join(" "));
+        }
+        // 执行函数
+        return await execution(params, ctx);
+    };
+    return runtime;
+}
+exports.createAPI = createAPI;
+function implementAPI(_actionStub, ParamsClass, execution) {
+    return createAPI(ParamsClass, execution);
+}
+exports.implementAPI = implementAPI;

package/dist/common/create-errors.d.ts

@@ -0,0 +1,118 @@
+/// <reference types="node" />
+/**
+ * 允许的一级错误码
+ */
+declare const ALLOW_L1_ERROR_CODES: {
+    /** 参数错误 */
+    InvalidParameter: boolean;
+    /** 资源未找到 */
+    ResourceNotFound: boolean;
+    /** 失败的操作 */
+    FailOperation: boolean;
+    /** 服务端错误 */
+    InternalError: boolean;
+};
+type AllowL1ErrorCodesType = keyof typeof ALLOW_L1_ERROR_CODES;
+/**
+ * 通用错误码映射
+ */
+declare const CommonErrorsMap: {
+    readonly InvalidParameter: {
+        readonly EmptyParameter: "请求参数不能为空";
+        readonly EmptyAPIRequest: "未指定API的请求";
+        readonly ValidationError: "参数校验失败";
+    };
+    readonly ResourceNotFound: {
+        readonly APINotFound: "不存在的API";
+    };
+    readonly FailOperation: {
+        readonly NoPermission: "无权操作";
+        readonly NotLogin: "未登录";
+    };
+    readonly InternalError: {
+        readonly UnknownError: "未知错误";
+        readonly ServiceError: "内部服务错误";
+        readonly DatabaseError: "DB异常";
+    };
+};
+/**
+ * 错误基础类
+ */
+export declare class BaseError extends Error {
+    code: string;
+    message: string;
+    constructor(code: string, defaultMessage: string, message?: string);
+    toJson(): {
+        code: string;
+        message: string;
+    };
+}
+type CommonMessageMap = typeof CommonErrorsMap;
+type MessageMap<L1 extends AllowL1ErrorCodesType = AllowL1ErrorCodesType> = {
+    readonly [Code in L1]?: Record<string, string>;
+};
+type MergeMessageMap<M1, M2> = {
+    [K in keyof M1 | keyof M2]: K extends AllowL1ErrorCodesType ? K extends keyof M1 & keyof M2 ? M1[K] & M2[K] : K extends keyof M2 ? M2[K] : K extends keyof M1 ? M1[K] : never : never;
+};
+declare function createErrorClass(code: string, defaultMessage: string): {
+    new (...args: any): {
+        code: string;
+        message: string;
+        toJson(): {
+            code: string;
+            message: string;
+        };
+        name: string;
+        stack?: string | undefined;
+        cause?: unknown;
+    };
+    captureStackTrace(targetObject: object, constructorOpt?: Function | undefined): void;
+    prepareStackTrace?: ((err: Error, stackTraces: NodeJS.CallSite[]) => any) | undefined;
+    stackTraceLimit: number;
+};
+export type CoreError = InstanceType<ReturnType<typeof createErrorClass>>;
+declare function createErrorsClasses<T extends MessageMap = MessageMap>(messageMap: T): ErrorClasses<MergeMessageMap<{
+    readonly InvalidParameter: {
+        readonly EmptyParameter: "请求参数不能为空";
+        readonly EmptyAPIRequest: "未指定API的请求";
+        readonly ValidationError: "参数校验失败";
+    };
+    readonly ResourceNotFound: {
+        readonly APINotFound: "不存在的API";
+    };
+    readonly FailOperation: {
+        readonly NoPermission: "无权操作";
+        readonly NotLogin: "未登录";
+    };
+    readonly InternalError: {
+        readonly UnknownError: "未知错误";
+        readonly ServiceError: "内部服务错误";
+        readonly DatabaseError: "DB异常";
+    };
+}, T>>;
+type ErrorClasses<T = CommonMessageMap> = {
+    [Code in keyof T]: {
+        [E in keyof T[Code]]: E extends string ? ReturnType<typeof createErrorClass> : never;
+    };
+};
+export declare const CommonErrors: ErrorClasses<MergeMessageMap<{
+    readonly InvalidParameter: {
+        readonly EmptyParameter: "请求参数不能为空";
+        readonly EmptyAPIRequest: "未指定API的请求";
+        readonly ValidationError: "参数校验失败";
+    };
+    readonly ResourceNotFound: {
+        readonly APINotFound: "不存在的API";
+    };
+    readonly FailOperation: {
+        readonly NoPermission: "无权操作";
+        readonly NotLogin: "未登录";
+    };
+    readonly InternalError: {
+        readonly UnknownError: "未知错误";
+        readonly ServiceError: "内部服务错误";
+        readonly DatabaseError: "DB异常";
+    };
+}, {}>>;
+export declare const createErrors: typeof createErrorsClasses;
+export {};

package/dist/common/create-errors.js

@@ -0,0 +1,109 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createErrors = exports.CommonErrors = exports.BaseError = void 0;
+const plain_object_1 = require("../helper/plain-object");
+/**
+ * 允许的一级错误码
+ */
+const ALLOW_L1_ERROR_CODES = {
+    /** 参数错误 */
+    InvalidParameter: true,
+    /** 资源未找到 */
+    ResourceNotFound: true,
+    /** 失败的操作 */
+    FailOperation: true,
+    /** 服务端错误 */
+    InternalError: true,
+};
+/**
+ * 通用错误码映射
+ */
+const CommonErrorsMap = {
+    InvalidParameter: {
+        EmptyParameter: "请求参数不能为空",
+        EmptyAPIRequest: "未指定API的请求",
+        ValidationError: "参数校验失败",
+    },
+    ResourceNotFound: {
+        APINotFound: "不存在的API",
+    },
+    FailOperation: {
+        NoPermission: "无权操作",
+        NotLogin: "未登录",
+    },
+    InternalError: {
+        UnknownError: "未知错误",
+        ServiceError: "内部服务错误",
+        DatabaseError: "DB异常",
+    },
+};
+/**
+ * 错误基础类
+ */
+class BaseError extends Error {
+    code;
+    message;
+    // 允许自定义message
+    constructor(code, defaultMessage, message) {
+        super(message || defaultMessage);
+        this.code = code;
+        this.message = message || defaultMessage;
+    }
+    toJson() {
+        return {
+            code: this.code,
+            message: this.message,
+        };
+    }
+}
+exports.BaseError = BaseError;
+function mergeMessageMap(map1, map2) {
+    const merged = Object.create(null);
+    const allKeys = new Set([
+        ...Object.keys(map1),
+        ...Object.keys(map2),
+    ]);
+    // 遍历所有的key
+    for (const key of allKeys) {
+        if ((0, plain_object_1.isPlainObject)(map1[key]) && (0, plain_object_1.isPlainObject)(map2[key])) {
+            // 如果两个对象都有，则合并属性值
+            merged[key] = {
+                ...map1[key],
+                ...map2[key],
+            };
+        }
+        else {
+            // 取有值的一个
+            merged[key] = map1[key] || map2[key];
+        }
+    }
+    return merged;
+}
+function createErrorClass(code, defaultMessage) {
+    return class CoreError extends BaseError {
+        constructor(...args) {
+            let message;
+            if (typeof args[0] === "string") {
+                [message] = args;
+            }
+            super(code, defaultMessage, message);
+        }
+    };
+}
+function createErrorsClasses(messageMap) {
+    // 合并 Map
+    const mergedMessageMap = mergeMessageMap(CommonErrorsMap, messageMap);
+    return Object.entries(mergedMessageMap).reduce((categories, [category, keyMap]) => {
+        return {
+            ...categories,
+            [category]: Object.keys(keyMap).reduce((keys, key) => {
+                return {
+                    ...keys,
+                    [key]: createErrorClass(`${category}.${key}`, mergedMessageMap[category][key]),
+                };
+            }, {}),
+        };
+    }, {});
+}
+exports.CommonErrors = createErrorsClasses({});
+exports.createErrors = createErrorsClasses;

package/dist/common/create-server.d.ts

@@ -0,0 +1,11 @@
+import { AnyAPIExecution } from "./create-api";
+export interface ICreateServerParams {
+    apis: Record<string, AnyAPIExecution>;
+}
+export interface ICreateServerOptions {
+    limit?: string | number | undefined;
+}
+/**
+ * 创建 Server
+ */
+export declare function createServer(params: ICreateServerParams, options?: ICreateServerOptions): import("express-serve-static-core").Express;

package/dist/common/create-server.js

@@ -0,0 +1,43 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createServer = void 0;
+const express_1 = __importStar(require("express"));
+const api_middleware_1 = require("./api-middleware");
+/**
+ * 创建 Server
+ */
+function createServer(params, options) {
+    const { apis } = params || {};
+    const { limit = "10mb" } = options || {};
+    const app = (0, express_1.default)();
+    // POST 参数获取
+    app.use((0, express_1.urlencoded)({ extended: true, limit }));
+    app.use((0, express_1.json)({ limit }));
+    // 注入API
+    app.use((0, api_middleware_1.packAPI)(apis));
+    return app;
+}
+exports.createServer = createServer;

package/dist/helper/plain-object.d.ts

@@ -0,0 +1,4 @@
+export interface PlainObject {
+    [key: string]: unknown;
+}
+export declare function isPlainObject(obj: unknown): obj is PlainObject;

package/dist/helper/plain-object.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isPlainObject = void 0;
+const is_plain_object_1 = require("is-plain-object");
+function isPlainObject(obj) {
+    return (0, is_plain_object_1.isPlainObject)(obj);
+}
+exports.isPlainObject = isPlainObject;

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { createServer } from "./common/create-server";
+export { createErrors, CommonErrors } from "./common/create-errors";
+export { implementAPI } from "./common/create-api";

package/dist/index.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.implementAPI = exports.CommonErrors = exports.createErrors = exports.createServer = void 0;
+var create_server_1 = require("./common/create-server");
+Object.defineProperty(exports, "createServer", { enumerable: true, get: function () { return create_server_1.createServer; } });
+var create_errors_1 = require("./common/create-errors");
+Object.defineProperty(exports, "createErrors", { enumerable: true, get: function () { return create_errors_1.createErrors; } });
+Object.defineProperty(exports, "CommonErrors", { enumerable: true, get: function () { return create_errors_1.CommonErrors; } });
+var create_api_1 = require("./common/create-api");
+Object.defineProperty(exports, "implementAPI", { enumerable: true, get: function () { return create_api_1.implementAPI; } });

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "kb-server",
+  "version": "0.0.1-beta.1",
+  "description": "A fast server for Node.JS,made by express.",
+  "main": "dist/index.js",
+  "scripts": {
+    "build": "tsc",
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [
+    "2kb",
+    "kb",
+    "kb-server"
+  ],
+  "files": [
+    "dist/",
+    "README.md"
+  ],
+  "author": "broxiang",
+  "license": "ISC",
+  "dependencies": {
+    "class-transformer": "^0.5.1",
+    "class-validator": "^0.14.1",
+    "express": "^4.21.1",
+    "is-plain-object": "^5.0.0",
+    "utility-types": "^3.11.0",
+    "uuid": "^11.0.3"
+  },
+  "devDependencies": {
+    "@types/express": "^4.17.21"
+  }
+}