@dangao/bun-server 1.8.0 → 1.8.2

package/docs/microservice.md

@@ -1,26 +1,26 @@
-# 微服务架构支持
+# Microservice Architecture Support
 
-Bun Server Framework 提供了完整的微服务架构支持，包括配置中心、服务注册与发现、服务调用、服务治理和可观测性等功能。
+Bun Server Framework provides comprehensive microservice architecture support, including configuration center, service registration and discovery, service invocation, service governance, and observability features.
 
-## 目录
+## Table of Contents
 
-- [快速开始](#快速开始)
-- [配置中心](#配置中心)
-- [服务注册与发现](#服务注册与发现)
-- [服务调用](#服务调用)
-- [服务治理](#服务治理)
-- [监控和追踪](#监控和追踪)
-- [最佳实践](#最佳实践)
+- [Quick Start](#quick-start)
+- [Configuration Center](#configuration-center)
+- [Service Registration and Discovery](#service-registration-and-discovery)
+- [Service Invocation](#service-invocation)
+- [Service Governance](#service-governance)
+- [Monitoring and Tracing](#monitoring-and-tracing)
+- [Best Practices](#best-practices)
 
-## 快速开始
+## Quick Start
 
-### 安装依赖
+### Install Dependencies
 
 ```bash
 bun add @dangao/bun-server
 ```
 
-### 基础示例
+### Basic Example
 
 ```typescript
 import { Application } from '@dangao/bun-server';
@@ -30,10 +30,10 @@ import {
   ServiceClient,
 } from '@dangao/bun-server';
 
-// 创建应用
+// Create application
 const app = new Application();
 
-// 注册配置中心模块
+// Register configuration center module
 app.registerModule(
   ConfigCenterModule.forRoot({
     provider: 'nacos',
@@ -48,7 +48,7 @@ app.registerModule(
   }),
 );
 
-// 注册服务注册中心模块
+// Register service registry module
 app.registerModule(
   ServiceRegistryModule.forRoot({
     provider: 'nacos',
@@ -63,13 +63,13 @@ app.registerModule(
   }),
 );
 
-// 启动应用
+// Start application
 await app.listen(3000);
 ```
 
-## 配置中心
+## Configuration Center
 
-### 基本使用
+### Basic Usage
 
 ```typescript
 import {
@@ -95,7 +95,7 @@ class MyService {
 }
 ```
 
-### 使用装饰器
+### Using Decorators
 
 ```typescript
 import { ConfigCenterValue, Injectable } from '@dangao/bun-server';
@@ -104,32 +104,32 @@ import { ConfigCenterValue, Injectable } from '@dangao/bun-server';
 class MyService {
   @ConfigCenterValue('my-config', 'DEFAULT_GROUP', {
     defaultValue: 'default-value',
-    watch: true, // 监听配置变更
+    watch: true, // Watch for configuration changes
   })
   public configValue: string = '';
 
   public getConfig() {
-    return this.configValue; // 自动从配置中心获取
+    return this.configValue; // Automatically fetched from config center
   }
 }
 ```
 
-### 配置热更新
+### Hot Configuration Update
 
-配置中心支持配置热更新，当配置变更时会自动通知应用：
+The configuration center supports hot configuration updates, automatically notifying the application when configurations change:
 
 ```typescript
 const configCenter = container.resolve<ConfigCenter>(CONFIG_CENTER_TOKEN);
 
 configCenter.watchConfig('my-config', 'DEFAULT_GROUP', (newConfig) => {
   console.log('Config updated:', newConfig.content);
-  // 更新应用配置
+  // Update application configuration
 });
 ```
 
-### ConfigModule 集成
+### ConfigModule Integration
 
-ConfigModule 支持与配置中心深度集成，配置变更会自动刷新：
+ConfigModule supports deep integration with the configuration center, automatically refreshing when configurations change:
 
 ```typescript
 import { ConfigModule } from '@dangao/bun-server';
@@ -142,16 +142,16 @@ ConfigModule.forRoot({
       ['app.name', { dataId: 'app-name', groupName: 'DEFAULT_GROUP' }],
       ['app.port', { dataId: 'app-port', groupName: 'DEFAULT_GROUP' }],
     ]),
-    configCenterPriority: true, // 配置中心配置优先级最高
+    configCenterPriority: true, // Config center has highest priority
   },
 });
 ```
 
-## 服务注册与发现
+## Service Registration and Discovery
 
-### 服务注册
+### Service Registration
 
-#### 使用装饰器自动注册
+#### Automatic Registration with Decorator
 
 ```typescript
 import { ServiceRegistry, Controller, GET } from '@dangao/bun-server';
@@ -169,13 +169,13 @@ class UserController {
   }
 }
 
-// 应用启动时会自动注册服务
+// Service will be automatically registered when application starts
 const app = new Application();
 app.registerController(UserController);
 await app.listen(3000);
 ```
 
-#### 手动注册
+#### Manual Registration
 
 ```typescript
 import {
@@ -203,9 +203,9 @@ class MyService {
 }
 ```
 
-### 服务发现
+### Service Discovery
 
-#### 使用装饰器自动发现
+#### Automatic Discovery with Decorator
 
 ```typescript
 import { ServiceDiscovery, Injectable } from '@dangao/bun-server';
@@ -214,18 +214,18 @@ import type { ServiceInstance } from '@dangao/bun-server';
 @Injectable()
 class MyService {
   @ServiceDiscovery('user-service', {
-    healthyOnly: true, // 只获取健康实例
+    healthyOnly: true, // Only get healthy instances
   })
   public instances: ServiceInstance[] = [];
 
   public async getAvailableInstances() {
-    // instances 会自动更新
+    // instances will be automatically updated
     return this.instances;
   }
 }
 ```
 
-#### 手动发现
+#### Manual Discovery
 
 ```typescript
 const instances = await serviceRegistry.getInstances('user-service', {
@@ -233,38 +233,38 @@ const instances = await serviceRegistry.getInstances('user-service', {
   namespaceId: 'public',
 });
 
-// 监听服务实例变更
+// Watch for service instance changes
 serviceRegistry.watchInstances('user-service', (newInstances) => {
   console.log('Instances updated:', newInstances);
 });
 ```
 
-### 健康检查集成
+### Health Check Integration
 
-服务注册会自动集成健康检查模块，根据健康检查状态更新服务健康状态：
+Service registration automatically integrates with the health check module, updating service health status based on health check results:
 
 ```typescript
 import { HealthModule } from '@dangao/bun-server';
 
-// 注册健康检查模块
+// Register health check module
 HealthModule.forRoot({
   indicators: [
     {
       name: 'db',
       async check() {
-        // 检查数据库连接
+        // Check database connection
         return { status: 'up' };
       },
     },
   ],
 });
 
-// 使用 @ServiceRegistry 装饰器的服务会自动根据健康检查状态更新
+// Services using @ServiceRegistry decorator will automatically update based on health check status
 ```
 
-## 服务调用
+## Service Invocation
 
-### 基本使用
+### Basic Usage
 
 ```typescript
 import {
@@ -296,7 +296,7 @@ class MyService {
 }
 ```
 
-### 使用装饰器注入
+### Using Decorator Injection
 
 ```typescript
 import { ServiceClient, Injectable } from '@dangao/bun-server';
@@ -317,12 +317,12 @@ class MyService {
 }
 ```
 
-### 负载均衡
+### Load Balancing
 
-ServiceClient 支持多种负载均衡策略：
+ServiceClient supports multiple load balancing strategies:
 
 ```typescript
-// 随机负载均衡
+// Random load balancing
 await serviceClient.call({
   serviceName: 'user-service',
   method: 'GET',
@@ -330,7 +330,7 @@ await serviceClient.call({
   loadBalanceStrategy: 'random',
 });
 
-// 轮询负载均衡
+// Round-robin load balancing
 await serviceClient.call({
   serviceName: 'user-service',
   method: 'GET',
@@ -338,7 +338,7 @@ await serviceClient.call({
   loadBalanceStrategy: 'roundRobin',
 });
 
-// 加权轮询
+// Weighted round-robin
 await serviceClient.call({
   serviceName: 'user-service',
   method: 'GET',
@@ -346,7 +346,7 @@ await serviceClient.call({
   loadBalanceStrategy: 'weightedRoundRobin',
 });
 
-// 一致性哈希（适用于需要会话粘性的场景）
+// Consistent hashing (for scenarios requiring session affinity)
 await serviceClient.call({
   serviceName: 'user-service',
   method: 'GET',
@@ -355,7 +355,7 @@ await serviceClient.call({
   consistentHashKey: 'user-id-123',
 });
 
-// 最少连接
+// Least active
 await serviceClient.call({
   serviceName: 'user-service',
   method: 'GET',
@@ -364,9 +364,9 @@ await serviceClient.call({
 });
 ```
 
-### 流式调用
+### Streaming Calls
 
-支持 Server-Sent Events 等流式响应：
+Supports streaming responses like Server-Sent Events:
 
 ```typescript
 const stream = await serviceClient.callStream({
@@ -375,7 +375,7 @@ const stream = await serviceClient.callStream({
   path: '/api/events',
 });
 
-// 读取流数据
+// Read stream data
 const reader = stream.getReader();
 while (true) {
   const { done, value } = await reader.read();
@@ -384,9 +384,9 @@ while (true) {
 }
 ```
 
-### 拦截器
+### Interceptors
 
-#### 请求拦截器
+#### Request Interceptors
 
 ```typescript
 import {
@@ -397,7 +397,7 @@ import {
 serviceClient.addRequestInterceptor(new TraceIdRequestInterceptor());
 serviceClient.addRequestInterceptor(new RequestLogInterceptor());
 
-// 自定义请求拦截器
+// Custom request interceptor
 serviceClient.addRequestInterceptor({
   async intercept(options) {
     options.headers = {
@@ -409,7 +409,7 @@ serviceClient.addRequestInterceptor({
 });
 ```
 
-#### 响应拦截器
+#### Response Interceptors
 
 ```typescript
 import {
@@ -420,10 +420,10 @@ import {
 serviceClient.addResponseInterceptor(new ResponseLogInterceptor());
 serviceClient.addResponseInterceptor(new ErrorHandlerInterceptor());
 
-// 自定义响应拦截器
+// Custom response interceptor
 serviceClient.addResponseInterceptor({
   async intercept(response) {
-    // 转换响应数据
+    // Transform response data
     return {
       ...response,
       data: transformData(response.data),
@@ -432,24 +432,27 @@ serviceClient.addResponseInterceptor({
 });
 ```
 
-## 服务治理
+## Service Governance
 
-### 熔断器
+### Circuit Breaker
 
-#### 使用装饰器
+#### Using Decorator
 
 ```typescript
 import { CircuitBreaker, Injectable } from '@dangao/bun-server';
 
 @Injectable()
 class MyService {
-  @CircuitBreaker({
-    failureThreshold: 0.5,
-    timeWindow: 60000,
-    minimumRequests: 10,
-  }, 'fallbackMethod')
+  @CircuitBreaker(
+    {
+      failureThreshold: 0.5,
+      timeWindow: 60000,
+      minimumRequests: 10,
+    },
+    'fallbackMethod',
+  )
   public async callExternalService() {
-    // 自动应用熔断保护
+    // Automatically applies circuit breaker protection
     return await externalService.call();
   }
 
@@ -459,7 +462,7 @@ class MyService {
 }
 ```
 
-#### 手动使用
+#### Manual Usage
 
 ```typescript
 import { CircuitBreaker } from '@dangao/bun-server';
@@ -474,15 +477,15 @@ const result = await circuitBreaker.execute(
     return await serviceClient.call(options);
   },
   async () => {
-    // 降级处理
+    // Fallback handling
     return { fallback: true };
   },
 );
 ```
 
-### 限流
+### Rate Limiting
 
-#### 内存限流
+#### In-Memory Rate Limiting
 
 ```typescript
 import { RateLimiter } from '@dangao/bun-server';
@@ -498,12 +501,12 @@ if (!allowed) {
 }
 ```
 
-#### 分布式限流（Redis）
+#### Distributed Rate Limiting (Redis)
 
 ```typescript
 import { RedisRateLimiter } from '@dangao/bun-server';
 
-// 需要提供 Redis 客户端
+// Redis client needs to be provided
 const redisClient = {
   get: async (key: string) => await redis.get(key),
   set: async (key: string, value: string, options?: any) => {
@@ -528,7 +531,7 @@ const rateLimiter = new RedisRateLimiter(
 const allowed = await rateLimiter.allow('service-key');
 ```
 
-### 重试策略
+### Retry Strategy
 
 ```typescript
 import {
@@ -536,34 +539,37 @@ import {
   ExponentialBackoffRetryStrategy,
 } from '@dangao/bun-server';
 
-// 固定间隔重试
+// Fixed interval retry
 const fixedRetry = new FixedIntervalRetryStrategy({
   maxRetries: 3,
   retryDelay: 1000,
 });
 
-// 指数退避重试
+// Exponential backoff retry
 const exponentialRetry = new ExponentialBackoffRetryStrategy({
   maxRetries: 3,
   baseDelay: 1000,
   maxDelay: 30000,
 });
 
-// 在 ServiceClient 中使用
+// Use in ServiceClient
 serviceClient.setDefaultRetryStrategy({
   maxRetries: 3,
   retryDelay: 1000,
   exponentialBackoff: true,
   shouldRetry: (error) => {
-    // 只对网络错误重试
-    return error.message.includes('timeout') || error.message.includes('network');
+    // Only retry on network errors
+    return (
+      error.message.includes('timeout') ||
+      error.message.includes('network')
+    );
   },
 });
 ```
 
-## 监控和追踪
+## Monitoring and Tracing
 
-### 分布式追踪
+### Distributed Tracing
 
 ```typescript
 import {
@@ -579,40 +585,40 @@ const tracer = new Tracer({
 
 tracer.addCollector(new ConsoleTraceCollector());
 
-// 在 ServiceClient 中使用
+// Use in ServiceClient
 serviceClient.setTracer(tracer);
 
-// 手动创建 Span
+// Manually create span
 const span = tracer.startSpan('my-operation', SpanKind.INTERNAL);
 tracer.setSpanTags(span.context.spanId, {
   'operation.name': 'process-data',
   'user.id': '123',
 });
-// ... 执行操作
+// ... execute operation
 tracer.endSpan(span.context.spanId, SpanStatus.OK);
 ```
 
-### 服务监控
+### Service Monitoring
 
 ```typescript
 import { ServiceMetricsCollector } from '@dangao/bun-server';
 
 const metricsCollector = new ServiceMetricsCollector({
   enabled: true,
-  autoReportToMetrics: true, // 自动上报到 MetricsModule
+  autoReportToMetrics: true, // Automatically report to MetricsModule
 });
 
-// 在 ServiceClient 中使用
+// Use in ServiceClient
 serviceClient.setMetricsCollector(metricsCollector);
 
-// 查询指标
+// Query metrics
 const allMetrics = metricsCollector.getAllMetrics();
 const healthStatus = metricsCollector.getAllHealthStatus();
 ```
 
-### Prometheus 集成
+### Prometheus Integration
 
-服务监控指标会自动上报到 MetricsModule，通过 `/metrics` 端点导出 Prometheus 格式：
+Service monitoring metrics are automatically reported to MetricsModule and exported in Prometheus format via the `/metrics` endpoint:
 
 ```typescript
 import { MetricsModule } from '@dangao/bun-server';
@@ -621,60 +627,59 @@ MetricsModule.forRoot({
   enableHttpMetrics: true,
 });
 
-// 访问 http://localhost:3000/metrics 获取 Prometheus 格式指标
+// Access http://localhost:3000/metrics to get Prometheus format metrics
 ```
 
-导出的指标包括：
-- `service_calls_total` - 服务调用总数
-- `service_calls_success_total` - 成功调用数
-- `service_calls_failure_total` - 失败调用数
-- `service_call_latency_avg_ms` - 平均延迟
-- `service_call_latency_min_ms` - 最小延迟
-- `service_call_latency_max_ms` - 最大延迟
-- `service_call_error_rate` - 错误率
-- `service_instance_healthy` - 实例健康状态
-- `service_instance_consecutive_failures` - 连续失败次数
-
-## 最佳实践
+Exported metrics include:
+- `service_calls_total` - Total service calls
+- `service_calls_success_total` - Successful calls
+- `service_calls_failure_total` - Failed calls
+- `service_call_latency_avg_ms` - Average latency
+- `service_call_latency_min_ms` - Minimum latency
+- `service_call_latency_max_ms` - Maximum latency
+- `service_call_error_rate` - Error rate
+- `service_instance_healthy` - Instance health status
+- `service_instance_consecutive_failures` - Consecutive failures
 
-### 1. 配置管理
+## Best Practices
 
-- 使用配置中心管理动态配置
-- 为不同环境使用不同的命名空间
-- 启用配置监听以实现热更新
-- 设置合理的配置优先级
+### 1. Configuration Management
 
-### 2. 服务注册
+- Use configuration center to manage dynamic configurations
+- Use different namespaces for different environments
+- Enable configuration watching for hot updates
+- Set reasonable configuration priorities
 
-- 使用 `@ServiceRegistry` 装饰器自动注册
-- 配置合理的服务元数据（版本、权重等）
-- 启用健康检查集成
-- 确保应用关闭时正确注销服务
+### 2. Service Registration
 
-### 3. 服务调用
+- Use `@ServiceRegistry` decorator for automatic registration
+- Configure reasonable service metadata (version, weight, etc.)
+- Enable health check integration
+- Ensure services are properly deregistered when application shuts down
 
-- 选择合适的负载均衡策略
-- 配置合理的超时时间
-- 使用拦截器统一处理请求/响应
-- 启用追踪和监控
+### 3. Service Invocation
 
-### 4. 服务治理
+- Choose appropriate load balancing strategy
+- Configure reasonable timeout values
+- Use interceptors for unified request/response handling
+- Enable tracing and monitoring
 
-- 为关键服务启用熔断器
-- 配置合理的限流策略
-- 实现降级处理逻辑
-- 使用重试策略处理临时故障
+### 4. Service Governance
 
-### 5. 可观测性
+- Enable circuit breaker for critical services
+- Configure reasonable rate limiting strategies
+- Implement fallback handling logic
+- Use retry strategies for temporary failures
 
-- 启用分布式追踪
-- 配置合理的采样率
-- 集成 Prometheus 监控
-- 设置告警规则
+### 5. Observability
 
-## 更多资源
+- Enable distributed tracing
+- Configure reasonable sampling rates
+- Integrate Prometheus monitoring
+- Set up alerting rules
 
-- [配置中心使用指南](./microservice-config-center.md)
-- [服务注册与发现使用指南](./microservice-service-registry.md)
-- [Nacos 集成文档](./microservice-nacos.md)
+## More Resources
 
+- [Configuration Center Guide](./zh/microservice-config-center.md)
+- [Service Registration and Discovery Guide](./zh/microservice-service-registry.md)
+- [Nacos Integration Documentation](./zh/microservice-nacos.md)