kb-server 0.0.1-beta.2 → 0.0.1-beta.20

package/README.md

@@ -2,4 +2,19 @@
 
 快速创建一个 Node 服务
 
-快速创建API、标准错误码、Server、支持统一鉴权函数（API级别）
+快速创建 API、标准错误码、Server、支持统一鉴权函数（API 级别）、自定义中间件、日志、支持SSE
+
+```javascript
+import { createServer } from "kb-server";
+import * as apis from "./apis";
+
+// 写法一
+const server = createServer({ apis });
+server.listen(3000);
+
+// 写法二
+(async () => {
+  // 其他的异步操作，例如：初始化数据库
+  return createServer({ apis });
+})().then((app) => app.listen(3000));
+```

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

@@ -23,9 +23,10 @@ export interface APIErrorResponse {
         RequestId: string;
     };
 }
-export type AuthFunction = (action: string, req: express.Request) => Promise<Record<string, any> | false>;
+export type AuthFunction = (action: string, req: express.Request) => Promise<Record<string, any> | boolean> | boolean | Record<string, any>;
 interface IPackAPIOptions {
     authFn?: AuthFunction;
+    log?: boolean;
 }
 /**
  * API包装函数

package/dist/common/api-middleware.js

@@ -3,13 +3,14 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.packAPI = void 0;
 const create_errors_1 = require("./create-errors");
 const uuid_1 = require("uuid");
+const logger_1 = require("../helper/logger");
 /**
  * API包装函数
  * @param apis API列表
  * @returns
  */
 const packAPI = (apis, options) => {
-    const { authFn } = options || {};
+    const { authFn, log = true } = options || {};
     return async (req, res) => {
         // 生成API映射
         const apiMap = new Map(Object.entries(apis).map(([action, execution]) => [action, execution]));
@@ -25,6 +26,9 @@ const packAPI = (apis, options) => {
         try {
             // API 解析
             const { Action, ...params } = req.body || {};
+            if (log) {
+                logger_1.logger.log("info", `请求入参：${JSON.stringify(req.body)} - RequestId: ${requestId}`);
+            }
             // 接口未定义
             if (!Action) {
                 throw new create_errors_1.CommonErrors.InvalidParameter.EmptyAPIRequest();
@@ -38,8 +42,10 @@ const packAPI = (apis, options) => {
                 if (!authResult) {
                     throw new create_errors_1.CommonErrors.FailOperation.NoPermission();
                 }
-                // 把权限信息写入上下文
-                ctx.AuthInfo = authResult || {};
+                if (typeof authResult !== "boolean") {
+                    // 把权限信息写入上下文
+                    ctx.AuthInfo = authResult || {};
+                }
             }
             // API 处理
             const execution = apiMap.get(Action);
@@ -57,11 +63,12 @@ const packAPI = (apis, options) => {
             };
             // 完成响应
             took = Date.now() - start;
-            console.log("响应：", took, JSON.stringify(response));
+            logger_1.logger.log("info", `响应：${JSON.stringify(response)}`);
+            logger_1.logger.log("info", `耗时：${took} ms - RequestId: ${requestId}`);
             return res.send(response);
         }
         catch (rawError) {
-            console.log("原始错误：", rawError);
+            logger_1.logger.log("error", rawError);
             // 未知错误
             let error = new create_errors_1.CommonErrors.InternalError.UnknownError();
             // 可控错误
@@ -83,7 +90,8 @@ const packAPI = (apis, options) => {
             };
             // 完成响应
             took = Date.now() - start;
-            console.log("响应：", took, JSON.stringify(response));
+            logger_1.logger.log("info", `响应：${JSON.stringify(response)}`);
+            logger_1.logger.log("info", `耗时：${took} ms - RequestId: ${requestId}`);
             return res.send(response);
         }
     };

package/dist/common/call-service.d.ts

@@ -0,0 +1 @@
+export declare const callService: <P = Record<string, any>, R = any>(endpoint: string, body: P) => Promise<R>;

package/dist/common/call-service.js

@@ -0,0 +1,27 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.callService = void 0;
+const node_fetch_1 = __importDefault(require("node-fetch"));
+const create_errors_1 = require("./create-errors");
+const callService = async (endpoint, body) => {
+    const response = await (0, node_fetch_1.default)(endpoint, {
+        headers: {
+            "Content-Type": "application/json",
+        },
+        method: "POST",
+        body: JSON.stringify(body),
+    });
+    const result = await response.json();
+    if (result?.Response?.Error) {
+        const errMsg = result.Response.Error?.Message;
+        if (errMsg) {
+            throw new create_errors_1.CommonErrors.InternalError.ServiceError(errMsg);
+        }
+        throw new create_errors_1.CommonErrors.InternalError.ServiceError();
+    }
+    return result?.Response?.Data;
+};
+exports.callService = callService;

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

@@ -1,15 +1,24 @@
+import { ValidationError } from "class-validator";
 import { Class } from "utility-types";
-export interface ServerContext {
+export interface ServerContext<A = any> {
     /** 被调用方的 RequestId */
     RequestId: string;
     /** 权限信息 */
-    AuthInfo?: Record<string, any>;
+    AuthInfo?: A;
 }
 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 type APIExecution<P, R, A> = (
+/** 请求入参 */
+params: P, 
+/** 请求上下文 */
+ctx: ServerContext<A>) => Promise<R>;
+export type AnyAPIExecution = APIExecution<any, any, any>;
 export type APIs = Record<string, AnyAPIExecution>;
-export declare function createAPI<P, R>(ParamsClass: Class<P>, execution: APIExecution<P, R>): API<P, R>;
+export declare function createAPI<P, R, A>(ParamsClass: Class<P>, execution: APIExecution<P, R, A>): 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 declare function implementAPI<F extends (params: any) => any, A = Record<string, any>>(_actionStub: F, ParamsClass: Class<StubParam<F>>, execution: APIExecution<StubParam<F>, ReturnType<F>, A>): API<StubParam<F>, ReturnType<F>>;
+/**
+ * 解析错误信息
+ */
+export declare function getMessage(message: ValidationError, propertyPath?: string): string[];
 export {};

package/dist/common/create-api.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.implementAPI = exports.createAPI = void 0;
+exports.getMessage = 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");
@@ -15,10 +15,8 @@ function createAPI(ParamsClass, execution) {
             : (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(" "));
+            const errorMessages = errors.flatMap((error) => getMessage(error));
+            throw new create_errors_1.CommonErrors.InvalidParameter.ValidationError(errorMessages.join("\n"));
         }
         // 执行函数
         return await execution(params, ctx);
@@ -30,3 +28,26 @@ function implementAPI(_actionStub, ParamsClass, execution) {
     return createAPI(ParamsClass, execution);
 }
 exports.implementAPI = implementAPI;
+/**
+ * 解析错误信息
+ */
+function getMessage(message, propertyPath = "") {
+    const messages = [];
+    // 构建当前属性的完整路径
+    const currentPropertyPath = propertyPath
+        ? `${propertyPath}.${message.property}`
+        : message.property;
+    if (message.constraints) {
+        // 将所有约束错误合并为一个字符串
+        const constraintErrors = Object.values(message.constraints).join(", ");
+        messages.push(`${currentPropertyPath}: ${constraintErrors}`);
+    }
+    if (message.children && message.children.length > 0) {
+        // 递归处理子错误，并传递更新后的属性路径
+        for (const [_index, child] of message.children.entries()) {
+            messages.push(...getMessage(child, currentPropertyPath));
+        }
+    }
+    return messages;
+}
+exports.getMessage = getMessage;

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

@@ -1,8 +1,54 @@
+import express from "express";
 import { AuthFunction } from "./api-middleware";
 import { APIs } from "./create-api";
+import { SSEHandlers } from "./sse-middleware";
 export interface ICreateServerParams {
+    /**
+     * API列表
+     */
     apis: APIs;
+    /**
+     * SSE配置
+     */
+    sse?: {
+        handlers: SSEHandlers;
+        route?: string;
+    };
+    /**
+     * 鉴权函数
+     *
+     * 可以通过返回布尔值来定义权限，也可以直接返回数据对象，数据对象会被传递到上下文 ctx 中（AuthInfo）
+     */
     authFn?: AuthFunction;
+    /**
+     * 默认请求日志，true开启，false关闭
+     */
+    log?: boolean;
+    /**
+     * 自定义中间件列表
+     *
+     * @example
+     *
+     * ```
+     * import cors from "cors"; // 引入cors中间件
+     *
+     * ...其他代码...
+     *
+     * const server = createServer(
+     *  {
+     *    apis: myAPIs,
+     *    authFn: myAuthFunction,
+     *    log: true,
+     *    middlewares: [cors()], // 传入cors中间件
+     *  },
+     *  {
+     *    limit: "5mb",
+     *  }
+     *);
+     * ```
+     *
+     */
+    middlewares?: express.RequestHandler[];
 }
 export interface ICreateServerOptions {
     limit?: string | number | undefined;

package/dist/common/create-server.js

@@ -26,18 +26,24 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.createServer = void 0;
 const express_1 = __importStar(require("express"));
 const api_middleware_1 = require("./api-middleware");
+const sse_middleware_1 = require("./sse-middleware");
 /**
  * 创建 Server
  */
 function createServer(params, options) {
-    const { apis, authFn } = params || {};
+    const { apis, sse, authFn, log, middlewares = [] } = params || {};
     const { limit = "10mb" } = options || {};
+    const { handlers, route } = sse || {};
     const app = (0, express_1.default)();
     // POST 参数获取
     app.use((0, express_1.urlencoded)({ extended: true, limit }));
     app.use((0, express_1.json)({ limit }));
+    // 使用自定义中间件
+    middlewares.forEach((middleware) => app.use(middleware));
+    // 注入SSE
+    handlers && app.use((0, sse_middleware_1.packSSE)(handlers, { route }));
     // 注入API
-    app.use((0, api_middleware_1.packAPI)(apis, { authFn }));
+    app.use((0, api_middleware_1.packAPI)(apis, { authFn, log }));
     return app;
 }
 exports.createServer = createServer;

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

@@ -0,0 +1,25 @@
+import express from "express";
+import { ServerContext } from "./create-api";
+import { AuthFunction } from "./api-middleware";
+export type SseExecution<P, R, A> = (
+/** 请求入参 */
+params: P, 
+/** 请求上下文 */
+ctx: ServerContext<A>, 
+/**
+ * 允许执行的操作
+ */
+operations: {
+    /** 发送消息 */
+    send: (event: string, message: string) => void;
+}) => Promise<R>;
+export type AnySseExecution = SseExecution<any, any, any>;
+export type SSEHandlers = Record<string, AnySseExecution>;
+interface IPackSSEOptions {
+    authFn?: AuthFunction;
+    route?: string;
+    log?: boolean;
+}
+export declare const packSSE: (sseHandlers: SSEHandlers, options?: IPackSSEOptions) => express.RequestHandler;
+export declare const createSSEMessage: (event: string, message: string) => string;
+export {};

package/dist/common/sse-middleware.js

@@ -0,0 +1,124 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createSSEMessage = exports.packSSE = void 0;
+const uuid_1 = require("uuid");
+const logger_1 = require("../helper/logger");
+const create_errors_1 = require("./create-errors");
+const short_id_1 = require("../helper/short-id");
+const packSSE = (sseHandlers, options) => {
+    const sseMap = new Map(Object.entries(sseHandlers).map(([action, execution]) => [
+        action,
+        execution,
+    ]));
+    const { authFn, log = true, route = "/sse" } = options || {};
+    return async (req, res, next) => {
+        const { path } = req;
+        // 路径不是SSE的路径
+        if (path !== route) {
+            next();
+            return;
+        }
+        // 请求开始时间
+        const start = Date.now();
+        let took = 0;
+        // 生成请求ID
+        const requestId = (0, uuid_1.v4)();
+        // 上下文
+        const ctx = {
+            RequestId: requestId,
+        };
+        try {
+            // API 解析
+            const { Action, ...params } = req.body || {};
+            if (log) {
+                logger_1.logger.log("info", `请求入参：${JSON.stringify(req.body)} - RequestId: ${requestId}`);
+            }
+            // 接口未定义
+            if (!Action) {
+                throw new create_errors_1.CommonErrors.InvalidParameter.EmptyAPIRequest();
+            }
+            // 处理鉴权函数
+            if (authFn !== null && authFn !== undefined) {
+                if (typeof authFn !== "function") {
+                    throw new create_errors_1.CommonErrors.ResourceNotFound.AuthFunctionNotFound();
+                }
+                const authResult = await authFn(Action, req);
+                if (!authResult) {
+                    throw new create_errors_1.CommonErrors.FailOperation.NoPermission();
+                }
+                if (typeof authResult !== "boolean") {
+                    // 把权限信息写入上下文
+                    ctx.AuthInfo = authResult || {};
+                }
+            }
+            // API 处理
+            const execution = sseMap.get(Action);
+            if (typeof execution !== "function") {
+                throw new create_errors_1.CommonErrors.ResourceNotFound.APINotFound();
+            }
+            /**
+             * 开始处理SSE请求就要统计
+             *
+             * 请求处理完毕的时间
+             *
+             * 不要让 API 随意改写 req res 里面的东西
+             *
+             * 统一管理请求头
+             *
+             */
+            // 处理SSE
+            res.writeHead(200, {
+                "Content-Type": "text/event-stream",
+                "Cache-Control": "no-cache",
+                Connection: "keep-alive",
+            });
+            const send = (event, message) => {
+                const response = (0, exports.createSSEMessage)(event, message);
+                res.write(response);
+                logger_1.logger.log("info", `发送消息：${response}`);
+            };
+            await execution(params, ctx, { send });
+            // 完成响应
+            took = Date.now() - start;
+            logger_1.logger.log("info", `耗时：${took} ms - RequestId: ${requestId}`);
+            return res.end();
+        }
+        catch (rawError) {
+            logger_1.logger.log("error", 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 = (0, exports.createSSEMessage)("error", JSON.stringify({
+                Response: {
+                    Error: {
+                        Code: error.code,
+                        Message: error.message,
+                    },
+                    RequestId: requestId,
+                },
+            }));
+            // 完成响应
+            took = Date.now() - start;
+            logger_1.logger.log("info", `响应：${response}`);
+            logger_1.logger.log("info", `耗时：${took} ms - RequestId: ${requestId}`);
+            res.write(response);
+            return res.end();
+        }
+    };
+};
+exports.packSSE = packSSE;
+const createSSEMessage = (event, message) => {
+    const id = (0, short_id_1.shortId)();
+    const idStr = `id: ${id}\n`;
+    const eventStr = `event: ${event}\n`;
+    const dataStr = `data: ${message}\n\n`;
+    return idStr + eventStr + dataStr;
+};
+exports.createSSEMessage = createSSEMessage;

package/dist/helper/logger.d.ts

@@ -0,0 +1,6 @@
+export declare const logger: {
+    log: typeof log;
+};
+type LogLevel = "info" | "error" | "warning";
+declare function log(level: LogLevel, message: unknown): void;
+export {};

package/dist/helper/logger.js

@@ -0,0 +1,17 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.logger = void 0;
+const moment_1 = __importDefault(require("moment"));
+exports.logger = { log };
+function log(level, message) {
+    const logTime = (0, moment_1.default)().format(`YYYY-MM-DD HH:mm:ss`);
+    if (typeof message === "string") {
+        console.log(`[${level}] - [${logTime}] - ${message}`);
+    }
+    else {
+        console.log(`[${level}] - [${logTime}] - `, message);
+    }
+}

package/dist/helper/short-id.d.ts

@@ -0,0 +1 @@
+export declare const shortId: () => string;

package/dist/helper/short-id.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.shortId = void 0;
+const nanoid_1 = require("nanoid");
+const nanoid = (0, nanoid_1.customAlphabet)("123456789abcdefghijkmnpqrstuvwxyzABCDEFGHJKLMNPQRSTUVWXYZ", 10);
+const shortId = () => nanoid();
+exports.shortId = shortId;

package/dist/index.d.ts

@@ -1,3 +1,4 @@
 export { createServer } from "./common/create-server";
 export { createErrors } from "./common/create-errors";
-export { implementAPI } from "./common/create-api";
+export { implementAPI, ServerContext } from "./common/create-api";
+export { callService } from "./common/call-service";

package/dist/index.js

@@ -1,9 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.implementAPI = exports.createErrors = exports.createServer = void 0;
+exports.callService = exports.implementAPI = 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; } });
 var create_api_1 = require("./common/create-api");
 Object.defineProperty(exports, "implementAPI", { enumerable: true, get: function () { return create_api_1.implementAPI; } });
+var call_service_1 = require("./common/call-service");
+Object.defineProperty(exports, "callService", { enumerable: true, get: function () { return call_service_1.callService; } });

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "kb-server",
-  "version": "0.0.1-beta.2",
+  "version": "0.0.1-beta.20",
   "description": "A fast server for Node.JS,made by express.",
   "main": "dist/index.js",
   "scripts": {
-    "build": "tsc",
+    "build": "rm -rf ./dist && tsc",
     "test": "echo \"Error: no test specified\" && exit 1"
   },
   "keywords": [
@@ -23,10 +23,14 @@
     "class-validator": "^0.14.1",
     "express": "^4.21.1",
     "is-plain-object": "^5.0.0",
+    "moment": "^2.30.1",
+    "nanoid": "^5.1.3",
+    "node-fetch": "^2.7.0",
     "utility-types": "^3.11.0",
     "uuid": "^11.0.3"
   },
   "devDependencies": {
-    "@types/express": "^4.17.21"
+    "@types/express": "^4.17.21",
+    "@types/node-fetch": "^2.6.12"
   }
 }