typespeed 2.4.10 → 2.5.0

package/introduction/decorator-next/src/main.ts

@@ -0,0 +1,64 @@
+// Symbol.metadata polyfill：Node 22/24/26 都没有 Symbol.metadata，
+// 标准装饰器的 context.metadata 依赖它，缺失会 TypeError，必须最先执行。
+(Symbol as { metadata?: symbol }).metadata ??= Symbol("Symbol.metadata");
+
+import express from "express";
+import {
+    component, getComponent, autoware, bean, getBean,
+    getMapping, bind, setRouter,
+} from "../../../dist/typespeed";
+
+class CacheBean {
+    name = "cache-bean";
+}
+
+@component
+class TestService {
+
+    @bean(CacheBean)
+    getCache() { return new CacheBean(); }
+
+    @autoware(CacheBean)
+    cache!: CacheBean;
+
+    // 标准模式：无参数装饰器，@bind 声明「参数名 → 来源」
+    @getMapping("/std/test/:id")
+    @bind({ id: "reqParam" })
+    async test(id: string) {
+        return { id, cache: this.cache.name };
+    }
+}
+
+// 验证 1：@component / @autoware / @bean
+const svc = getComponent(TestService);
+console.log("[component] registered:", svc !== undefined);
+console.log("[autoware(CacheBean)] injected:", svc && (svc as any).cache?.name);
+console.log("[bean(CacheBean)] factory:", getBean(CacheBean)?.name);
+
+// 验证 2：@getMapping + @bind 路由，走 setRouter 真实 HTTP 请求
+const app = express();
+setRouter(app);
+const server = app.listen(0, () => {
+    const addr = server.address() as any;
+    const port = addr.port;
+    httpGet(`http://127.0.0.1:${port}/std/test/123`, (body) => {
+        console.log("[route @bind] response:", body);
+        const parsed = JSON.parse(body);
+        const ok = svc !== undefined
+            && (svc as any).cache?.name === "cache-bean"
+            && getBean(CacheBean)?.name === "cache-bean"
+            && parsed.id === "123"
+            && parsed.cache === "cache-bean";
+        console.log(ok ? "STANDARD DECORATORS OK" : "STANDARD DECORATORS FAILED");
+        server.close();
+        process.exit(ok ? 0 : 1);
+    });
+});
+
+function httpGet(url: string, cb: (body: string) => void) {
+    require("http").get(url, (res: any) => {
+        let data = "";
+        res.on("data", (chunk: any) => { data += chunk; });
+        res.on("end", () => cb(data));
+    });
+}

package/introduction/decorator-next/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "es2022",
+    "module": "commonjs",
+    "moduleResolution": "node",
+    "useDefineForClassFields": true,
+    "experimentalDecorators": false,
+    "emitDecoratorMetadata": false,
+    "lib": ["es2022", "esnext.decorators", "dom"],
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "strict": false,
+    "outDir": "./dist",
+    "baseUrl": "."
+  },
+  "include": ["./src/**/*.ts"]
+}

package/introduction/decorator-next//346/225/231/347/250/213.md

@@ -0,0 +1,384 @@
+# 一套装饰器，服务两代语法：typespeed 2.5.x 标准装饰器双轨
+
+> 本章教程配套 typespeed 2.5.x 的「装饰器双轨」能力。阅读前提：用过 typespeed 2.4.x 的 legacy 装饰器（`@component` / `@getMapping` / `@insert` 等），读过《TypeScript框架开发实践》相关章节更佳。
+>
+> 本文按「**为什么 → 怎么用 → 原理 → 怎么扩展**」四段展开，读完你既能直接上手标准装饰器，也能自己动手给一个装饰器加上双签名。
+>
+> 配套可运行代码：本目录 `src/main.ts`（标准模式，`experimentalDecorators: false`）。
+
+---
+
+## 一、为什么：一个框架，两批用户
+
+typespeed 从 2.4.x 起用的是一套基于 TypeScript 早期实验语法写的装饰器，也就是我们熟悉的「legacy 装饰器」。它长这样：
+
+```ts
+@component
+class TestDatabase {
+    @autoware
+    private cacheBean: CacheFactory;
+
+    @getMapping("/db/select")
+    async select(req, res) { /* ... */ }
+}
+```
+
+这套写法依赖 `tsconfig.json` 里两条开关：
+
+```jsonc
+{
+    "experimentalDecorators": true,   // 开 legacy 装饰器
+    "emitDecoratorMetadata": true     // 生成 design:* 元数据，供 @autoware 推导类型
+}
+```
+
+**它已经写进出版书里**，书读者照着抄就能跑。这是 typespeed 的地基，绝不能动。
+
+但 TypeScript 生态已经转向另一套装饰器——**TC39 标准装饰器**（提案当前处于 Stage 2.7，TS 5.0+ 已稳定转译）。两套装饰器的**运行时签名完全不同**：
+
+| 用户 tsconfig | 装饰器运行时收到的签名 |
+|---|---|
+| `experimentalDecorators: true`（legacy） | 类 `(ctor)`；方法/属性 `(target, key)`；带 descriptor 方法 `(target, key, descriptor)`；参数 `(target, key, index)` |
+| `experimentalDecorators: false`（标准） | 统一 `(value, context)`，`context` 恒为带 `kind` 字段的对象 |
+
+两套签名不仅在语法上不同，更关键的是：**`experimentalDecorators` 是项目级开关**，一个编译单元只能选一种。所以框架要么只服务 legacy 用户，要么只服务标准用户，很难两全。
+
+而 typespeed 的判断是：**两个都要**。理由有三：
+
+1. **旧版是地基**——书已出版，legacy 代码必须零改动继续跑，这是底线；
+2. **标准装饰器是未来**——`context.metadata` + `Symbol.metadata` 能做声明式元数据驱动，正是「AI 友好框架」想要的（AI 读得懂、写得了）；
+3. **迁移要跟功能走**——业界的共识是「不重写能跑的代码」，标准装饰器应该 opt-in（按需选），而不是强迫用户升级。
+
+于是 2.5.x 的答案是：**单份源码、运行时双签名感知**。一套装饰器函数，运行时根据收到的参数形态，自动判断该走 legacy 分支还是标准分支。legacy 用户零感知，标准用户 opt-in 就能用。
+
+---
+
+## 二、怎么用：三步切到标准装饰器
+
+### 2.1 改 tsconfig（关掉 legacy，进入标准模式）
+
+标准模式的关键是**关掉 `experimentalDecorators`，同时必须关掉 `emitDecoratorMetadata`**（标准模式下开着它编译会直接报错 TS5052）：
+
+```jsonc
+{
+  "compilerOptions": {
+    "target": "es2022",
+    "useDefineForClassFields": true,
+    "experimentalDecorators": false,   // ★ 关 legacy，进标准模式
+    "emitDecoratorMetadata": false,    // ★ 标准模式必须关，否则 TS5052
+    "lib": ["es2022", "esnext.decorators"]
+  }
+}
+```
+
+### 2.2 加一行 Symbol.metadata polyfill
+
+标准装饰器的 `context.metadata` 依赖全局的 `Symbol.metadata`。**Node 22/24/26 至今都没有这个符号**，缺了会直接 `TypeError`。所以在入口最早处补一行（本目录 `src/main.ts` 第一行就是它）：
+
+```ts
+(Symbol as { metadata?: symbol }).metadata ??= Symbol("Symbol.metadata");
+```
+
+> 注意：这行必须在任何装饰器类定义**之前**执行，否则类定义时访问 `context.metadata` 会崩。
+
+### 2.3 用「显式 token」替代 design:type
+
+legacy 下 `@autoware` 靠 `emitDecoratorMetadata` 自动生成的 `design:type` 推导注入类型；标准模式关掉了元数据生成，`design:type` / `design:returntype` 全部消失。所以依赖注入要**显式传 token**：
+
+```ts
+// legacy（design:type 自动推导）
+@autoware
+private cacheBean: CacheFactory;
+
+// 标准（显式 token）
+@autoware(CacheFactory)
+cacheBean!: CacheFactory;
+```
+
+`@bean` / `@resource` 同理。`@resource` 还支持带构造参数（首参是类 = token，其余是构造参数）：
+
+```ts
+@resource(UserModel, "user")     // token=UserModel，构造参数 "user"
+private userModel: UserModel;
+```
+
+### 2.4 用 @bind 替代参数装饰器
+
+标准装饰器**删除了参数装饰器**（TS 官方明确「does not allow decorating parameters」）。`@reqParam` / `@reqBody` / `@reqQuery` 这些路由参数装饰器，以及数据库的 `@param`，都要改成**方法级 `@bind`**：
+
+```ts
+// ── legacy（书上的写法）──
+@getMapping("/request/param/:id")
+async testParam(@res res, @reqParam id: number) {
+    res.send("test param: " + id);
+}
+
+// ── 标准（方法级 @bind：参数名 → 来源）──
+@getMapping("/std/test/:id")
+@bind({ id: "reqParam" })
+async test(id: string) {
+    return { id };
+}
+```
+
+`@bind` 的来源取值：`"req"` / `"res"` / `"next"` / `"reqBody"` / `"reqParam"` / `"reqQuery"` / `"reqForm"`。
+
+数据库侧，`@param` 的散参写法也换成 `@bind`（SQL 占位符 → 参数索引）：
+
+```ts
+// legacy
+@insert("Insert into `user` (id, name) values (#{id}, #{name})")
+async addRow(@param("name") newName: string, @param("id") id: number) { }
+
+// 标准
+@insert("Insert into `user` (id, name) values (#{id}, #{name})")
+@bind({ name: 0, id: 1 })
+async addRow(newName: string, id: number) { }
+```
+
+> **更推荐的做法**：数据库侧干脆用**对象传参**（typespeed 一直支持，标准模式下它是最省事的主路径），完全不需要 `@param` / `@bind`：
+>
+> ```ts
+> @insert("Insert into `user` (id, name) values (#{id}, #{name})")
+> async addRowByObject(myParams: object) { }   // 调用时传 { id, name }，自动按属性名匹配 #{占位符}
+> ```
+
+### 2.5 完整对照（本目录可跑的例子）
+
+```ts
+// src/main.ts
+(Symbol as { metadata?: symbol }).metadata ??= Symbol("Symbol.metadata");
+
+import express from "express";
+import { component, getComponent, autoware, bean, getBean, getMapping, bind, setRouter } from "../../../dist/typespeed";
+
+class CacheBean {
+    name = "cache-bean";
+}
+
+@component
+class TestService {
+    @bean(CacheBean)                          // 显式 token
+    getCache() { return new CacheBean(); }
+
+    @autoware(CacheBean)                      // 显式 token
+    cache!: CacheBean;
+
+    @getMapping("/std/test/:id")
+    @bind({ id: "reqParam" })                 // 方法级参数绑定
+    async test(id: string) {
+        return { id, cache: this.cache.name };
+    }
+}
+
+const app = express();
+setRouter(app);                               // 注册路由，与 legacy 完全一致
+app.listen(3000);
+```
+
+跑起来后 `GET /std/test/123` 返回 `{"id":"123","cache":"cache-bean"}`。
+
+一句话总结用法：**tsconfig 关两开关 → 入口补 polyfill → 注入用显式 token → 参数用 @bind（或对象传参）**，其余 `@component` / `@getMapping` / `@insert` 等类/方法装饰器**写法不变**。
+
+---
+
+## 三、原理：一套函数怎么识别两套签名
+
+### 3.1 核心事实：装饰器函数是普通函数
+
+很多人误以为「legacy 装饰器」和「标准装饰器」是两种不同的函数。其实**装饰器函数就是普通函数**，它运行时收到什么参数，完全由**调用方**（用户代码）的编译模式决定：
+
+- 用户用 `experimentalDecorators: true` 编译，TS 就把装饰器函数当成 legacy 语义调用，传 `(target, key, descriptor?)`；
+- 用户用 `experimentalDecorators: false` 编译，TS 就按标准语义调用，传 `(value, context)`。
+
+而 typespeed 库**本身只需要编译一份**（仍然用 legacy 模式编译，因为库内部不用装饰器语法，只导出装饰器函数）。用户那边选什么模式，运行时库里就收到什么签名。这就是「单份源码、双签名感知」的物理基础。
+
+### 3.2 isStd：一条可靠的判别式
+
+于是问题收敛成：**一个装饰器函数，怎么判断自己收到的是哪套签名？**
+
+标准模式的 `context` 恒是带 `kind` 字段的对象，这是最可靠的分界。typespeed 的判据（`src/decorator-utils.ts`）：
+
+```ts
+function isStd(args: unknown[]): boolean {
+    return args.length === 2
+        && typeof args[1] === "object"
+        && args[1] !== null
+        && typeof (args[1] as { kind?: unknown }).kind === "string";
+}
+```
+
+为什么这个判据不会误判 legacy？逐条对照：
+
+| legacy 形态 | args.length | 第二参 | isStd 结果 |
+|---|---|---|---|
+| 类装饰器 `(ctor)` | 1 | — | false（长度不是 2） |
+| 方法/属性 `(target, key)` | 2 | string 的 key | false（不是对象） |
+| 带 descriptor 方法 / 参数 `(target, key, desc/idx)` | 3 | — | false（长度不是 2） |
+| 标准 `(value, context)` | 2 | 带 `kind` 的对象 | **true** |
+
+注意**不能**用「3 参 = legacy」这种判据——legacy 类装饰器只有 1 参、属性装饰器 2 参，只有带 descriptor 的方法和参数装饰器才是 3 参。
+
+### 3.3 每个装饰器：入口分流，legacy 逐字不变
+
+拿到 `isStd` 后，每个装饰器的结构就统一了——**入口加一行分流，legacy 分支原样保留，标准分支是新增**。以 `component`（类装饰器）为例：
+
+```ts
+function component(...args: any[]): any {
+    if (isStd(args)) {
+        // ── 标准 (value, context) ──
+        const [ctor, ctx] = getStdArgs(args);
+        ctx.addInitializer(function (this: any) {
+            objectMapper.set(this.name, new this());   // 类定义完成后注册实例
+        });
+        return;
+    }
+    // ── legacy (ctor)，与 2.4.x 逐字一致 ──
+    const constructorFunction = args[0];
+    objectMapper.set(constructorFunction.name, new constructorFunction());
+}
+```
+
+关键设计纪律：**legacy 分支的每一行都和 2.4.x 一模一样**，只把原来的命名参数换成 `args[0]` / `args[1]` 的解构。这样老代码的行为被回归测试（51 个 legacy 用例）逐字节锁定，标准分支怎么加都不会碰坏地基。
+
+### 3.4 方法装饰器：改 descriptor → 返回替换函数
+
+legacy 方法装饰器靠「就地改 `descriptor.value`」来替换方法；标准方法装饰器则是**返回一个新函数**来替换。以数据库的 `insert` 为例：
+
+```ts
+function insert(sql: string) {
+    return (...args: any[]): any => {
+        if (isStd(args)) {
+            const [, ctx] = getStdArgs(args);
+            // ── 标准：返回替换函数 ──
+            return async function (this: any, ...callArgs: any[]) {
+                const result = await queryForExecute(sql, callArgs, this, String(ctx.name));
+                // ...
+                return result.insertId;
+            };
+        }
+        // ── legacy：就地改 descriptor.value，逐字一致 ──
+        const [, , descriptor] = args;
+        descriptor.value = async function (this: any, ...callArgs: any[]) {
+            const result = await queryForExecute(sql, callArgs, args[0], args[1]);
+            // ...
+            return result.insertId;
+        };
+    };
+}
+```
+
+### 3.5 addInitializer：标准模式的注册时机
+
+标准模式下有个 legacy 没有的问题：**方法/field 装饰器拿不到类名**（`context` 里只有 `name`=成员名，没有类名）。而 typespeed 的注册表都是按「类名 + 成员名」做 key 的。
+
+解法是 `context.addInitializer`——它注册一个回调，在类定义完成后执行，回调里的 `this` 就是类（对类装饰器）或实例（对成员装饰器），能拿到 `this.constructor.name`。所以标准分支的注册动作统一挂进 `addInitializer`：
+
+```ts
+if (isStd(args)) {
+    const [, ctx] = getStdArgs(args);
+    ctx.addInitializer(function (this: any) {
+        const className = this.constructor.name;   // 到这里才拿得到类名
+        routerMapper[method][value] = { /* ...注册路由... */ };
+    });
+    return;
+}
+```
+
+这也是为什么「显式 token」在标准模式是刚需——`addInitializer` 只解决「类名」，解决不了 `design:type` 的消失。
+
+### 3.6 两个硬缝：参数装饰器与 design:type
+
+标准装饰器有两处 legacy 有、标准没有的东西，必须重新设计，这就是 2.5.x 唯二的真改动点：
+
+1. **参数装饰器**（`@reqParam` / `@param` 等）——标准模式删了，改为方法级 `@bind`（见 2.4）。`@bind` 内部只是把「参数名 → 来源」的声明存进一张按「类名+方法名」为 key 的注册表，路由 invoker 在取参数时读到这张表，按「参数名 → 索引」还原出每个位置该从请求里取什么。
+2. **`design:type` / `design:returntype`**——`emitDecoratorMetadata` 关掉后消失，改为显式 token（见 2.3）。
+
+---
+
+## 四、怎么扩展：自己写一个双签名装饰器
+
+掌握了上面的套路，你也能给任意自定义装饰器加双签名。核心模板就三步：
+
+```ts
+import { isStd, getStdArgs } from "./decorator-utils";
+
+function myLog(prefix: string) {
+    return (...args: any[]): any => {
+        if (isStd(args)) {
+            // ── 标准分支：方法装饰器，返回替换函数 ──
+            const [, ctx] = getStdArgs(args);
+            return function (this: any, ...callArgs: any[]) {
+                console.log(prefix, String(ctx.name), callArgs);
+                return args[0].apply(this, callArgs);   // 调用原方法
+            };
+        }
+        // ── legacy 分支：就地改 descriptor ──
+        const [target, key, descriptor] = args;
+        const original = descriptor.value;
+        descriptor.value = function (this: any, ...callArgs: any[]) {
+            console.log(prefix, key, callArgs);
+            return original.apply(this, callArgs);
+        };
+    };
+}
+```
+
+三个要点：
+
+1. **签名永远写 `(...args: any[])`**——这样 legacy（1/2/3 参）和标准（2 参）都能过类型检查；
+2. **入口第一句 `if (isStd(args))` 分流**，两个分支各写各的，别共用；
+3. **方法装饰器**：legacy 改 `descriptor.value`，标准返回新函数；**类装饰器**：标准用 `ctx.addInitializer`，legacy 直接拿 `args[0]`。
+
+### 4.1 用 context.metadata 做声明式元数据
+
+标准装饰器最大的红利是 `context.metadata`——类定义完成后，这些元数据会汇总到 `Class[Symbol.metadata]`，供框架在启动时统一读取：
+
+```ts
+function register(tag: string) {
+    return (value: Function, ctx: any) => {
+        ctx.metadata.classTag = tag;            // 写元数据
+        ctx.addInitializer(function (this: any) {
+            registry.set(this, { name: ctx.name, tag });
+        });
+    };
+}
+
+@register("user-service")
+class UserService {}
+
+// 运行期读：所有装饰器写的元数据都在这
+const meta = (UserService as any)[Symbol.metadata];
+console.log(meta.classTag);   // "user-service"
+```
+
+这为 typespeed 后续阶段（自动路由、自动注册）铺了路——启动时读 `Symbol.metadata` 就能建路由表，比 reflect-metadata 扫描更干净。这也是「AI 友好」的方向：元数据显式、可读、可写，AI 拿到就能理解一个服务的结构。
+
+### 4.2 边界与纪律
+
+- **默认永远是 legacy**。标准模式只能通过子路径或后续大版本 opt-in，绝不能偷偷把标准模式设成默认——书读者的 legacy 代码是命根子。
+- **对象传参是数据库主路径**，`@bind` 散参是补充。能不用 `@bind` 就不用。
+- 一个编译单元只能选一种语义，别在同一个 tsconfig 里混用两套写法。
+
+---
+
+## 附：装饰器双签名对照表
+
+| 装饰器 | 族 | legacy 形态 | 标准形态 |
+|---|---|---|---|
+| `component` | core | 类 `(ctor)` | 类 + `addInitializer` |
+| `bean` | core | 方法 `(target, key)` | 方法 + 显式 token |
+| `autoware` | core | 属性 `(target, key)` | field + 显式 token |
+| `resource` | core | 属性 + 构造参数 | field + 显式 token + 构造参数 |
+| `schedule` | core | 方法 `(target, key)` | 方法 + `addInitializer` |
+| `getMapping` / `postMapping` / `requestMapping` | route | 方法 | 方法 + `addInitializer` |
+| `before` / `after` | route | 方法 | 方法 + `addInitializer` |
+| `upload` / `jwt` | route | 方法 | 方法 + `addInitializer` |
+| `req` / `res` / `next` / `reqBody` / `reqParam` / `reqQuery` / `reqForm` | route | **参数** | **硬缝 → `@bind`** |
+| `insert` / `update` / `remove` / `select` | database | 方法带 descriptor | 方法返回替换函数 |
+| `resultType` / `cache` | database | 方法 | 方法 + `addInitializer` |
+| `param` | database | **参数** | **硬缝 → `@bind`** |
+| `app` | 入口 | 类 `(ctor)` | 类 + `addInitializer` |
+| `value` | 入口 | 属性 | field 返回 initializer |
+
+> 本教程由 typespeed 2.5.x 开发笔记整理，配套《TypeScript技术实战》书稿体系。代码动一步，长文跟一篇。

package/introduction/tsconfig.json

@@ -16,5 +16,8 @@
   },
   "include": [
     "./**/*.ts"
+  ],
+  "exclude": [
+    "decorator-next"
   ]
 }

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "typespeed",
-  "version": "2.4.10",
+  "version": "2.5.0",
   "description": "A new Framework for TypeScript.",
   "author": "speedphp",
   "license": "MIT License",
   "scripts": {
-    "test": "mocha --require ts-node/register test/**/*.ts --exit",
+    "test": "NODE_OPTIONS=--no-experimental-strip-types mocha --require ts-node/register test/**/*.ts --exit",
     "test-with-coverage": "nyc --reporter=lcov npm test",
     "start": "ts-node --transpile-only app/src/main.ts",
     "build": "tsc -p .",

package/src/bind.decorator.ts

@@ -0,0 +1,50 @@
+import { isStd, getStdArgs } from "./decorator-utils";
+
+/**
+ * 方法级参数绑定注册表：key = `[className, methodName]`，value = 绑定声明。
+ * 标准装饰器删除了参数装饰器，@bind 是方法级替代（legacy 模式同样可用）。
+ * 按 value 类型区分两种语义：
+ *   - database 场景：{ SQL占位符名: 参数索引 }（值为 number）
+ *   - route 场景：{ 参数名: 请求来源 }（值为 string，如 "reqParam" / "reqBody" / "reqQuery"）
+ */
+const bindParamMap: Map<string, Record<string, string | number>> = new Map();
+
+/**
+ * @bind 方法级参数绑定装饰器。
+ *
+ * database 散参绑定（对象传参已是主路径，@bind 作散参补充）：
+ * ```
+ * @insert("Insert into `user` (id, name) values (#{id}, #{name})")
+ * @bind({ name: 0, id: 1 })
+ * async addRow(newName: string, id: number) { }
+ * ```
+ *
+ * route 参数绑定（替代 req/res/reqBody/reqParam/reqQuery/reqForm 参数装饰器）：
+ * ```
+ * @getMapping("/user/:id")
+ * @bind({ id: "reqParam", body: "reqBody", q: "reqQuery" })
+ * async getUser(id: string, body: any, q: string) { }
+ * ```
+ */
+function bind(mapping: Record<string, string | number>) {
+    return function (...args: any[]): any {
+        if (isStd(args)) {
+            const [, ctx] = getStdArgs(args);
+            const methodName = String(ctx.name);
+            ctx.addInitializer(function (this: any) {
+                bindParamMap.set([this.constructor.name, methodName].toString(), mapping);
+            });
+            return;
+        }
+        const target = args[0];
+        const propertyKey = args[1] as string;
+        bindParamMap.set([target.constructor.name, propertyKey].toString(), mapping);
+    };
+}
+
+/** 读取某方法上的 @bind 声明（route/database 内部使用） */
+function getBindMapping(className: string, methodName: string): Record<string, string | number> | undefined {
+    return bindParamMap.get([className, methodName].toString());
+}
+
+export { bind, getBindMapping };