typespeed 2.4.10 → 2.5.0

package/src/typespeed.d.ts

@@ -5,68 +5,74 @@ import "reflect-metadata";
 
 /**设置路由中间件 */
 declare function setRouter(app: express.Application): void;
-/**上传文件装饰器，装饰页面具备解析上传文件的能力 */
-declare function upload(target: any, propertyKey: string): void;
+/**上传文件装饰器，装饰页面具备解析上传文件的能力（legacy 方法装饰器；2.5.x 起兼容标准 (value, context) 签名） */
+declare function upload(...args: any[]): any;
 /**
  * 页面支持 JWT 鉴权能力
  * @param jwtConfig jwt 配置
  */
-declare function jwt(jwtConfig: any): (target: any, propertyKey: string) => void;
+declare function jwt(jwtConfig: any): (...args: any[]) => any;
 /**
  * GET 请求装饰器
  * @param value 请求路径
  */
-declare const getMapping: (value: string) => (target: any, propertyKey: string) => void;
+declare const getMapping: (value: string) => (...args: any[]) => any;
 /**
  * POST 请求装饰器
  * @param value 请求路径
  */
-declare const postMapping: (value: string) => (target: any, propertyKey: string) => void;
+declare const postMapping: (value: string) => (...args: any[]) => any;
 /**
  * 请求装饰器，不区分请求类型
  * @param value 请求路径
  */
-declare const requestMapping: (value: string) => (target: any, propertyKey: string) => void;
+declare const requestMapping: (value: string) => (...args: any[]) => any;
 /**
  * INSERT 装饰器
  * 将方法作为 INSERT SQL 使用
  * @param sql INSERT SQL 语句
  */
-declare function insert(sql: string): (target: any, propertyKey: string, descriptor: PropertyDescriptor) => void;
+declare function insert(sql: string): (...args: any[]) => any;
 /**
  * UPDATE 装饰器
  * 将方法作为 UPDATE SQL 使用
  * @param sql UPDATE SQL 语句
  */
-declare function update(sql: string): (target: any, propertyKey: string, descriptor: PropertyDescriptor) => void;
+declare function update(sql: string): (...args: any[]) => any;
 /**
  * DELETE 装饰器
  * 将方法作为 DELETE SQL 使用
  * @param sql DELETE SQL 语句
  */
-declare function remove(sql: string): (target: any, propertyKey: string, descriptor: PropertyDescriptor) => void;
+declare function remove(sql: string): (...args: any[]) => any;
 /**
  * SELECT 装饰器
  * 将方法作为 SELECT SQL 使用
  * @param sql SELECT SQL 语句
  */
-declare function select(sql: string): (target: any, propertyKey: string, descriptor: PropertyDescriptor) => void;
+declare function select(sql: string): (...args: any[]) => any;
 /**
  * SELECT 结果类型装饰器，和 @select 配合使用
  * @param dataClass 结果类型
  */
-declare function resultType(dataClass: any): (target: any, propertyKey: string) => void;
+declare function resultType(dataClass: any): (...args: any[]) => any;
 /**
  * SQL 参数装饰器，标注 SQL 语句的绑定参数值，和 @select @insert @update @remove 配合使用
  * @param name 参数在 SQL 语句内的标记值
  */
 declare function param(name: string): (target: any, propertyKey: string | symbol, parameterIndex: number) => void;
+/**
+ * 方法级参数绑定装饰器（标准装饰器删除了参数装饰器后的替代，legacy 模式也可用）。
+ * database 场景映射 SQL 占位符 → 参数索引（值为 number）；route 场景映射参数名 → 请求来源（值为 string）。
+ * @param mapping 绑定声明，如 { name: 0, id: 1 } 或 { id: "reqParam", body: "reqBody" }
+ */
+declare function bind(mapping: Record<string, string | number>): (...args: any[]) => any;
 /**
  * SELECT 缓存装饰器，自动缓存 SELECT 查询结果，和 @select 配合使用
  * 当执行 @insert @update @remove 时，会自动清除缓存。
  * @param ttl 缓存时间，单位秒
  */
-declare function cache(ttl: number): (target: any, propertyKey: string) => void;
+declare function cache(ttl: number): (...args: any[]) => any;
 /**模型数据操作类 */
 declare class Model {
     /**分页数据 */
@@ -139,23 +145,21 @@ declare class Model {
  * 
  * 被装饰的类将作为应用程序入口，框架将启动该类的 main 方法
  */
-declare function app<T extends {
-    new(...args: any[]): {};
-}>(constructor: T): void;
+declare function app(...args: any[]): any;
 /**获取配置文件中的配置项 */
 declare function config(node: string): any;
-/**组件装饰器，被装饰的类可以通过 @autoware 取得实例 */
-declare function component(constructorFunction: any): void;
+/**组件装饰器，被装饰的类可以通过 @autoware 取得实例（legacy 类装饰器；2.5.x 起兼容标准 (value, context) 签名） */
+declare function component(...args: any[]): any;
 /**获取组件实例函数，返回结果同 @autoware */
 declare function getComponent(constructorFunction: any): any;
-/**提供对象装饰器，框架将使用 @bean 装饰的方法来获取对象实例 */
-declare function bean(target: any, propertyKey: string): void;
+/**提供对象装饰器，框架将使用 @bean 装饰的方法来获取对象实例（legacy 方法装饰器；2.5.x 起兼容标准签名） */
+declare function bean(...args: any[]): any;
 /**获取对象实例函数，返回结果由 @bean 装饰的方法提供 */
 declare function getBean(mappingClass: Function): any;
 /**配置装饰器，装饰类成员变量值，获取配置文件中的配置项 */
 declare function value(configPath: string): any;
 /**自动装配装饰器，无参数版本，被装饰的类成员变量将自动注入实例 */
-declare function autoware(target: any, propertyKey: string): void;
+declare function autoware(...args: any[]): any;
 /**自动装配装饰器，带参数版本，可输入参数作为实例初始化参数，被装饰的类成员变量将自动注入实例 */
 declare function resource(...args: any[]): any;
 /**日志函数，输出打印日志 */
@@ -165,11 +169,11 @@ declare function logx(message: any): void;
 /**错误日志函数，输出打印错误日志 */
 declare function error(message?: any, ...optionalParams: any[]): void;
 /**路由页面前置执行装饰器，参数指向路由页面方法，被装饰的方法将在路由页面之前执行 */
-declare function before(constructorFunction: any, methodName: string): (target: any, propertyKey: string) => void;
+declare function before(constructorFunction: any, methodName: string): (...args: any[]) => any;
 /**路由页面后置执行装饰器，参数指向路由页面方法，被装饰的方法将在路由页面之后执行 */
-declare function after(constructorFunction: any, methodName: string): (target: any, propertyKey: string) => void;
+declare function after(constructorFunction: any, methodName: string): (...args: any[]) => any;
 /**定时程序装饰器，参数支持 crontab 格式字符串，可根据参数定时执行被装饰的方法 */
-declare function schedule(cronTime: string | Date): (target: any, propertyKey: string) => void;
+declare function schedule(cronTime: string | Date): (...args: any[]) => any;
 /**RabbitMQ 监听装饰器，参数是监听的队列名称，当接受到消息时将执行被装饰方法 */
 declare function rabbitListener(queue: string): (target: any, propertyKey: string) => void;
 /**Redis 监听装饰器，参数是监听的队列名称，当接受到消息时将执行被装饰方法 */
@@ -396,4 +400,4 @@ declare class SocketIo {
 /**Socket IO 服务实现类 */
 declare const io: IoServer;
 
-export { ExpressServer, LogDefault, NodeCache, RabbitMQ, rabbitListener, redisSubscriber, ReadWriteDb, Redis, CacheFactory, DataSourceFactory, LogFactory, ServerFactory, AuthenticationFactory, next, reqBody, reqQuery, reqForm, reqParam, req, req as request, res, res as response, component, bean, resource, log, logx, app, before, after, value, error, config, autoware, getBean, getComponent, schedule, getMapping, postMapping, requestMapping, setRouter, upload, jwt, insert, update, remove, select, param, resultType, cache, Model, SocketIo, io };
+export { ExpressServer, LogDefault, NodeCache, RabbitMQ, rabbitListener, redisSubscriber, ReadWriteDb, Redis, CacheFactory, DataSourceFactory, LogFactory, ServerFactory, AuthenticationFactory, next, reqBody, reqQuery, reqForm, reqParam, req, req as request, res, res as response, component, bean, resource, log, logx, app, before, after, value, error, config, autoware, getBean, getComponent, schedule, getMapping, postMapping, requestMapping, setRouter, upload, jwt, insert, update, remove, select, param, bind, resultType, cache, Model, SocketIo, io };

package/src/typespeed.ts

@@ -2,6 +2,7 @@ import "reflect-metadata";
 import * as fs from "fs";
 import * as path from "path";
 import * as walkSync from "walk-sync";
+import { isStd, getStdArgs } from "./decorator-utils";
 
 let globalConfig = {};
 const corePath = __dirname;
@@ -18,7 +19,18 @@ if (fs.existsSync(configFile)) {
 globalConfig["MAIN_PATH"] = mainPath;
 globalConfig["CORE_PATH"] = corePath;
 
-function app<T extends { new(...args: any[]): {} }>(constructor: T) {
+function app(...args: any[]): any {
+    if (isStd(args)) {
+        const [, ctx] = getStdArgs(args);
+        ctx.addInitializer(function (this: any) {
+            startApp(this.constructor);
+        });
+        return;
+    }
+    startApp(args[0]);
+}
+
+function startApp(constructor: any) {
     const coreFiles = walkSync(corePath, { globs: ['**/*.ts'], ignore: ['**/*.d.ts', 'scaffold/**'] });
     const mainFiles = walkSync(mainPath, { globs: ['**/*.ts'] });
 
@@ -47,7 +59,23 @@ function config(node: string) {
 }
 
 function value(configPath: string): any {
-    return function (target: any, propertyKey: string) {
+    return function (...args: any[]): any {
+        if (isStd(args)) {
+            // 标准 field 装饰器：返回 initializer 注入配置值（标准模式下无 design:type）。
+            return (initialValue: any) => {
+                if (globalConfig === undefined) {
+                    return initialValue;
+                }
+                let pathNodes = configPath.split(".");
+                let nodeValue = globalConfig;
+                for (let i = 0; i < pathNodes.length; i++) {
+                    nodeValue = nodeValue[pathNodes[i]];
+                }
+                return nodeValue === undefined ? initialValue : nodeValue;
+            };
+        }
+        const target = args[0];
+        const propertyKey = args[1] as string;
         if (globalConfig === undefined) {
             Object.defineProperty(target, propertyKey, {
                 get: () => {
@@ -70,19 +98,21 @@ function value(configPath: string): any {
 }
 
 function getRootPath(lines: string[]) {
-    const macths = ["at Function.Module._load", "at Module.require", "at require", "at Object.<anonymous>"];
+    // 兼容新旧 Node 栈帧（Node<22: "Function.Module._load" / Node22+: "Function._load"）、
+    // mocha(ts-node) 下 "Context.<anonymous>" 与中间可能插入的 "wrapModuleLoad" 帧：
+    // 按顺序出现匹配（不要求严格相邻），提高在各种加载器下的容错。
+    const macths = [/at Function(\.Module)?\._load/, "at Module.require", /at require\b/, /at (Object|Context)\.<anonymous>/];
     let matchIndex = 0;
     for (let line of lines) {
-        if (line.includes(macths[matchIndex])) {
-            if(matchIndex === macths.length - 1) {
+        const matcher = macths[matchIndex];
+        if (matcher instanceof RegExp ? matcher.test(line) : line.includes(matcher)) {
+            if (matchIndex === macths.length - 1) {
                 let arr = line.split("(")[1].split(":")
                 arr.pop()
                 arr.pop()
                 return arr.join(':')
             }
             matchIndex++;
-        }else{
-            matchIndex = 0;
         }
     }
     return undefined;
@@ -92,6 +122,7 @@ export { app, value, config };
 export * from "./core.decorator";
 export * from "./route.decorator";
 export * from "./database.decorator";
+export * from "./bind.decorator";
 
 export { default as LogFactory} from "./factory/log-factory.class";
 export { default as CacheFactory} from "./factory/cache-factory.class";

package/test/bind.test.ts

@@ -0,0 +1,28 @@
+const chaiObj = require('chai');
+chaiObj.use(require("chai-http"));
+const expect = chaiObj.expect;
+
+describe("Test @bind and token", () => {
+    const testAddr = `http://${process.env.LOCAL_HOST || "localhost"}:8081`;
+    it("/bind/param (route @bind)", (done) => {
+        chaiObj.request(testAddr).get("/bind/param/100?name=testname").end((err, res) => {
+            expect(JSON.parse(res.text)).to.deep.equal({ id: "100", name: "testname" });
+            done();
+        });
+    });
+    it("/bind/token (@bean(Token) + @autoware(Token) + @resource(Token, args))", (done) => {
+        chaiObj.request(testAddr).get("/bind/token").end((err, res) => {
+            expect(res.text).to.equal("test-bean|model-ok");
+            done();
+        });
+    });
+    it("/bind/db (database @bind scalar)", (done) => {
+        const id = Math.floor(Math.random() * 900000) + 100000;
+        chaiObj.request(testAddr).get(`/bind/db?id=${id}`).end((err, res) => {
+            expect(res.text).to.match(/^bind insert: \d+/);
+            done();
+        });
+    });
+});
+
+export {};

package/test/decorator-utils.test.ts

@@ -0,0 +1,42 @@
+import { expect } from "chai";
+import { isStd, getStdArgs } from "../src/decorator-utils";
+
+describe("decorator-utils · isStd 双签名判据", () => {
+    it("legacy 类装饰器（1 参）→ false", () => {
+        expect(isStd([class Foo {}])).to.equal(false);
+    });
+
+    it("legacy 方法/属性装饰器（2 参，第 2 参是 string key）→ false", () => {
+        expect(isStd([{}, "methodName"])).to.equal(false);
+    });
+
+    it("legacy 带 descriptor 方法 / 参数装饰器（3 参）→ false", () => {
+        expect(isStd([{}, "methodName", {}])).to.equal(false);
+        expect(isStd([{}, "methodName", 0])).to.equal(false);
+    });
+
+    it("标准类/方法/field 装饰器（2 参，第 2 参带 string kind）→ true", () => {
+        expect(isStd([function () {}, { kind: "class" }])).to.equal(true);
+        expect(isStd([function () {}, { kind: "method" }])).to.equal(true);
+        expect(isStd([undefined, { kind: "field" }])).to.equal(true);
+        expect(isStd([{}, { kind: "accessor" }])).to.equal(true);
+    });
+
+    it("第 2 参是对象但无 kind → false", () => {
+        expect(isStd([{}, {}])).to.equal(false);
+    });
+
+    it("第 2 参是 null / 非对象 → false", () => {
+        expect(isStd([{}, null])).to.equal(false);
+        expect(isStd([{}, 42])).to.equal(false);
+    });
+
+    it("getStdArgs 解出 (value, context)", () => {
+        const ctx = { kind: "method", name: "foo" };
+        const [value, context] = getStdArgs([function bar() {}, ctx]);
+        expect(typeof value).to.equal("function");
+        expect(context).to.equal(ctx);
+    });
+});
+
+export {};

package/test-env/docker-compose.test.yml

@@ -0,0 +1,31 @@
+services:
+  mysql:
+    image: mysql:8.0
+    container_name: typespeed-test-mysql
+    environment:
+      MYSQL_ROOT_PASSWORD: root
+      MYSQL_DATABASE: test
+    ports:
+      - "3306:3306"
+    volumes:
+      - ./mysql-init:/docker-entrypoint-initdb.d
+    healthcheck:
+      test: ["CMD", "mysqladmin", "ping", "-h", "localhost", "-proot"]
+      interval: 3s
+      timeout: 3s
+      retries: 20
+
+  redis:
+    image: redis:7
+    container_name: typespeed-test-redis
+    ports:
+      - "6379:6379"
+
+  rabbitmq:
+    image: rabbitmq:3.8
+    container_name: typespeed-test-rabbitmq
+    environment:
+      RABBITMQ_DEFAULT_USER: guest
+      RABBITMQ_DEFAULT_PASS: guest
+    ports:
+      - "5672:5672"

package/test-env/mysql-init/init.sql

@@ -0,0 +1,8 @@
+-- 与 CI 的 Setup MySQL 步骤一致：建 test 库 + user 表
+CREATE DATABASE IF NOT EXISTS test DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;
+USE test;
+CREATE TABLE IF NOT EXISTS `user` (
+  `id` int(11) NOT NULL AUTO_INCREMENT,
+  `name` varchar(100) DEFAULT NULL,
+  PRIMARY KEY (`id`)
+) ENGINE=InnoDB AUTO_INCREMENT=1 DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci;

package/test-env//346/234/254/345/234/260Docker/346/265/213/350/257/225/346/226/271/346/241/210.md

@@ -0,0 +1,69 @@
+# 本地 Docker 测试方案
+
+typespeed 测试依赖三个外部服务（MySQL / Redis / RabbitMQ），本机没有常驻服务时用 Docker 起一套与 CI 一致的环境来跑测试。
+
+## 一、前置条件
+
+- 本机已安装 **OrbStack**（或 Docker Desktop），Docker CLI 可用：`docker --version`
+- 若 OrbStack 未运行，先启动它（菜单栏点开即可，或 `open -a OrbStack`）
+- 端口占用：默认映射 `3306 / 6379 / 5672`，起容器前确认空闲（`nc -z localhost 3306` 等）
+
+## 二、一键启动测试依赖
+
+```bash
+cd /Users/zzz/book/typespeed
+docker compose -f test-env/docker-compose.test.yml up -d
+```
+
+启动三个容器：
+
+| 服务 | 容器名 | 端口 | 账号 |
+|------|--------|------|------|
+| MySQL 8.0 | typespeed-test-mysql | 127.0.0.1:3306 | root / root，库 `test` |
+| Redis 7 | typespeed-test-redis | 127.0.0.1:6379 | 无 |
+| RabbitMQ 3.8 | typespeed-test-rabbitmq | 127.0.0.1:5672 | guest / guest |
+
+MySQL 首次启动会自动执行 `test-env/mysql-init/init.sql`（建 `test` 库 + `user` 表，与 CI 的 Setup MySQL 步骤一致）。
+
+检查就绪状态：
+
+```bash
+docker compose -f test-env/docker-compose.test.yml ps          # 三容器 Up 且 mysql 为 healthy
+docker exec typespeed-test-mysql mysql -uroot -proot -e "USE test; SHOW TABLES;"
+docker exec typespeed-test-redis redis-cli ping        # PONG
+docker exec typespeed-test-rabbitmq rabbitmq-diagnostics -q ping   # Ping succeeded
+```
+
+## 三、跑测试
+
+```bash
+npm test
+```
+
+预期：`51 passing`。
+
+> 说明：`package.json` 的 test 脚本已加 `NODE_OPTIONS=--no-experimental-strip-types`，这是 Node 22 下 mocha 加载 CJS 风格 .ts 测试的必需项（否则报 `require is not defined`）。
+
+## 四、收尾
+
+```bash
+docker compose -f test-env/docker-compose.test.yml down        # 停容器（保留数据卷需加 -v）
+```
+
+## 五、本次排障记录（2026-09-06）
+
+本地 `npm test` 曾长期 0 passing / 47 failing，所有请求返回 404 错误页（`src/default/pages/404.html`，即 MIT License 模板页）。曾误判为"缺本地服务"（环境差异），用 Docker 起齐服务后依然全挂，最终定位为**框架根因**：
+
+1. `src/typespeed.ts` 的 `getRootPath()` 靠匹配调用栈推断应用根目录（`mainPath`），原匹配写死旧版 Node 栈帧格式 `at Function.Module._load` 和 `at Object.<anonymous>`：
+   - Node 22 的帧是 `at Function._load`（少了 `Module.`）；
+   - mocha 下 hooks 的帧是 `at Context.<anonymous>`（不是 `Object.`），且 `Function._load` 与 `Module.require` 之间会插入 `wrapModuleLoad` 帧。
+   - 匹配全部落空 → `mainPath` 回退成 mocha 的 bin 目录 → config 不加载、app/src 下组件不加载、路由不注册 → 一切请求 404。
+2. 修复：`getRootPath` 改为**按顺序出现匹配**（不要求帧严格相邻），帧格式用正则兼容新旧 Node 与 mocha。改动见 `src/typespeed.ts`（未提交）。
+3. 修复后本地 `npm test` 全绿 **51 passing (3s)**。
+4. 连带影响：CI 若从 node 16 升到 node 22（见 0.4 改动），旧的栈匹配同样会失效——本修复对 CI 也是必需的。
+
+## 六、附：docker-compose.test.yml 内容要点
+
+- 服务定义与 CI（`.github/workflows/test.yml`）的 services 保持一致：mysql root/root + `test` 库、redis、rabbitmq guest/guest。
+- MySQL 加了 healthcheck，避免测试启动时库还没就绪。
+- 初始化 SQL 挂在 `test-env/mysql-init/init.sql`，与 CI 建表语句一致。