docs: Thêm tài liệu mô tả các patterns và protocols giao tiếp microservices, bao gồm API Gateway, Service Discovery, hiệu suất và bảo mật.

2026-01-07 09:27:58 +07:00
parent 7217c48253
commit d8faffd41d
1 changed files with 383 additions and 0 deletions
--- a/docs/vi/architecture/microservices-communication.md
+++ b/docs/vi/architecture/microservices-communication.md
@@ -0,0 +1,383 @@
+# Giao tiếp Microservices / Microservices Communication
+
+> **VI**: Các patterns và protocols giao tiếp giữa các services
+> **EN**: Communication patterns and protocols for inter-service communication
+
+## Sơ đồ Tổng quan / Overview Diagram
+
+```mermaid
+graph TD
+    Client[Client Apps] --> Gateway[API Gateway<br/>Traefik]
+    
+    Gateway --> ServiceA[Service A]
+    Gateway --> ServiceB[Service B]
+    
+    ServiceA <-->|REST/HTTP| ServiceB
+    ServiceA -->|Events| Kafka[Kafka Broker]
+    ServiceB <-.->|Sub| Kafka
+    
+    ServiceA --> SD[Service Discovery<br/>Docker DNS / K8s DNS]
+    ServiceB --> SD
+    
+    style Gateway fill:#e1f5ff
+    style Kafka fill:#fff4e1
+    style SD fill:#d4edda
+```
+
+## Bối cảnh Hệ thống / System Context
+
+```mermaid
+C4Context
+    title System Context Diagram for GoodGo Microservices Communication
+    
+    Person(client_web, "Web Client", "Browser/Mobile App")
+    Person(client_api, "API Consumer", "External API clients")
+    
+    System_Boundary(goodgo, "GoodGo Platform") {
+        System(gateway, "API Gateway", "Traefik - Routes requests to services")
+        System(services, "Microservices", "IAM, User, Order, Product services")
+        System(kafka, "Event Bus", "Kafka - Async communication")
+        System(discovery, "Service Discovery", "Docker DNS / K8s DNS")
+    }
+    
+    System_Ext(db, "Database", "Neon PostgreSQL")
+    System_Ext(cache, "Cache", "Redis")
+    System_Ext(external_api, "External APIs", "Payment, Email, SMS")
+    
+    Rel(client_web, gateway, "Uses", "HTTPS")
+    Rel(client_api, gateway, "Calls", "HTTPS/REST")
+    Rel(gateway, services, "Routes to", "HTTP")
+    Rel(services, kafka, "Pub/Sub", "Kafka Protocol")
+    Rel(services, discovery, "Lookup", "DNS")
+    Rel(services, db, "Reads/Writes", "PostgreSQL")
+    Rel(services, cache, "Gets/Sets", "Redis Protocol")
+    Rel(services, external_api, "Integrates", "HTTPS")
+```
+
+**VI**: Nền tảng GoodGo sử dụng kiến trúc microservices nơi tất cả client requests đi qua API Gateway (Traefik), được route đến các microservices phù hợp. Các services giao tiếp đồng bộ qua REST/HTTP cho patterns request-response và bất đồng bộ qua Kafka cho workflows event-driven. Service discovery được xử lý bởi Docker DNS trong môi trường local và Kubernetes DNS trong production.
+
+**EN**: The GoodGo platform uses a microservices architecture where all client requests flow through an API Gateway (Traefik), which routes them to appropriate microservices. Services communicate synchronously via REST/HTTP for request-response patterns and asynchronously via Kafka for event-driven workflows. Service discovery is handled by Docker DNS in local environments and Kubernetes DNS in production.
+
+## Protocols Giao tiếp / Communication Protocols
+
+### So sánh Protocols / Protocol Comparison
+
+| Protocol | Latency | Complexity | Use Case |
+|----------|---------|------------|----------|
+| **REST** | Medium | Low | External APIs, CRUD |
+| **gRPC** | Low | High | Internal high-performance |
+| **Events** | Async | Medium | Decoupled workflows |
+| **GraphQL** | Medium | Medium | Complex data fetching |
+
+### Pattern REST/HTTP
+
+```mermaid
+sequenceDiagram
+    participant Client
+    participant Gateway as API Gateway
+    participant ServiceA as Service A
+    participant ServiceB as Service B
+    
+    Client->>Gateway: GET /api/v1/users/123
+    Gateway->>ServiceA: Forward Request
+    ServiceA->>ServiceB: GET /internal/permissions/123
+    ServiceB-->>ServiceA: Permissions
+    ServiceA-->>Gateway: User + Permissions
+    Gateway-->>Client: JSON Response
+```
+
+**VI**: Request-response đồng bộ sử dụng HTTP/REST.
+
+**EN**: Synchronous request-response using HTTP/REST.
+
+**Triển khai / Implementation**:
+```typescript
+// Service-to-service HTTP client
+import axios from 'axios';
+
+export class UserServiceClient {
+  private client = axios.create({
+    baseURL: process.env.USER_SERVICE_URL,
+    timeout: 5000,
+    headers: {
+      'x-service-auth': process.env.INTERNAL_API_KEY
+    }
+  });
+  
+  async getUser(userId: string): Promise<User> {
+    const response = await this.client.get(`/users/${userId}`);
+    return response.data;
+  }
+}
+```
+
+### Pattern Event-Driven
+
+```mermaid
+sequenceDiagram
+    participant ServiceA
+    participant Kafka
+    participant ServiceB
+    participant ServiceC
+    
+    ServiceA->>Kafka: Publish: user.created
+    Kafka->>ServiceB: Deliver event
+    Kafka->>ServiceC: Deliver event
+    
+    par Parallel Processing
+        ServiceB->>ServiceB: Send welcome email
+        ServiceC->>ServiceC: Create user profile
+    end
+```
+
+**VI**: Giao tiếp bất đồng bộ dựa trên events qua Kafka.
+
+**EN**: Asynchronous event-based communication via Kafka.
+
+### Khám phá Dịch vụ / Service Discovery
+
+**Local (Docker Compose)**:
+```yaml
+# Services discover via Docker DNS
+http://service-name:port
+http://iam-service:3001
+```
+
+**Kubernetes**:
+```yaml
+# Services discover via K8s DNS
+http://service-name.namespace.svc.cluster.local
+http://iam-service.default.svc.cluster.local:3001
+```
+
+## Pattern API Gateway
+
+```mermaid
+graph LR
+    Client --> Gateway[API Gateway<br/>Traefik]
+    
+    subgraph "Gateway Features"
+        Gateway --> Route[Routing]
+        Gateway --> LB[Load Balancing]
+        Gateway --> Auth[Authentication]
+        Gateway --> Rate[Rate Limiting]
+        Gateway --> CORS
+    end
+    
+    Route --> Service1[Service 1]
+    Route --> Service2[Service 2]
+    LB --> Service1A[Instance A]
+    LB --> Service1B[Instance B]
+    
+    style Gateway fill:#e1f5ff
+```
+
+**VI**: Điểm vào duy nhất cho tất cả client requests với routing, auth, rate limiting.
+
+**EN**: Single entry point for all client requests with routing, auth, rate limiting.
+
+## Đặc điểm Hiệu suất / Performance Characteristics
+
+**VI**: Kỳ vọng hiệu suất và chiến lược tối ưu cho giao tiếp giữa các services.
+
+**EN**: Performance expectations and optimization strategies for inter-service communication.
+
+| Chỉ số / Metric | Mục tiêu / Target | Ghi chú / Notes |
+|------------------|-------------------|-----------------|
+| **Thời gian phản hồi REST API / REST API Response Time** | < 100ms | P95 for internal service-to-service calls |
+| **Độ trễ publish event / Event Publishing Latency** | < 50ms | Time to publish to Kafka |
+| **Service discovery lookup** | < 10ms | DNS resolution time |
+| **Chi phí routing của Gateway / Gateway Routing Overhead** | < 20ms | Additional latency added by Traefik |
+| **Thông lượng / Throughput** | 10,000 req/s | Per service instance |
+| **Xử lý Kafka event / Kafka Event Processing** | < 500ms | P95 end-to-end event processing |
+
+**Chiến lược Tối ưu / Optimization Strategies**:
+- **Connection Pooling**: Reuse HTTP connections between services / Tái sử dụng HTTP connections giữa services
+- **Circuit Breaker**: Prevent cascading failures with Opossum library / Ngăn chặn cascading failures với thư viện Opossum
+- **Retry with Backoff**: Exponential backoff for transient failures / Exponential backoff cho transient failures
+- **Compression**: Enable gzip for large payloads / Bật gzip cho payloads lớn
+- **Caching**: Cache service discovery results and responses / Cache kết quả service discovery và responses
+
+## Cân nhắc Bảo mật / Security Considerations
+
+**VI**: Biện pháp bảo mật để bảo vệ giao tiếp giữa các services.
+
+**EN**: Security measures for protecting inter-service communication.
+
+### Xác thực Service-to-Service / Service-to-Service Authentication
+
+- **Internal API Keys**: Services authenticate using `x-service-auth` header / Services xác thực sử dụng `x-service-auth` header
+- **JWT Tokens**: For user context propagation between services / Để truyền user context giữa services
+- **Mutual TLS (mTLS)**: Optional for production environments (Kubernetes service mesh) / Tùy chọn cho môi trường production
+
+### Bảo mật Mạng / Network Security
+
+- **Network Policies**: Kubernetes NetworkPolicies restrict service-to-service traffic / Hạn chế traffic service-to-service
+- **Service Mesh**: Istio/Linkerd for advanced security policies (optional) / Cho security policies nâng cao (tùy chọn)
+- **Private Networks**: Services communicate within private VPC/cluster network / Services giao tiếp trong private VPC/cluster network
+
+### Bảo vệ Dữ liệu / Data Protection
+
+- **Encryption in Transit**: TLS 1.2+ for all external communication / TLS 1.2+ cho mọi external communication
+- **Event Payload Encryption**: Sensitive data encrypted before publishing to Kafka / Dữ liệu nhạy cảm được mã hóa trước khi publish tới Kafka
+- **API Gateway**: Traefik handles SSL termination and request validation / Xử lý SSL termination và request validation
+
+### Best Practices Bảo mật / Security Best Practices
+
+```typescript
+// VI: Service client với xác thực
+// EN: Service client with authentication
+export class SecureServiceClient {
+  private client = axios.create({
+    baseURL: process.env.SERVICE_URL,
+    timeout: 5000,
+    headers: {
+      'x-service-auth': process.env.INTERNAL_API_KEY,
+      'x-correlation-id': generateCorrelationId()
+    },
+    httpsAgent: new https.Agent({
+      rejectUnauthorized: true // VI: Xác minh SSL certificates / EN: Verify SSL certificates
+    })
+  });
+}
+```
+
+## Triển khai / Deployment
+
+**VI**: Cách giao tiếp microservices được triển khai và mở rộng qua các môi trường.
+
+**EN**: How microservices communication is deployed and scaled across environments.
+
+```mermaid
+graph TD
+    subgraph "Production Cluster"
+        LB[Load Balancer] --> Gateway[API Gateway\n3 replicas]
+        
+        Gateway --> ServiceA1[Service A\nInstance 1]
+        Gateway --> ServiceA2[Service A\nInstance 2]
+        Gateway --> ServiceB1[Service B\nInstance 1]
+        Gateway --> ServiceB2[Service B\nInstance 2]
+        
+        ServiceA1 & ServiceA2 --> Kafka[Kafka Cluster\n3 brokers]
+        ServiceB1 & ServiceB2 --> Kafka
+        
+        ServiceA1 & ServiceA2 --> DB[(PostgreSQL\nPrimary + Replica)]
+        ServiceB1 & ServiceB2 --> DB
+        
+        ServiceA1 & ServiceA2 --> Redis[(Redis Cluster\n3 nodes)]
+        ServiceB1 & ServiceB2 --> Redis
+    end
+    
+    style Gateway fill:#e1f5ff
+    style Kafka fill:#fff4e1
+    style DB fill:#d4edda
+    style Redis fill:#ffe1e1
+```
+
+### Môi trường Triển khai / Deployment Environments
+
+| Environment | Gateway | Services | Kafka | Service Discovery |
+|-------------|---------|----------|-------|-------------------|
+| **Local** | Traefik (Docker) | Single instance per service | Single broker | Docker DNS |
+| **Staging** | Traefik (2 replicas) | 2 replicas per service | 3 brokers | Kubernetes DNS |
+| **Production** | Traefik (3+ replicas) | 3+ replicas per service | 5+ brokers | Kubernetes DNS + Service Mesh |
+
+### Chiến lược Mở rộng / Scaling Strategy
+
+- **Horizontal Pod Autoscaler (HPA)**: Auto-scale based on CPU/memory / Tự động scale dựa trên CPU/memory
+- **Kafka Partitions**: Scale event processing by increasing partitions / Scale event processing bằng cách tăng partitions
+- **Load Balancing**: Kubernetes Service load balances across pod replicas / Cân bằng tải giữa pod replicas
+- **Gateway Scaling**: Traefik scales independently from backend services / Traefik scale độc lập với backend services
+
+## Giám sát & Khả năng quan sát / Monitoring & Observability
+
+**VI**: Cách giám sát và quan sát giao tiếp microservices.
+
+**EN**: How to monitor and observe microservices communication.
+
+### Chỉ số Chính / Key Metrics
+
+**Service-to-Service Metrics**:
+- `http_request_duration_seconds` - Request latency histogram
+- `http_requests_total` - Total requests counter
+- `http_request_errors_total` - Failed requests counter
+- `service_client_timeout_total` - Timeout counter
+
+**Gateway Metrics**:
+- `traefik_service_requests_total` - Requests per service
+- `traefik_service_request_duration_seconds` - Routing latency
+- `traefik_service_retries_total` - Retry attempts
+
+**Kafka Metrics**:
+- `kafka_producer_record_send_total` - Events published
+- `kafka_consumer_lag` - Consumer lag
+- `kafka_consumer_records_consumed_total` - Events consumed
+
+### Kiểm tra Sức khỏe / Health Checks
+
+**Service Endpoints**:
+```typescript
+// VI: Liveness - service có đang chạy không?
+// EN: Liveness - is service running?
+app.get('/health/live', (req, res) => {
+  res.json({ status: 'ok', timestamp: new Date().toISOString() });
+});
+
+// VI: Readiness - service có thể xử lý traffic không?
+// EN: Readiness - can service handle traffic?
+app.get('/health/ready', async (req, res) => {
+  const checks = {
+    database: await checkDatabase(),
+    redis: await checkRedis(),
+    kafka: await checkKafka()
+  };
+  
+  const healthy = Object.values(checks).every(c => c);
+  res.status(healthy ? 200 : 503).json({ ready: healthy, checks });
+});
+```
+
+**Kubernetes Probes**:
+```yaml
+livenessProbe:
+  httpGet:
+    path: /health/live
+    port: 3000
+  initialDelaySeconds: 30
+  periodSeconds: 10
+
+readinessProbe:
+  httpGet:
+    path: /health/ready
+    port: 3000
+  initialDelaySeconds: 5
+  periodSeconds: 5
+```
+
+### Tracing Phân tán / Distributed Tracing
+
+- **OpenTelemetry**: Instrument all service-to-service calls / Instrument tất cả service-to-service calls
+- **Jaeger**: Visualize distributed traces / Hiển thị distributed traces
+- **Correlation IDs**: Propagate via `x-correlation-id` header for request tracking / Truyền qua `x-correlation-id` header để tracking requests
+
+### Dashboard Giám sát / Monitoring Dashboard
+
+**Grafana Panels**:
+- Service Communication Overview (request rate, latency, errors)
+- Gateway Performance (routing time, backend health)
+- Event Bus Health (Kafka lag, throughput)
+- Service Dependencies (service map from traces)
+
+## Tài liệu Liên quan / Related Documentation
+
+- [System Design](./system-design.md) - Overall architecture / Kiến trúc tổng thể
+- [Event-Driven Architecture](./event-driven-architecture.md) - Event patterns
+- [API Gateway Advanced](../skills/api-gateway-advanced.md) - Gateway patterns
+- [Inter-Service Communication](../skills/inter-service-communication.md) - Communication patterns
+- [Resilience Patterns](../skills/resilience-patterns.md) - Circuit breaker, retry
+
+---
+
+**Cập nhật lần cuối / Last Updated**: 2026-01-07  
+**Tác giả / Authors**: GoodGo Architecture Team  
+**Reviewers**: To be assigned