speed 1.3.1 → 1.3.2

package/README.md

@@ -33,6 +33,22 @@ registry.unregister("user-service", "127.0.0.1", 8080); // true
 
 > 详见 `docs/1.3.1-本地注册表.md`（为什么 → 怎么用 → 原理 → 怎么扩展）。
 
+## 服务声明（1.3.2）
+
+`@Service` 装饰器把类标记为「可被发现的微服务」——**只声明身份，不注册实例**（真实 host/port 要等启动后拿到再提交）：
+
+```ts
+import { Service, serviceRegistrar } from "speed";
+
+@Service("user-service")
+class UserService {}
+
+serviceRegistrar.register("user-service", { host: "127.0.0.1", port: 8080 });
+serviceRegistrar.getRegistry().getInstances("user-service");
+```
+
+> `@Service` 只声明，真实 host/port 在启动后用 `serviceRegistrar.register()` 提交；详见 `docs/1.3.2-Service装饰器.md`。
+
 ## 模块（单包 `speed` + 子路径导出）
 
 | 子路径 | 模块 | 版本 |

package/dist/core/index.d.ts

@@ -1 +1 @@
-export {};
+export { Service } from "./service.decorator";

package/dist/core/index.js

@@ -1,2 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.Service = void 0;
+// core —— 共享核心：@Service / @RpcClient / @GatewayRoute / @Config 装饰器 + 基础设施
+var service_decorator_1 = require("./service.decorator");
+Object.defineProperty(exports, "Service", { enumerable: true, get: function () { return service_decorator_1.Service; } });

package/dist/core/service.decorator.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @Service —— 类装饰器：把类标记为「可被发现的微服务」，声明即注册。
+ *
+ * 支持四种形式：
+ *   @Service                                     // 服务名默认用类名
+ *   @Service()                                   // 同上，显式空参数
+ *   @Service("user-service")                     // 指定服务名
+ *   @Service({ name, group, version })           // 带元数据
+ *
+ * 注意：装饰器只做「声明」（登记身份元数据），不注册实例——
+ * 真实 host/port 要等服务 start 后才能拿到，由 serviceRegistrar.register() 在启动后提交。
+ */
+export declare function Service(...args: any[]): any;

package/dist/core/service.decorator.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Service = Service;
+const service_registrar_1 = require("../registry/service-registrar");
+// 解析 @Service 的入参：string 视为服务名，对象视为元数据，undefined 用默认。
+function resolveOptions(param) {
+    if (typeof param === "string") {
+        return { name: param };
+    }
+    return param ?? {};
+}
+/**
+ * @Service —— 类装饰器：把类标记为「可被发现的微服务」，声明即注册。
+ *
+ * 支持四种形式：
+ *   @Service                                     // 服务名默认用类名
+ *   @Service()                                   // 同上，显式空参数
+ *   @Service("user-service")                     // 指定服务名
+ *   @Service({ name, group, version })           // 带元数据
+ *
+ * 注意：装饰器只做「声明」（登记身份元数据），不注册实例——
+ * 真实 host/port 要等服务 start 后才能拿到，由 serviceRegistrar.register() 在启动后提交。
+ */
+function Service(...args) {
+    // 直接装饰形式：@Service（无参数）—— 标准类装饰器收到 (value, context)
+    if (args.length === 2 && typeof args[1] === "object" && args[1] !== null && args[1].kind === "class") {
+        const context = args[1];
+        context.addInitializer(function () {
+            // 标准类装饰器 initializer 的 this 是类本身（非实例），this.name 即类名
+            service_registrar_1.serviceRegistrar.declare(this.name, {});
+        });
+        return;
+    }
+    // 工厂形式：@Service() / @Service("name") / @Service({...})
+    const options = resolveOptions(args[0]);
+    return function (value, context) {
+        context.addInitializer(function () {
+            service_registrar_1.serviceRegistrar.declare(this.name, options);
+        });
+    };
+}

package/dist/index.d.ts

@@ -1,2 +1,3 @@
 export * from "./registry";
+export * from "./core";
 export {};

package/dist/index.js

@@ -15,8 +15,5 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 // speed —— TypeScript 微服务编排框架（对标 Spring Cloud），构建于 typespeed 之上。
-//
-// 骨架阶段（1.3.x）：speed 自身的微服务能力（@Service / @RpcClient / @GatewayRoute / @Config 等）
-// 随模块开发逐步加入；项目入口引导暂由 typespeed 的 @app / ServerFactory 承担
-// （脚手架模板 src/main.ts 直接从 "typespeed" 引入，保证 MAIN_PATH 正确解析到应用目录）。
 __exportStar(require("./registry"), exports);
+__exportStar(require("./core"), exports);

package/dist/registry/index.d.ts

@@ -1,2 +1,4 @@
 export { LocalRegistry } from "./registry";
-export type { ServiceInstance } from "./registry";
+export type { ServiceInstance, Registration, Registry } from "./registry";
+export { ServiceRegistrar, serviceRegistrar } from "./service-registrar";
+export type { ServiceOptions } from "./service-registrar";

package/dist/registry/index.js

@@ -1,6 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.LocalRegistry = void 0;
+exports.serviceRegistrar = exports.ServiceRegistrar = exports.LocalRegistry = void 0;
 // ① 注册中心（服务注册 + 发现）—— 1.3.x 实现
 var registry_1 = require("./registry");
 Object.defineProperty(exports, "LocalRegistry", { enumerable: true, get: function () { return registry_1.LocalRegistry; } });
+var service_registrar_1 = require("./service-registrar");
+Object.defineProperty(exports, "ServiceRegistrar", { enumerable: true, get: function () { return service_registrar_1.ServiceRegistrar; } });
+Object.defineProperty(exports, "serviceRegistrar", { enumerable: true, get: function () { return service_registrar_1.serviceRegistrar; } });

package/dist/registry/registry.d.ts

@@ -3,12 +3,25 @@ export interface ServiceInstance {
     port: number;
     registeredAt?: number;
     metadata?: Record<string, unknown>;
+    status?: string;
 }
-export declare class LocalRegistry {
+export interface Registration {
+    readonly instanceId: string;
+    renew(): void;
+    deregister(): boolean;
+}
+export interface Registry {
+    register(serviceName: string, instance: ServiceInstance): Registration;
+    unregister(serviceName: string, host: string, port: number): boolean;
+    getInstances(serviceName: string): ServiceInstance[];
+}
+export declare class LocalRegistry implements Registry {
     private instances;
-    register(serviceName: string, instance: ServiceInstance): ServiceInstance;
+    register(serviceName: string, instance: ServiceInstance): Registration;
     unregister(serviceName: string, host: string, port: number): boolean;
     getInstances(serviceName: string): ServiceInstance[];
     getServiceNames(): string[];
     getInstanceCount(serviceName: string): number;
+    private normalize;
+    private makeRegistration;
 }

package/dist/registry/registry.js

@@ -4,39 +4,33 @@ exports.LocalRegistry = void 0;
 // 本地注册表：服务注册 + 发现的单点真相（纯内存，不涉及网络）。
 // 数据结构为两级：服务名 -> 实例列表（实例列表用数组，实例带 metadata 扩展位）。
 class LocalRegistry {
-    // 两级结构：服务名 -> 实例列表（实例列表用数组）
     instances = new Map();
     // 注册一个实例。同 host:port 重复注册只更新不新增。
     register(serviceName, instance) {
-        // 去重键：host:port（同一服务内的实例唯一标识）
         const key = `${instance.host}:${instance.port}`;
         const list = this.instances.get(serviceName);
-        // 服务已存在时，在其列表里做线性查找（实例数量少，线性足够）
+        let target;
         if (list) {
             const existing = list.find((item) => `${item.host}:${item.port}` === key);
             if (existing) {
-                // 原地刷新注册时间（心跳语义），并替换 metadata（若本次提供）
+                // 原地刷新注册时间（心跳语义），并替换 metadata/status（若本次提供）
                 existing.registeredAt = Date.now();
-                if (instance.metadata !== undefined) {
+                if (instance.metadata !== undefined)
                     existing.metadata = instance.metadata;
-                }
-                return existing;
+                if (instance.status !== undefined)
+                    existing.status = instance.status;
+                target = existing;
+            }
+            else {
+                target = this.normalize(instance);
+                list.push(target);
             }
-            // 新实例补全 registeredAt 后 push 进列表
-            const newInstance = {
-                ...instance,
-                registeredAt: instance.registeredAt ?? Date.now(),
-            };
-            list.push(newInstance);
-            return newInstance;
         }
-        // 服务不存在：新建列表并存入 map
-        const newInstance = {
-            ...instance,
-            registeredAt: instance.registeredAt ?? Date.now(),
-        };
-        this.instances.set(serviceName, [newInstance]);
-        return newInstance;
+        else {
+            target = this.normalize(instance);
+            this.instances.set(serviceName, [target]);
+        }
+        return this.makeRegistration(serviceName, target);
     }
     // 注销。找到并移除同 host:port 的实例返回 true；否则返回 false。
     unregister(serviceName, host, port) {
@@ -69,5 +63,26 @@ class LocalRegistry {
     getInstanceCount(serviceName) {
         return this.instances.get(serviceName)?.length ?? 0;
     }
+    // 补全实例的 registeredAt（缺省 Date.now()）与 status（缺省 "UP"）
+    normalize(instance) {
+        return {
+            ...instance,
+            registeredAt: instance.registeredAt ?? Date.now(),
+            status: instance.status ?? "UP",
+        };
+    }
+    // 为已登记实例生成注册句柄；句柄闭包持有该实例引用与所在服务名。
+    makeRegistration(serviceName, target) {
+        const instanceId = `${target.host}:${target.port}`;
+        const registry = this;
+        return {
+            instanceId,
+            renew: () => {
+                // 1.3.2 占位：刷新 registeredAt；1.3.3 起改为刷新 lastHeartbeat
+                target.registeredAt = Date.now();
+            },
+            deregister: () => registry.unregister(serviceName, target.host, target.port),
+        };
+    }
 }
 exports.LocalRegistry = LocalRegistry;

package/dist/registry/service-registrar.d.ts

@@ -0,0 +1,15 @@
+import { ServiceInstance, Registration, Registry } from "./registry";
+export interface ServiceOptions {
+    name?: string;
+    group?: string;
+    version?: string;
+}
+export declare class ServiceRegistrar {
+    private declarations;
+    private registry;
+    declare(className: string, options: ServiceOptions): void;
+    register(serviceName: string, instance: ServiceInstance): Registration;
+    getRegistry(): Registry;
+    clear(): void;
+}
+export declare const serviceRegistrar: ServiceRegistrar;

package/dist/registry/service-registrar.js

@@ -0,0 +1,60 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.serviceRegistrar = exports.ServiceRegistrar = void 0;
+const registry_1 = require("./registry");
+// 服务注册协调器：负责「声明 → 提交」两阶段。
+//   - 声明：@Service 装饰器在类定义时调用 declare()，只登记身份元数据，不注册实例。
+//   - 提交：服务启动后调用 register()，用真实 host/port 注册到注册表（每次启动一次）。
+// 「同名多实例」= 一次声明 + N 次提交（合法，负载均衡基础）；
+// 「同名异类」= 同一服务名出现多次声明（declare 时告警）。
+class ServiceRegistrar {
+    // 声明表：服务名 -> 声明列表（同名异类时会有多条）
+    declarations = new Map();
+    registry = new registry_1.LocalRegistry();
+    // @Service 装饰器调用：只做声明（幂等——同一类重复声明不重复登记）。
+    declare(className, options) {
+        const name = options.name ?? className;
+        const list = this.declarations.get(name) ?? [];
+        // 幂等：同一类重复声明（重复 import / 多次装饰）不重复登记
+        if (list.some((d) => d.className === className)) {
+            return;
+        }
+        // 同名异类：已有别的类占用该服务名 → 告警（不阻断，多实例场景由「提交」区分）
+        if (list.length > 0) {
+            console.warn(`[speed] 服务名 "${name}" 已被类 ${list.map((d) => d.className).join(", ")} 占用，` +
+                `本次 ${className} 声明可能造成同名异类冲突。`);
+        }
+        list.push({ className, name, group: options.group, version: options.version });
+        this.declarations.set(name, list);
+    }
+    // 提交：把已声明的服务名注册到注册表（每次启动调用一次）。
+    // host/port 唯一可信来源是真实监听值（server.address().port / start() 后拿到）。
+    register(serviceName, instance) {
+        const declarations = this.declarations.get(serviceName);
+        if (!declarations || declarations.length === 0) {
+            throw new Error(`[speed] 服务名 "${serviceName}" 未通过 @Service 声明，无法注册。`);
+        }
+        // 取第一条声明的 group/version 合并进 metadata（同名异类场景下取首条；一般只有一个）
+        const decl = declarations[0];
+        const metadata = { ...(instance.metadata ?? {}) };
+        if (decl.group !== undefined) {
+            metadata.group = decl.group;
+        }
+        if (decl.version !== undefined) {
+            metadata.version = decl.version;
+        }
+        return this.registry.register(serviceName, { ...instance, metadata });
+    }
+    // 查询入口：拿到底层注册表（供 getInstances / 后续 discover 使用）。
+    getRegistry() {
+        return this.registry;
+    }
+    // 测试/重置用：清空声明与实例。
+    clear() {
+        this.declarations.clear();
+        this.registry = new registry_1.LocalRegistry();
+    }
+}
+exports.ServiceRegistrar = ServiceRegistrar;
+// 进程内单例：@Service 装饰器与启动代码共享同一个注册协调器。
+exports.serviceRegistrar = new ServiceRegistrar();

package/dist/scaffold/command.js

@@ -41,7 +41,7 @@ const program = new commander_1.Command();
 program
     .name("speed")
     .description("A microservices orchestration framework for TypeScript (the Spring Cloud equivalent, built on typespeed).")
-    .version("1.3.1");
+    .version("1.3.2");
 program.command('new <projectName>')
     .description('Create a new speed project.')
     .action((projectName) => {

package/dist/scaffold/templates/main.ts.tpl

@@ -2,25 +2,33 @@
 // 标准装饰器的 context.metadata 依赖它，缺失会 TypeError，必须最先执行。
 (Symbol as { metadata?: symbol }).metadata ??= Symbol("Symbol.metadata");
 
-// 骨架阶段直接使用 typespeed 的 @app 引导（speed 的微服务装饰器 @Service 等自 1.3.2 起提供）。
+// 骨架入口：直接使用 typespeed 的 @app 引导 + speed 的 @Service 声明服务。
 import { app, autoware, ServerFactory } from "typespeed";
+import { Service, serviceRegistrar } from "speed";
 
 /**
  * speed 项目入口骨架（标准装饰器模式）。
  *
  * 目录约定：
  *   - 服务类放 src/（本文件即入口）；
- *   - 配置文件 src/config.json（可选，typespeed 启动时自动读取，可用 config()/@value 访问）；
+ *   - 配置文件 src/config.json（可选，typespeed 启动时自动读取）；
  *   - tsconfig.json 已固定标准装饰器（experimentalDecorators:false + esnext.decorators lib）。
+ *
+ * @Service 声明本服务可被发现（服务名 = 应用名 ###appName###）；
+ * 启动完成后在 main() 里用真实监听端口调用 serviceRegistrar.register() 提交注册。
  */
 @app
+@Service("###appName###")
 class Main {
 
     @autoware(ServerFactory)
     public server!: ServerFactory;
 
     public main() {
-        this.server.start(8080);
-        console.log("speed service started at http://127.0.0.1:8080");
+        const port = 8080;
+        this.server.start(port);
+        // 声明/提交分离：@Service 只做声明，这里用真实 host:port 提交注册
+        serviceRegistrar.register("###appName###", { host: "127.0.0.1", port });
+        console.log(`speed service "###appName###" started at http://127.0.0.1:${port}`);
     }
 }

package/dist/scaffold/templates/package.json.tpl

@@ -8,7 +8,7 @@
         "test": "ts-node --transpile-only src/main.ts"
     },
     "dependencies": {
-        "speed": "^1.3.0",
+        "speed": "^1.3.2",
         "typespeed": "^2.6.7"
     },
     "devDependencies": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "speed",
-  "version": "1.3.1",
+  "version": "1.3.2",
   "description": "A microservices orchestration framework for TypeScript (the Spring Cloud equivalent, built on typespeed).",
   "author": "speedphp",
   "license": "MIT",
@@ -15,6 +15,10 @@
       "types": "./dist/registry/index.d.ts",
       "default": "./dist/registry/index.js"
     },
+    "./core": {
+      "types": "./dist/core/index.d.ts",
+      "default": "./dist/core/index.js"
+    },
     "./gateway": {
       "types": "./dist/gateway/index.d.ts",
       "default": "./dist/gateway/index.js"