wok-server 0.3.4 → 0.4.1

package/dist/index.js

@@ -11,3 +11,4 @@ tslib_1.__exportStar(require("./mvc"), exports);
 tslib_1.__exportStar(require("./mysql"), exports);
 tslib_1.__exportStar(require("./http-client"), exports);
 tslib_1.__exportStar(require("./mongodb"), exports);
+tslib_1.__exportStar(require("./lock"), exports);

package/dist/lock/index.js

@@ -0,0 +1,115 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getLockManager = void 0;
+const crypto_1 = require("crypto");
+/**
+ * 锁管理器，主要用于将不确定的顺序且有冲突的异步操作顺序执行，
+ * 防止异步流程庞大穿插执行造成的数据混乱和错误，常见于请求的处理。
+ */
+class ServerLockManager {
+    /**
+     * 存储锁信息的表，值是一个随机值，用于验证锁是否为当前程序所拥有
+     */
+    lockMap = new Map();
+    constructor() {
+        // 定期清理，将过期的信息移除，防止内存泄漏
+        setTimeout(() => {
+            const keysToBeDeleted = [];
+            const now = Date.now();
+            for (const entry of this.lockMap.entries()) {
+                const [key, info] = entry;
+                if (info.expiresAt < now) {
+                    keysToBeDeleted.push(key);
+                }
+            }
+            if (keysToBeDeleted.length) {
+                for (const key of keysToBeDeleted) {
+                    this.lockMap.delete(key);
+                }
+            }
+        }, 10000);
+    }
+    /**
+     * 尝试竞争锁，如果成功获取到锁，则执行 run 函数
+     * @param opts
+     * @returns 是否获取到锁
+     */
+    async tryLock(opts) {
+        const value = (0, crypto_1.randomUUID)().toString();
+        const expiresInSeconds = typeof opts.expiresInSeconds === 'number' && opts.expiresInSeconds > 0
+            ? opts.expiresInSeconds
+            : 60;
+        const expiresAt = Date.now() + expiresInSeconds * 1000;
+        const waitSeconds = typeof opts.waitSeconds === 'number' && opts.waitSeconds > 0 ? opts.waitSeconds : 0;
+        const res = await this.waitLock({
+            key: opts.key,
+            value,
+            expiresAt,
+            waitSeconds
+        });
+        if (!res) {
+            return false;
+        }
+        try {
+            await opts.run();
+        }
+        finally {
+            // 解锁
+            const info = this.lockMap.get(opts.key);
+            if (info && info.value === value) {
+                this.lockMap.delete(opts.key);
+            }
+        }
+        return true;
+    }
+    /**
+     * 等待锁
+     * @param opts
+     */
+    async waitLock(opts) {
+        let milliseconds = 0;
+        while (true) {
+            const info = this.lockMap.get(opts.key);
+            // 锁不存在或已经过期
+            if (!info || info.expiresAt < Date.now()) {
+                // 成功获取到锁
+                this.lockMap.set(opts.key, {
+                    value: opts.value,
+                    expiresAt: opts.expiresAt
+                });
+                return true;
+            }
+            if (info.value === opts.value) {
+                return true;
+            }
+            if (milliseconds >= opts.waitSeconds * 1000) {
+                break;
+            }
+            milliseconds = milliseconds + 100;
+            await this.sleep();
+        }
+        return false;
+    }
+    /**
+     * 沉睡100ms
+     * @returns
+     */
+    sleep() {
+        return new Promise((resolve, reject) => {
+            setTimeout(resolve, 100);
+        });
+    }
+}
+let lockManager;
+/**
+ * 获取锁管理器。锁管理器提供一个简单的异步并发控制，用于将不确定的顺序的有冲突的异步操作顺序执行，
+ * 防止异步流程庞大穿插执行造成的数据混乱和错误，常见于请求的处理。
+ * @returns
+ */
+function getLockManager() {
+    if (!lockManager) {
+        lockManager = new ServerLockManager();
+    }
+    return lockManager;
+}
+exports.getLockManager = getLockManager;

package/dist/mvc/static/static-handler.js

@@ -208,6 +208,9 @@ class StaticHandler {
         return true;
     }
     async endRespWithBuffer(response, buffer) {
+        if (response.writableEnded || response.destroyed) {
+            return;
+        }
         await new Promise((resolve, reject) => {
             response.write(buffer, err => {
                 if (err) {

package/documentation/zh-cn/index.md

@@ -21,6 +21,7 @@ Nodejs 后端开发框架，简洁，易上手，功能够用。使用 Typescrip
 - [mongodb](./mongodb.md)
 - [MVC](./mvc.md)
 - [任务](./task.md)
+- [锁](./lock.md)
 - [Http 客户端](./http-client.md)
 - [单元测试](./test.md)
 - [工程化](./engineering.md)

package/documentation/zh-cn/lock.md

@@ -0,0 +1,53 @@
+# 锁
+
+锁的作用是协调多个异步操作流程，使这些流程可以按顺序执行，在并发请求时会很有用。
+一个请求的处理过程中可能有很多个异步操作，并发情况下，不同请求中的操作就会穿插执行，
+如果有修改操作，有可能会造成错误，比如减库存和抽奖等。
+
+## 使用
+
+使用 getLockManager 函数可以获取锁管理对象，调用 tryLock 方法来尝试上锁并在成功获取锁后执行逻辑。
+
+简单的场景示例代码：
+
+```ts
+import { getLockManager } from 'wok-server'
+
+interface Form {
+  id: string
+  quantity: number
+}
+// 创建 json 主动处理器，模拟减库存请求
+createJsonHandler<Form>({
+  validation: {
+    id: [notBlank()],
+    quantity: [notNull(), min(1), max(10)]
+  },
+  async handle(body, exchange) {
+    const lock = getLockManager()
+    const res = lock.tryLock({
+      // 锁的标识，标识相同产生竞争关系
+      key: `reduce-quantity-${body.id}`,
+      // 最多等待两秒，两秒内如果获取不到锁 tryLock 函数就返回 false
+      waitSeconds: 2,
+      // 锁的过期时间，这里设置最多只能拥有锁 600 秒，防止死锁
+      // 如果超时就可以被其它的程序获取到锁，不管 run 函数执行完没有
+      expiresInSeconds: 600,
+      // 执行函数，获取锁成功就会被执行
+      // 在请求并发的情况下，没有获取锁的请求处理则会等待，然后排队执行
+      async run() {
+        const product = await findProductById(body.id)
+        if (product.quantity < body.quantity) {
+          throw new BusinessException('库存不足')
+        }
+        await reduceQuantity(body.id,body.quantity)
+      }
+    })
+    // tryLock 返回的结果是 boolean 类型，表示此次是否成功获取到锁
+    // 没有获取到锁，给业务提示
+    if (!res) {
+      throw new BusinessException('系统繁忙，请稍后重试')
+    }
+  }
+})
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wok-server",
-  "version": "0.3.4",
+  "version": "0.4.1",
   "packageManager": "pnpm@8.9.0",
   "description": "一个基于 NodeJs 和 TypeScript 的后端框架，轻量级、克制、简洁。A lightweight, restrained, and concise backend framework based on Node.js and TypeScript.",
   "scripts": {
@@ -50,5 +50,8 @@
     "mysql2": "^3.11.0"
   },
   "main": "dist/index.js",
-  "types": "types/index.d.ts"
+  "types": "types/index.d.ts",
+  "engines": {
+    "node": ">=16.0.0"
+  }
 }

package/types/index.d.ts

@@ -8,3 +8,4 @@ export * from './mvc';
 export * from './mysql';
 export * from './http-client';
 export * from './mongodb';
+export * from './lock';

package/types/lock/index.d.ts

@@ -0,0 +1,64 @@
+export interface LockInfo {
+    /**
+     * 一个随机值，用于验证锁是否为当前程序所拥有
+     */
+    value: string;
+    /**
+     * 锁过期的时间
+     */
+    expiresAt: number;
+}
+/**
+ * 锁管理器，主要用于将不确定的顺序且有冲突的异步操作顺序执行，
+ * 防止异步流程庞大穿插执行造成的数据混乱和错误，常见于请求的处理。
+ */
+declare class ServerLockManager {
+    /**
+     * 存储锁信息的表，值是一个随机值，用于验证锁是否为当前程序所拥有
+     */
+    private lockMap;
+    constructor();
+    /**
+     * 尝试竞争锁，如果成功获取到锁，则执行 run 函数
+     * @param opts
+     * @returns 是否获取到锁
+     */
+    tryLock(opts: {
+        /**
+         * 竞争锁的标识，相同的 key 会处于竞争关系，从而按顺序执行
+         */
+        key: string;
+        /**
+         * 等待秒数，如果没有获取锁，要等待的时间，单位秒。
+         * 不设置的情况下则不会等待，获取不到锁就立即返回。
+         */
+        waitSeconds?: number;
+        /**
+         * 运行函数，成功获取锁就会执行
+         * @returns
+         */
+        run: () => Promise<void>;
+        /**
+         * 过期时间，单位秒。目的是防止一个程序长期占用锁，导致其它程序获取不到锁一直不能被执行
+         * 导致的死锁问题。锁一旦过期，当前程序就不再拥有锁，其它程序就可以获取到锁。默认 60 秒。
+         */
+        expiresInSeconds?: number;
+    }): Promise<boolean>;
+    /**
+     * 等待锁
+     * @param opts
+     */
+    private waitLock;
+    /**
+     * 沉睡100ms
+     * @returns
+     */
+    private sleep;
+}
+/**
+ * 获取锁管理器。锁管理器提供一个简单的异步并发控制，用于将不确定的顺序的有冲突的异步操作顺序执行，
+ * 防止异步流程庞大穿插执行造成的数据混乱和错误，常见于请求的处理。
+ * @returns
+ */
+export declare function getLockManager(): ServerLockManager;
+export {};