@dangao/bun-server 1.3.0 → 1.5.0

package/docs/microservice-nacos.md

@@ -0,0 +1,346 @@
+# Nacos 集成文档
+
+本文档介绍如何在 Bun Server Framework 中使用 Nacos 作为配置中心和服务注册中心。
+
+## 目录
+
+- [概述](#概述)
+- [Nacos 安装](#nacos-安装)
+- [配置中心集成](#配置中心集成)
+- [服务注册中心集成](#服务注册中心集成)
+- [完整示例](#完整示例)
+- [常见问题](#常见问题)
+
+## 概述
+
+Bun Server Framework 通过 `@dangao/nacos-client` 包提供 Nacos 3.X 支持，包括：
+
+- **配置管理**：动态配置获取和监听
+- **服务注册**：服务实例注册、续约、注销
+- **服务发现**：服务实例查询和监听
+- **Open API**：基于 Nacos 3.X Open API 实现
+
+## Nacos 安装
+
+### Docker 安装（推荐）
+
+```bash
+docker run --name nacos -e MODE=standalone -p 8848:8848 nacos/nacos-server:v3.0.0
+```
+
+### 访问控制台
+
+访问 http://localhost:8848/nacos，默认用户名/密码：`nacos/nacos`
+
+## 配置中心集成
+
+### 1. 注册配置中心模块
+
+```typescript
+import { Application } from '@dangao/bun-server';
+import { ConfigCenterModule } from '@dangao/bun-server';
+
+const app = new Application();
+
+app.registerModule(
+  ConfigCenterModule.forRoot({
+    provider: 'nacos',
+    nacos: {
+      client: {
+        serverList: ['http://localhost:8848'],
+        namespaceId: 'public',
+        username: 'nacos',
+        password: 'nacos',
+      },
+      watchInterval: 3000, // 配置轮询间隔（毫秒）
+    },
+  }),
+);
+```
+
+### 2. 在 Nacos 控制台创建配置
+
+1. 登录 Nacos 控制台
+2. 进入"配置管理" -> "配置列表"
+3. 点击"+"创建配置：
+   - **Data ID**：`my-config`
+   - **Group**：`DEFAULT_GROUP`
+   - **配置格式**：`JSON`（或其他格式）
+   - **配置内容**：
+     ```json
+     {
+       "app": {
+         "name": "MyApp",
+         "version": "1.0.0"
+       }
+     }
+     ```
+
+### 3. 使用配置
+
+```typescript
+import {
+  CONFIG_CENTER_TOKEN,
+  type ConfigCenter,
+} from '@dangao/bun-server';
+import { Inject, Injectable } from '@dangao/bun-server';
+
+@Injectable()
+class MyService {
+  public constructor(
+    @Inject(CONFIG_CENTER_TOKEN) private readonly configCenter: ConfigCenter,
+  ) {}
+
+  public async getConfig() {
+    const result = await this.configCenter.getConfig(
+      'my-config',
+      'DEFAULT_GROUP',
+    );
+    const config = JSON.parse(result.content);
+    return config.app.name;
+  }
+}
+```
+
+### 4. 配置热更新
+
+```typescript
+configCenter.watchConfig('my-config', 'DEFAULT_GROUP', (newConfig) => {
+  console.log('Config updated:', newConfig.content);
+  // 更新应用配置
+});
+```
+
+## 服务注册中心集成
+
+### 1. 注册服务注册中心模块
+
+```typescript
+import { ServiceRegistryModule } from '@dangao/bun-server';
+
+app.registerModule(
+  ServiceRegistryModule.forRoot({
+    provider: 'nacos',
+    nacos: {
+      client: {
+        serverList: ['http://localhost:8848'],
+        namespaceId: 'public',
+        username: 'nacos',
+        password: 'nacos',
+      },
+      heartbeatInterval: 5000, // 心跳间隔（毫秒）
+    },
+  }),
+);
+```
+
+### 2. 注册服务
+
+#### 使用装饰器（推荐）
+
+```typescript
+import { ServiceRegistry, Controller, GET } from '@dangao/bun-server';
+
+@ServiceRegistry('user-service', {
+  port: 3000,
+  weight: 100,
+  metadata: { version: '1.0.0' },
+})
+@Controller('/api/users')
+class UserController {
+  @GET('/')
+  public getUsers() {
+    return { users: [] };
+  }
+}
+
+app.registerController(UserController);
+await app.listen(3000);
+// 服务会自动注册到 Nacos
+```
+
+#### 手动注册
+
+```typescript
+import {
+  SERVICE_REGISTRY_TOKEN,
+  type ServiceRegistry,
+} from '@dangao/bun-server';
+import { Inject, Injectable } from '@dangao/bun-server';
+
+@Injectable()
+class MyService {
+  public constructor(
+    @Inject(SERVICE_REGISTRY_TOKEN) private readonly registry: ServiceRegistry,
+  ) {}
+
+  public async registerService() {
+    await this.registry.register({
+      serviceName: 'user-service',
+      ip: '127.0.0.1',
+      port: 3000,
+      weight: 100,
+      healthy: true,
+    });
+  }
+}
+```
+
+### 3. 服务发现
+
+```typescript
+import {
+  SERVICE_REGISTRY_TOKEN,
+  type ServiceRegistry,
+} from '@dangao/bun-server';
+
+const instances = await serviceRegistry.getInstances('user-service', {
+  healthyOnly: true,
+  namespaceId: 'public',
+});
+
+// 监听服务实例变更
+serviceRegistry.watchInstances('user-service', (newInstances) => {
+  console.log('Instances updated:', newInstances);
+});
+```
+
+## 完整示例
+
+```typescript
+import { Application, Controller, GET, Injectable, Inject } from '@dangao/bun-server';
+import {
+  ConfigCenterModule,
+  ServiceRegistryModule,
+  ServiceClient,
+  CONFIG_CENTER_TOKEN,
+  SERVICE_REGISTRY_TOKEN,
+  type ConfigCenter,
+  type ServiceRegistry,
+} from '@dangao/bun-server';
+
+// 注册配置中心
+ConfigCenterModule.forRoot({
+  provider: 'nacos',
+  nacos: {
+    client: {
+      serverList: ['http://localhost:8848'],
+      namespaceId: 'public',
+      username: 'nacos',
+      password: 'nacos',
+    },
+  },
+});
+
+// 注册服务注册中心
+ServiceRegistryModule.forRoot({
+  provider: 'nacos',
+  nacos: {
+    client: {
+      serverList: ['http://localhost:8848'],
+      namespaceId: 'public',
+      username: 'nacos',
+      password: 'nacos',
+    },
+  },
+});
+
+// 服务类
+@Injectable()
+class UserService {
+  private readonly serviceClient: ServiceClient;
+
+  public constructor(
+    @Inject(CONFIG_CENTER_TOKEN) private readonly configCenter: ConfigCenter,
+    @Inject(SERVICE_REGISTRY_TOKEN) private readonly serviceRegistry: ServiceRegistry,
+  ) {
+    this.serviceClient = new ServiceClient(this.serviceRegistry);
+  }
+
+  public async callOrderService() {
+    return await this.serviceClient.call({
+      serviceName: 'order-service',
+      method: 'GET',
+      path: '/api/orders',
+    });
+  }
+}
+
+// 控制器
+@ServiceRegistry('user-service', { port: 3000 })
+@Controller('/api/users')
+class UserController {
+  public constructor(private readonly userService: UserService) {}
+
+  @GET('/')
+  public async getUsers() {
+    return { users: [] };
+  }
+}
+
+// 启动应用
+const app = new Application();
+app.registerController(UserController);
+await app.listen(3000);
+```
+
+## 常见问题
+
+### 1. 连接失败
+
+**问题**：无法连接到 Nacos 服务器
+
+**解决方案**：
+- 检查 Nacos 服务器是否运行
+- 检查 `serverList` 配置是否正确
+- 检查网络连接和防火墙设置
+- 检查用户名和密码是否正确
+
+### 2. 配置获取失败
+
+**问题**：无法获取配置
+
+**解决方案**：
+- 检查配置是否在 Nacos 控制台中存在
+- 检查 Data ID 和 Group 是否正确
+- 检查命名空间是否正确
+- 检查权限设置
+
+### 3. 服务注册失败
+
+**问题**：服务无法注册到 Nacos
+
+**解决方案**：
+- 检查服务注册中心模块是否已注册
+- 检查服务名、IP、端口是否正确
+- 检查 Nacos 服务器连接是否正常
+- 查看应用日志获取详细错误信息
+
+### 4. 服务发现为空
+
+**问题**：服务发现返回空列表
+
+**解决方案**：
+- 检查服务是否已注册
+- 检查 `healthyOnly` 选项（如果设置为 true，只返回健康实例）
+- 检查命名空间和分组是否正确
+- 检查服务实例是否健康
+
+### 5. 配置热更新不生效
+
+**问题**：配置变更后应用未更新
+
+**解决方案**：
+- 检查是否启用了配置监听（`watch: true`）
+- 检查 `watchInterval` 设置是否合理
+- 检查配置监听回调是否正确实现
+- 查看日志确认配置变更是否被检测到
+
+## 参考资源
+
+- [Nacos 官方文档](https://nacos.io/docs/latest/)
+- [Nacos 3.X Open API](https://nacos.io/docs/latest/manual/user/open-api/)
+- [微服务使用指南](./microservice.md)
+- [配置中心使用指南](./microservice-config-center.md)
+- [服务注册与发现使用指南](./microservice-service-registry.md)
+

package/docs/microservice-service-registry.md

@@ -0,0 +1,306 @@
+# 服务注册与发现使用指南
+
+本文档介绍如何使用 Bun Server Framework 的服务注册与发现功能。
+
+## 目录
+
+- [概述](#概述)
+- [快速开始](#快速开始)
+- [服务注册](#服务注册)
+- [服务发现](#服务发现)
+- [负载均衡](#负载均衡)
+- [健康检查集成](#健康检查集成)
+- [最佳实践](#最佳实践)
+
+## 概述
+
+服务注册与发现提供了微服务架构中的核心能力：
+
+- **服务注册**：将服务实例注册到注册中心
+- **服务发现**：从注册中心发现服务实例
+- **负载均衡**：支持多种负载均衡策略
+- **健康检查**：自动根据健康检查状态更新服务健康状态
+- **实例监听**：监听服务实例变更
+
+## 快速开始
+
+### 1. 注册服务注册中心模块
+
+```typescript
+import { Application } from '@dangao/bun-server';
+import { ServiceRegistryModule } from '@dangao/bun-server';
+
+const app = new Application();
+
+app.registerModule(
+  ServiceRegistryModule.forRoot({
+    provider: 'nacos',
+    nacos: {
+      client: {
+        serverList: ['http://localhost:8848'],
+        namespaceId: 'public',
+        username: 'nacos',
+        password: 'nacos',
+      },
+      heartbeatInterval: 5000, // 心跳间隔（毫秒）
+    },
+  }),
+);
+```
+
+### 2. 注册服务
+
+```typescript
+import { ServiceRegistry, Controller, GET } from '@dangao/bun-server';
+
+@ServiceRegistry('user-service', {
+  port: 3000,
+  weight: 100,
+  metadata: { version: '1.0.0' },
+})
+@Controller('/api/users')
+class UserController {
+  @GET('/')
+  public getUsers() {
+    return { users: [] };
+  }
+}
+
+app.registerController(UserController);
+await app.listen(3000);
+// 服务会自动注册到注册中心
+```
+
+## 服务注册
+
+### 使用装饰器自动注册
+
+最简单的方式是使用 `@ServiceRegistry` 装饰器：
+
+```typescript
+@ServiceRegistry('user-service', {
+  port: 3000,
+  weight: 100,
+  enabled: true,
+  healthy: true,
+  metadata: {
+    version: '1.0.0',
+    region: 'us-east',
+  },
+  clusterName: 'default',
+  namespaceId: 'public',
+  groupName: 'DEFAULT_GROUP',
+})
+@Controller('/api/users')
+class UserController {
+  // ...
+}
+```
+
+**配置说明**：
+- `serviceName`：服务名（必需）
+- `port`：服务端口（可选，默认从 Application 获取）
+- `ip`：服务 IP（可选，默认从 Application 获取）
+- `weight`：服务权重（用于加权负载均衡）
+- `enabled`：是否启用
+- `healthy`：初始健康状态
+- `metadata`：服务元数据（版本、区域等）
+- `clusterName`：集群名
+- `namespaceId`：命名空间
+- `groupName`：分组名
+
+### 手动注册
+
+```typescript
+import {
+  SERVICE_REGISTRY_TOKEN,
+  type ServiceRegistry,
+  type ServiceInstance,
+} from '@dangao/bun-server';
+import { Inject, Injectable } from '@dangao/bun-server';
+
+@Injectable()
+class MyService {
+  public constructor(
+    @Inject(SERVICE_REGISTRY_TOKEN) private readonly registry: ServiceRegistry,
+  ) {}
+
+  public async registerService() {
+    const instance: ServiceInstance = {
+      serviceName: 'my-service',
+      ip: '127.0.0.1',
+      port: 3000,
+      weight: 100,
+      healthy: true,
+      enabled: true,
+      metadata: {
+        version: '1.0.0',
+      },
+    };
+
+    await this.registry.register(instance);
+  }
+
+  public async renewService() {
+    // 续约服务（心跳）
+    await this.registry.renew({
+      serviceName: 'my-service',
+      ip: '127.0.0.1',
+      port: 3000,
+    });
+  }
+
+  public async deregisterService() {
+    // 注销服务
+    await this.registry.deregister({
+      serviceName: 'my-service',
+      ip: '127.0.0.1',
+      port: 3000,
+    });
+  }
+}
+```
+
+## 服务发现
+
+### 使用装饰器自动发现
+
+使用 `@ServiceDiscovery` 装饰器自动注入服务实例列表：
+
+```typescript
+import { ServiceDiscovery, Injectable } from '@dangao/bun-server';
+import type { ServiceInstance } from '@dangao/bun-server';
+
+@Injectable()
+class MyService {
+  @ServiceDiscovery('user-service', {
+    healthyOnly: true, // 只获取健康实例
+    namespaceId: 'public',
+    groupName: 'DEFAULT_GROUP',
+  })
+  public instances: ServiceInstance[] = [];
+
+  public async getAvailableInstances() {
+    // instances 会自动更新
+    return this.instances;
+  }
+}
+```
+
+### 手动发现
+
+```typescript
+// 获取服务实例列表
+const instances = await serviceRegistry.getInstances('user-service', {
+  healthyOnly: true,
+  namespaceId: 'public',
+  groupName: 'DEFAULT_GROUP',
+  clusterName: 'default',
+});
+
+// 监听服务实例变更
+const unsubscribe = serviceRegistry.watchInstances(
+  'user-service',
+  (newInstances) => {
+    console.log('Instances updated:', newInstances);
+    // 更新本地缓存
+    updateLocalCache(newInstances);
+  },
+  {
+    namespaceId: 'public',
+    groupName: 'DEFAULT_GROUP',
+  },
+);
+
+// 取消监听
+unsubscribe();
+```
+
+## 负载均衡
+
+ServiceClient 支持多种负载均衡策略，详见[服务调用文档](./microservice.md#负载均衡)。
+
+## 健康检查集成
+
+服务注册会自动集成健康检查模块，根据健康检查状态更新服务健康状态：
+
+### 1. 注册健康检查模块
+
+```typescript
+import { HealthModule } from '@dangao/bun-server';
+
+HealthModule.forRoot({
+  indicators: [
+    {
+      name: 'db',
+      async check() {
+        // 检查数据库连接
+        const isHealthy = await checkDatabase();
+        return {
+          status: isHealthy ? 'up' : 'down',
+          details: { connection: isHealthy ? 'ok' : 'failed' },
+        };
+      },
+    },
+    {
+      name: 'cache',
+      async check() {
+        // 检查缓存连接
+        return { status: 'up' };
+      },
+    },
+  ],
+});
+```
+
+### 2. 使用 @ServiceRegistry 装饰器
+
+使用 `@ServiceRegistry` 装饰器的服务会自动根据健康检查状态更新：
+
+```typescript
+@ServiceRegistry('user-service')
+@Controller('/api/users')
+class UserController {
+  // 服务会根据健康检查状态自动更新健康状态
+}
+```
+
+### 3. 健康检查更新机制
+
+- 每 30 秒检查一次健康状态
+- 如果健康检查失败，服务会被标记为不健康
+- 不健康的服务实例不会被负载均衡器选择（如果设置了 `healthyOnly: true`）
+
+## 最佳实践
+
+### 1. 服务注册
+
+- **使用装饰器**：优先使用 `@ServiceRegistry` 装饰器自动注册
+- **配置元数据**：设置版本、区域等元数据便于管理
+- **合理权重**：根据服务实例性能设置权重
+- **自动注销**：确保应用关闭时正确注销服务
+
+### 2. 服务发现
+
+- **健康过滤**：使用 `healthyOnly: true` 只获取健康实例
+- **实例监听**：监听实例变更及时更新本地缓存
+- **命名空间**：使用命名空间区分不同环境
+
+### 3. 负载均衡
+
+- **随机**：适用于无状态服务
+- **轮询**：适用于性能相近的实例
+- **加权轮询**：适用于性能差异较大的实例
+- **一致性哈希**：适用于需要会话粘性的场景
+- **最少连接**：适用于长连接场景
+
+### 4. 健康检查
+
+- **关键依赖**：为关键依赖（数据库、缓存等）添加健康检查
+- **检查频率**：合理设置检查频率（默认 30 秒）
+- **快速失败**：健康检查应该快速失败，避免阻塞
+
+## 示例
+
+完整示例请参考 `examples/microservice-app.ts`。
+