wok-server 0.1.4 → 0.1.6

package/dist/mvc/handler/json.js

@@ -27,7 +27,7 @@ function createJsonHandler(opts) {
                 (0, validation_1.validate)(body, opts.validation);
             }
         }
-        const res = await opts.handle(body, exchange);
+        const res = await opts.handle(body, { request: exchange.request });
         if (!res) {
             exchange.respond({ statusCode: 200 });
             return;

package/dist/mvc/handler/upload.js

@@ -17,10 +17,8 @@ function createUploadHandler(opts) {
             return;
         }
         const body = await exchange.bodyBuffer();
-        const { url, headers } = exchange.request;
         const res = await opts.handle(body, {
-            url: url || '',
-            headers,
+            request: exchange.request,
             query: exchange.parseQueryString()
         });
         if (!res) {

package/dist/mvc/render/file.js

@@ -5,6 +5,7 @@ const fs_1 = require("fs");
 const promises_1 = require("fs/promises");
 const json_1 = require("./json");
 const path_1 = require("path");
+const zlib_1 = require("zlib");
 /**
  * 常用的 content-type 对照表
  */
@@ -143,7 +144,7 @@ async function renderFile(request, response, filePath, download = false) {
     const rangeHeader = request.headers['range'];
     if (!rangeHeader) {
         response.setHeader('Last-Modified', statRes.mtime.toUTCString());
-        return streamFile(filePath, response);
+        return streamFile(filePath, request, response);
     }
     // 解析，range 示例：bytes=200-1000, 2000-6576, 19000-
     // 多段的情况，暂时不做支持，非常麻烦，段数多还可能会有效率问题
@@ -151,11 +152,11 @@ async function renderFile(request, response, filePath, download = false) {
     const ranges = rangeHeader.split(',');
     let range = ranges.length ? ranges[0] : undefined;
     if (!range) {
-        return streamFile(filePath, response);
+        return streamFile(filePath, request, response);
     }
     range = range.trim();
     if (!range.startsWith('bytes=')) {
-        return streamFile(filePath, response);
+        return streamFile(filePath, request, response);
     }
     range = range.substring(6);
     const strs = range.split('-');
@@ -178,10 +179,10 @@ async function renderFile(request, response, filePath, download = false) {
     // 注：Range 和 Content-Range 还有 createReadStream 中的字节范围，都是前后全包含的
     // Content-Range: bytes 42-1233/1234
     response.setHeader('Content-Range', `bytes ${start}-${end}/${statRes.size}`);
-    return streamFile(filePath, response, { start, end });
+    return streamFile(filePath, request, response, { start, end });
 }
 exports.renderFile = renderFile;
-function streamFile(filePath, response, opts) {
+function streamFile(filePath, request, response, opts) {
     return new Promise((res, rej) => {
         if (opts && typeof opts.start === 'number') {
             // 部分返回 206
@@ -191,6 +192,22 @@ function streamFile(filePath, response, opts) {
             // 全部返回 200
             response.statusCode = 200;
         }
+        // 支持 gzip
+        const acceptEncoding = request.headers['accept-encoding'];
+        if (acceptEncoding) {
+            // Accept-Encoding: br;q=1.0, gzip;q=0.8, *;q=0.1
+            const acceptEncodings = acceptEncoding
+                .trim()
+                .split(',')
+                .map(item => item.trim())
+                .map(item => item.split(';')[0]);
+            if (acceptEncodings.includes('gzip') || acceptEncodings.includes('*')) {
+                response.setHeader('Content-Encoding', 'gzip');
+                (0, fs_1.createReadStream)(filePath, opts).pipe((0, zlib_1.createGzip)()).pipe(response);
+                response.once('finish', res).once('error', rej);
+                return;
+            }
+        }
         (0, fs_1.createReadStream)(filePath, opts).pipe(response);
         response.once('finish', res).once('error', rej);
     });

package/documentation/zh-cn/engineering.md

@@ -33,6 +33,7 @@
   │   │   ├──create-tag.ts 创建标签接口（/tag/create）
   │   │   ├──delete-tag.ts 删除标签接口（/tag/delete）
   │   │   └──index.ts 包入口文件，导出需要导出的模块
+  │   ├──exception.ts 全局异常
   │   └──main.ts 入口文件，启动服务，配置路由
   ├──.env 开发环境变量配置
   ├──package.json
@@ -42,12 +43,64 @@
 
 ## 文件说明
 
+exception.ts 这个文件中包含了自定义的业务异常，以及异常的处理拦截器。
+
+```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.propertyPath}：${e.errMsg}`, 400)
+      return
+    }
+    // 其它异常直接抛出，框架默认会响应 500 状态码
+    throw e
+  }
+}
+```
+
+使用自定义业务异常，在业务无法进行的情况下抛出异常中止请求处理，事务的处理过程中遇到异常也会进行回滚，这是推荐的做法。
+
 main.ts 示例：
 
 ```ts
 import { createAuth, authInterceptor, ccuTask } from './auth'
 import { createUser, updateUser, deleteUser } from './user'
 import { createTag, deleteTag } from './tag'
+import { globalErrorInterceptor } from './exception'
 
 async function main() {
   // 改写 date 原型，将日期序列化为数字
@@ -77,7 +130,7 @@ async function main() {
       '/tag/delete': deleteTag
     },
     // 拦截器
-    interceptors: [authInterceptor]
+    interceptors: [globalErrorInterceptor, authInterceptor]
   })
   // 周期性任务
   // 每60秒统计一次在线人数
@@ -194,9 +247,9 @@ export const createUser = createJsonHandler<Form, Resp>({
   async handle(body, exchange) {
     const manager = getMysqlManager()
     if (await manager.existsBy(tableUser, { code: body.code })) {
-      // 错误信息的响应也可以自定义异常，然后通过拦截器来统一处理，这里仅仅是简单的示例
-      exchage.respondErrMsg('编号已经存在')
-      return
+      // 抛出异常，中止处理
+      // 异常最终会由拦截器来处理并响应
+      throw new BusinessException('编号已经存在')
     }
     const newUser = await manager.insert(tableUser, body)
     return { id: newUser.id }

package/package.json

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

package/types/mvc/handler/json.d.ts

@@ -1,6 +1,13 @@
+/// <reference types="node" />
+import { IncomingMessage } from 'http';
 import { ValidationOpts } from '../../validation';
-import { ServerExchange } from '../exchange';
 import { RouterHandler } from '../router';
+export interface JsonHandlerExchange {
+    /**
+     * 请求信息
+     */
+    request: IncomingMessage;
+}
 /**
  * 创建 json 处理器..
  * @param <REQ> 表示请求的 json 数据格式类型
@@ -19,5 +26,5 @@ export declare function createJsonHandler<REQ, RES = void>(opts: {
      * @param exchange 请求传输对象，用于获取请求的基本信息
      * @returns
      */
-    handle: (body: REQ, exchange: ServerExchange) => Promise<RES>;
+    handle: (body: REQ, exchange: JsonHandlerExchange) => Promise<RES>;
 }): RouterHandler;

package/types/mvc/handler/upload.d.ts

@@ -1,20 +1,16 @@
 /// <reference types="node" />
 /// <reference types="node" />
-import { IncomingHttpHeaders } from 'http';
+import { IncomingMessage } from 'http';
 import { QueryString } from '../query';
 import { RouterHandler } from '../router';
 /**
  * 上传请求传输对象.
  */
-export interface UploadRouterExchange {
+export interface UploadHandlerExchange {
     /**
-     * 请求地址
+     * 请求信息
      */
-    url: string;
-    /**
-     * 请求头
-     */
-    headers: IncomingHttpHeaders;
+    request: IncomingMessage;
     /**
      * querystring 解析结果
      */
@@ -36,5 +32,5 @@ export declare function createUploadHandler<RES = void>(opts: {
      * @param exchange 请求传输对象，用于获取请求的基本信息
      * @returns
      */
-    handle: (body: Buffer, exchange: UploadRouterExchange) => Promise<RES>;
+    handle: (body: Buffer, exchange: UploadHandlerExchange) => Promise<RES>;
 }): RouterHandler;