wok-server 0.1.7 → 0.1.8

package/dist/cache/cache.js

@@ -34,15 +34,15 @@ class Cache {
     get(key) {
         const content = this.valueMap.get(key);
         if (!content) {
-            this.stat.addGet(false);
+            this.stat?.addGet(false);
             return undefined;
         }
         if (content.expireAt < new Date().getTime()) {
-            this.stat.addGet(false);
+            this.stat?.addGet(false);
             this.valueMap.delete(key);
             return undefined;
         }
-        this.stat.addGet(true);
+        this.stat?.addGet(true);
         return content.val;
     }
     /**
@@ -50,7 +50,7 @@ class Cache {
      */
     clear() {
         this.valueMap.clear();
-        this.stat.clear();
+        this.stat?.clear();
     }
     /**
      * 删除.
@@ -68,10 +68,10 @@ class Cache {
     async computeIfAbsent(key, provider, expiresInSeconds) {
         const content = this.valueMap.get(key);
         if (content && content.expireAt >= new Date().getTime()) {
-            this.stat.addGet(true);
+            this.stat?.addGet(true);
             return content.val;
         }
-        this.stat.addGet(false);
+        this.stat?.addGet(false);
         // 如果已经在处理中，则直接返回 promise
         const ep = this.promiseMap.get(key);
         if (ep) {

package/dist/cache/index.js

@@ -7,17 +7,17 @@ const config_1 = require("./config");
 const purge_task_1 = require("./purge-task");
 const stat_1 = require("./stat");
 const valueMap = new Map();
-const stat = new stat_1.CacheStat(valueMap);
+const stat = config_1.config.statTaskEnabled ? new stat_1.CacheStat(valueMap) : undefined;
 const cache = new cache_1.Cache(valueMap, stat);
 // 清理任务
 (0, task_1.scheduleWithFixedDelay)(config_1.config.cleaningInterval, config_1.config.cleaningInterval, new purge_task_1.PurgeTask(valueMap));
 // 统计任务
 if (config_1.config.statTaskEnabled) {
     (0, task_1.scheduleWithFixedDelay)(config_1.config.statInterval, config_1.config.statInterval, {
-        name: 'cache statistics',
+        name: 'Cache statistics',
         async run() {
-            stat.log();
-            stat.clear();
+            stat?.log();
+            stat?.clear();
         }
     });
 }

package/dist/cache/purge-task.js

@@ -8,7 +8,7 @@ const config_1 = require("./config");
  */
 class PurgeTask {
     valueMap;
-    name = 'cache purge';
+    name = 'Cache purge';
     constructor(valueMap) {
         this.valueMap = valueMap;
     }
@@ -22,12 +22,7 @@ class PurgeTask {
             }
         }
         if (removeCount > 0) {
-            if (removeCount > 1) {
-                (0, log_1.getLogger)().info(`A total of ${removeCount} expired cache records have been cleared.`);
-            }
-            else {
-                (0, log_1.getLogger)().info(`A total of ${removeCount} expired cache record has been cleared.`);
-            }
+            (0, log_1.getLogger)().info(`A total of ${removeCount} expired cache ${removeCount > 1 ? 'records' : 'record'} have been cleared.`);
         }
         // 如果过期的都清理掉，但是元素总数仍然超出，则删除多余元素，删除是从头开始删除的
         // 看上去是按put顺序清理最早的，实际上随机的，重复 set 相同的 key，key 的位置是不会变的，不保证 key 的顺序
@@ -44,12 +39,7 @@ class PurgeTask {
                     break;
                 }
             }
-            if (evictedCount > 1) {
-                (0, log_1.getLogger)().info(`A total of ${evictedCount} cache records have been evicted.`);
-            }
-            else {
-                (0, log_1.getLogger)().info(`A total of ${evictedCount} cache record has been evicted.`);
-            }
+            (0, log_1.getLogger)().info(`A total of ${evictedCount} cache ${evictedCount > 1 ? 'records' : 'record'} have been evicted.`);
         }
     }
 }

package/dist/log/config.js

@@ -2,27 +2,28 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.config = void 0;
 const path_1 = require("path");
+const config_1 = require("../config");
+const validation_1 = require("../validation");
 const level_1 = require("./level");
-const dotenv_1 = require("dotenv");
-(0, dotenv_1.config)();
-/**
- * 默认配置信息.
- */
-const config = {
-    file: process.env.LOG_FILE === 'true',
-    fileDir: process.env.LOG_FILE_DIR || 'logs',
+const envConfig = (0, config_1.registerConfig)({
+    file: false,
+    fileDir: 'logs',
     fileMaxDays: 30,
-    level: (0, level_1.parseLogLevel)(process.env.LOG_LEVEL || 'info')
-};
-exports.config = config;
+    level: 'INFO'
+}, 'LOG', {
+    file: [(0, validation_1.notNull)()],
+    fileDir: [(0, validation_1.notBlank)()],
+    fileMaxDays: [(0, validation_1.min)(1)],
+    level: [(0, validation_1.notBlank)()]
+});
+let { fileDir, level } = envConfig;
 // 目录处理
-if (!(0, path_1.isAbsolute)(config.fileDir)) {
-    config.fileDir = (0, path_1.resolve)(process.cwd(), config.fileDir);
-}
-// 天数
-if (process.env.LOG_FILE_MAX_DAYS) {
-    const days = parseInt(process.env.LOG_FILE_MAX_DAYS);
-    if (!isNaN(days)) {
-        config.fileMaxDays = days;
-    }
+if (!(0, path_1.isAbsolute)(fileDir)) {
+    fileDir = (0, path_1.resolve)(process.cwd(), fileDir);
 }
+exports.config = Object.freeze({
+    file: envConfig.file,
+    fileDir,
+    fileMaxDays: envConfig.fileMaxDays,
+    level: (0, level_1.parseLogLevel)(level)
+});

package/dist/log/file.js

@@ -53,24 +53,24 @@ if (config_1.config.file) {
      * 清理任务.
      */
     (0, task_1.scheduleDailyTask)(3, 0, {
-        name: '日志文件清理',
+        name: 'Log files clear',
         async run() {
             const files = await (0, promises_1.readdir)(config_1.config.fileDir);
             const now = new Date().getTime();
             for (const file of files) {
                 const dotIdx = file.indexOf('.');
                 if (dotIdx === -1) {
-                    console.warn(`无法处理日志文件 ${file}`);
+                    console.warn(`Unable to process the log file: ${file}`);
                     return;
                 }
                 const dateStr = file.substring(0, dotIdx);
                 const timestamp = Date.parse(dateStr);
                 if (isNaN(timestamp)) {
-                    console.warn(`无法处理日志文件 ${file}`);
+                    console.warn(`Unable to process the log file: ${file}`);
                     return;
                 }
                 if (timestamp + config_1.config.fileMaxDays * 24 * 3600 * 1000 < now) {
-                    console.warn(`清理掉日志文件： ${file}`);
+                    console.warn(`Remove log file： ${file}`);
                     await (0, promises_1.rm)((0, path_1.resolve)(config_1.config.fileDir, file));
                 }
             }

package/dist/log/index.js

@@ -5,13 +5,9 @@ const tslib_1 = require("tslib");
 const os_1 = require("os");
 const config_1 = require("./config");
 const date_1 = require("./date");
+const file_1 = require("./file");
 const level_1 = require("./level");
 const store_1 = require("./store");
-const file_1 = require("./file");
-/**
- * 日志级别的值
- */
-const LOG_LEVEL_VAL = level_1.LogLevelVals[config_1.config.level];
 /**
  * 文件存储
  */
@@ -25,31 +21,31 @@ if (config_1.config.file) {
  * @param error
  */
 function log(level, message, error) {
-    const levelVal = level_1.LogLevelVals[level];
-    if (levelVal >= LOG_LEVEL_VAL) {
-        const date = new Date();
-        // 控制台输出日志
-        let msg = `[${(0, date_1.formatDateTime)(date)}][${level}]${message}`;
-        console.log(msg);
+    if (level < config_1.config.level) {
+        return;
+    }
+    const date = new Date();
+    // 控制台输出日志
+    let msg = `[${(0, date_1.formatDateTime)(date)}][${level_1.LogLevel[level]}]${message}`;
+    console.log(msg);
+    if (error) {
+        console.log(error);
+    }
+    // 存储中输出日志
+    const store = (0, store_1.getLogStore)();
+    if (store) {
         if (error) {
-            console.log(error);
-        }
-        // 存储中输出日志
-        const store = (0, store_1.getLogStore)();
-        if (store) {
-            if (error) {
-                if (error.stack) {
-                    msg += os_1.EOL + error.stack;
-                }
-                else if (error.message) {
-                    msg += os_1.EOL + error.message;
-                }
-                else {
-                    msg += os_1.EOL + error;
-                }
+            if (error.stack) {
+                msg += os_1.EOL + error.stack;
+            }
+            else if (error.message) {
+                msg += os_1.EOL + error.message;
+            }
+            else {
+                msg += os_1.EOL + error;
             }
-            store(msg);
         }
+        store(msg);
     }
 }
 const logger = Object.freeze({
@@ -60,7 +56,7 @@ const logger = Object.freeze({
         log(level_1.LogLevel.DEBUG, message);
     },
     isDebugEnabled() {
-        return level_1.LogLevelVals[level_1.LogLevel.DEBUG] >= LOG_LEVEL_VAL;
+        return level_1.LogLevel.DEBUG >= config_1.config.level;
     },
     /**
      * info 日志
@@ -70,7 +66,7 @@ const logger = Object.freeze({
         log(level_1.LogLevel.INFO, message);
     },
     isInfoEnabled() {
-        return level_1.LogLevelVals[level_1.LogLevel.INFO] >= LOG_LEVEL_VAL;
+        return level_1.LogLevel.INFO >= config_1.config.level;
     },
     /**
      * 警告日志
@@ -81,7 +77,7 @@ const logger = Object.freeze({
         log(level_1.LogLevel.WARN, message, error);
     },
     isWarnEnabled() {
-        return level_1.LogLevelVals[level_1.LogLevel.WARN] >= LOG_LEVEL_VAL;
+        return level_1.LogLevel.WARN >= config_1.config.level;
     },
     /**
      * 错误日志
@@ -92,7 +88,7 @@ const logger = Object.freeze({
         log(level_1.LogLevel.ERROR, message, error);
     },
     isErrorEnabled() {
-        return level_1.LogLevelVals[level_1.LogLevel.ERROR] >= LOG_LEVEL_VAL;
+        return level_1.LogLevel.ERROR >= config_1.config.level;
     }
 });
 /**

package/dist/log/level.js

@@ -1,22 +1,16 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.parseLogLevel = exports.LogLevelVals = exports.LogLevel = void 0;
+exports.parseLogLevel = exports.LogLevel = void 0;
 /**
  * 日志级别.
  */
 var LogLevel;
 (function (LogLevel) {
-    LogLevel["DEBUG"] = "DEBUG";
-    LogLevel["INFO"] = "INFO";
-    LogLevel["WARN"] = "WARN";
-    LogLevel["ERROR"] = "ERROR";
+    LogLevel[LogLevel["DEBUG"] = 1] = "DEBUG";
+    LogLevel[LogLevel["INFO"] = 2] = "INFO";
+    LogLevel[LogLevel["WARN"] = 3] = "WARN";
+    LogLevel[LogLevel["ERROR"] = 4] = "ERROR";
 })(LogLevel = exports.LogLevel || (exports.LogLevel = {}));
-exports.LogLevelVals = Object.freeze({
-    [LogLevel.DEBUG]: 1,
-    [LogLevel.INFO]: 2,
-    [LogLevel.WARN]: 3,
-    [LogLevel.ERROR]: 4
-});
 /**
  * 解析日志级别
  * @param level
@@ -33,7 +27,7 @@ function parseLogLevel(level) {
         case 'ERROR':
             return LogLevel.ERROR;
         default:
-            throw new Error(`无法解析日志级别：${level}`);
+            throw new Error(`Unknown log level ：${level}`);
     }
 }
 exports.parseLogLevel = parseLogLevel;

package/dist/mvc/index.js

@@ -278,7 +278,12 @@ async function startWebServer(opts) {
     });
     console.log('App running at: ');
     getIpv4List().forEach(ip => {
-        console.log(`http://${ip}:${config_1.config.port}`);
+        if (config_1.config.port === 80) {
+            console.log(`http://${ip}`);
+        }
+        else {
+            console.log(`http://${ip}:${config_1.config.port}`);
+        }
     });
     process.on('beforeExit', () => {
         if (server.listening) {

package/documentation/zh-cn/mvc.md

@@ -118,15 +118,99 @@ await startWebServer({
           exchange.respondErrMsg(e.errMsg, 400)
           return
         }
-        getLogger().error(`接口异常 ${url}`, e)
-        // 调用 exchange 上的工具方法，快速完成一个响应
-        exchange.respondErrMsg('服务器内部错误', 500)
+        // 对于不能处理的异常，可直接抛出
+        // 框架最终会响应 500 状态码，并记录错误信息到日志里以便于线上排查
+        throw e
       }
     }
   ]
 })
 ```
 
+### 异常处理
+
+对于业务处理失败的情况下，推荐的做法是抛出异常来中止处理流程，然后由拦截器来统一处理进行响应。
+但是这并非是强制的，框架也没有预置任何相关的类型或函数，需要自己根据实际情况来扩展，下面是一个例子。
+
+```ts
+/**
+ * 自定义业务异常.
+ */
+export class BusinessException {
+  constructor(
+    /**
+     * 提示信息.
+     */
+    readonly message: string,
+    /**
+     * 自定义状态码，默认 400
+     */
+    readonly status?: number
+  ) {}
+}
+
+/**
+ * 全局异常拦截器，对一些特定的异常做处理，给予合适的响应信息.
+ * @param exchange
+ * @param next
+ */
+export async function globalErrorInterceptor(
+  exchange: ServerExchange,
+  next: () => Promise<void>
+): Promise<void> {
+  try {
+    await next()
+  } catch (e) {
+    // 处理自定义业务异常
+    if (e instanceof BusinessException) {
+      const status = typeof e.status === 'number' ? e.status : 400
+      const message = e.message || ''
+      exchange.respondErrMsg(message, status)
+      return
+    }
+    // 处理校验异常
+    if (e instanceof ValidationException) {
+      exchange.respondErrMsg(e.errMsg, 400)
+      return
+    }
+    // 其它异常不需要处理的直接抛出，框架默认会响应 500 状态码
+    throw e
+  }
+}
+```
+
+实际开发中可根据情况设置多个业务异常，分别响应不同的 JSON 格式，
+respondErrMsg 方法响应的 json 格式是框架预设的，可通过 respondJson 方法响应自定义的格式。
+
+将错误处理拦截器设置为第一个拦截器，在使用请求处理过程中使用自定义异常。
+
+```ts
+// 启动服务
+await startWebServer({
+  interceptors: [
+    // 将错误处理拦截器设置为第一个拦截器
+    globalErrorInterceptor,
+    // 接下来是其它的拦截器
+    authInterceptor
+  ],
+  // 路由
+  routers: {
+    '/order/cancel': createJsonHandler<{ id: string }>({
+      validation: { id: [notBlank()] },
+      async handle(body, exchange) {
+        const order = await findOrderById(body.id)
+        if (!order) {
+          // 使用自定义业务异常来中断处理流程
+          throw new BusinessException('找不到订单')
+        }
+        // 继续处理 ...
+      }
+    })
+    // 省略路由配置代码
+  }
+})
+```
+
 ### 针对不同的方法进行处理
 
 组件提供了 restful 函数，可以在配置路由时按请求方法进行分发。
@@ -159,11 +243,12 @@ await startWebServer({
 请求和响应都是 json 格式，响应和请求都可以为空。请求为空可以填入类型 {} 来表示空对象，响应为空可以填入类型 void 。
 
 ```ts
-// 申请请求体　json 格式和响应的格式
+// json 格式请求正文定义
 interface Form {
   name: string
   age: number
 }
+// json 格式响应信息定义
 interface Resp {
   id: string
 }
@@ -190,7 +275,71 @@ export const userCreateHandler = createJsonHandler<Form, Resp>({
 
 校验时会自动根据消息头 `accept-language` 切换校验器的语言，对于没有自定义错误信息的校验使用切换后的语言给予默认的提示。
 
-### 上传文件处理
+### 二进制（Binary）上传
+
+二制进上传也就是将文件以二进制的形式写入请求正文，请求正文仅存储文件内容没有别的信息，
+请求的格式（Content-type）是 application/octet-stream 。
+
+这种形式带来的好处就是简单，性能更好，因为服务器端拿到请求正文就是文件，不像 multipart/form-data 格式过需要解析内容来获取信息。
+但是由于请求正文仅存储了文件，其它的业务参数只能通过查询字符串（Query String）带入。
+
+框架提供了 createUploadHandler 函数带创建处理二进制格式请求的路由处理器，响应 JSON 格式，下面是示例。
+
+```ts
+interface Resp {
+  /**
+   * 新头像访问地址
+   */
+  url: string
+}
+
+/**
+ * 演示场景: 上传头像
+ */
+export const uploadAvatar = createUploadHandler<Resp>({
+  async handle(body, exchange) {
+    // 通过 Query String 获取用户id参数
+    const userId = exchange.query.getStr('userId') as string
+    // 校验参数
+    validate(
+      { userId },
+      {
+        userId: [notBlank(), maxLength(64)]
+      }
+    )
+    // 判定文件大小
+    if (body.byteLength > 2 * 1024 * 1024) {
+      // BusinessException 是自定义的业务异常，抛出后由拦截器统一处理
+      throw new BusinessException('文件大小不得超过 2MB')
+    }
+    const user = await getMysqlManager().findById(tableUser, userId)
+    if (!user) {
+      throw new BusinessException('找不到用户')
+    }
+    // 模拟上传到文件服务器的场景，oss 是对象存储服务 sdk
+    const key = `users/${userId}/avatar`
+    await oss.putObject(key, body)
+    await getMysqlManager().partialUpdate(tableUser, { id: userId, avatar_key: key })
+    return { url: oss.getUrl(key) }
+  }
+})
+```
+
+如果需要更高的自由度，比如不想返回 json 格式，定义普通的路由处理器即可，通过 exchage 上的 bodyBuffer 方法即可获取请求正文内容。
+
+```ts
+export const uploadAvatar: RouterHandler = async exchange => {
+  // 读取文件
+  const file = await exchange.bodyBuffer()
+  // 获取 Query String 上的参数
+  const query = exchange.parseQueryString()
+  const userId = query.getStr('userId')
+
+  // 校验参数和存储文件等流程省略...
+}
+```
+
+### multipart/form-data 格式上传文件处理
 
 组件目前尚未实现对 multipart/form-data 类型请求的处理，如有需要可通一些第三方库来解析文件上传的请求内容。
 
@@ -250,7 +399,6 @@ await startWebServer({
             add({ tag: 'h1', children: ['个人中心'] })
             // 在 user 有值和无值的情况下分别渲染不同的元素
             if (user) {
-              1
               add({ tag: 'p', children: [`用户名：${user.account}`] })
             } else {
               add({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wok-server",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "packageManager": "pnpm@8.9.0",
   "description": "一个基于 NodeJs 和 TypeScript 的后端框架，轻量级、克制、简洁。A lightweight, restrained, and concise backend framework based on Node.js and TypeScript.",
   "scripts": {

package/types/cache/cache.d.ts

@@ -14,12 +14,12 @@ export interface CacheContent {
 }
 export declare class Cache {
     private readonly valueMap;
-    private readonly stat;
+    private readonly stat?;
     /**
      * promise 表，作用是处理异步并发问题，如果有相同的 key 同时请求，保证异步的 provider 只执行一次
      */
     private promiseMap;
-    constructor(valueMap: Map<string, CacheContent>, stat: CacheStat);
+    constructor(valueMap: Map<string, CacheContent>, stat?: CacheStat | undefined);
     /**
      * 放入缓存
      * @param key

package/types/cache/purge-task.d.ts

@@ -5,7 +5,7 @@ import { CacheContent } from './cache';
  */
 export declare class PurgeTask implements Task {
     private readonly valueMap;
-    readonly name = "cache purge";
+    readonly name = "Cache purge";
     constructor(valueMap: Map<string, CacheContent>);
     run(): Promise<void>;
 }

package/types/log/config.d.ts

@@ -2,7 +2,7 @@ import { LogLevel } from './level';
 /**
  * 日志配置的定义
  */
-export interface LogConfig {
+interface EnvConfig {
     /**
      * 是否输出到文件，如果为 true ，则会在根目录下生成 logs 目录存放日志文件.
      */
@@ -18,10 +18,10 @@ export interface LogConfig {
     /**
      * 要输出的日志级别.
      */
-    level: LogLevel;
+    level: string;
 }
-/**
- * 默认配置信息.
- */
-declare const config: LogConfig;
-export { config };
+export type LogConfig = Omit<EnvConfig, 'level'> & {
+    level: LogLevel;
+};
+export declare const config: LogConfig;
+export {};

package/types/log/level.d.ts

@@ -2,12 +2,11 @@
  * 日志级别.
  */
 export declare enum LogLevel {
-    DEBUG = "DEBUG",
-    INFO = "INFO",
-    WARN = "WARN",
-    ERROR = "ERROR"
+    DEBUG = 1,
+    INFO = 2,
+    WARN = 3,
+    ERROR = 4
 }
-export declare const LogLevelVals: Record<LogLevel, number>;
 /**
  * 解析日志级别
  * @param level