pos-system/docs/en/architecture/microservices-communication.md

Kiến trúc Giao tiếp Microservices

Các patterns và protocols giao tiếp giữa các services

Quick Overview

Hướng dẫn nhanh về các patterns giao tiếp cơ bản trong hệ thống GoodGo.

Mô hình Giao tiếp Cơ bản

graph TD
    %% Nodes
    Client[Web App / Mobile App]
    Traefik[Traefik API Gateway]
    Auth[Auth Service]
    Notify[Notification Service]

    %% Relationships
    Client -->|HTTP Request| Traefik
    Traefik -->|Routing| Auth
    Auth -.->|Internal HTTP| Notify

    %% Styles using dark color palette
    style Client fill:#1565c0,stroke:#fff,stroke-width:2px,color:#fff
    style Traefik fill:#0f4c81,stroke:#fff,stroke-width:2px,color:#fff
    style Auth fill:#283593,stroke:#fff,stroke-width:2px,color:#fff
    style Notify fill:#4527a0,stroke:#fff,stroke-width:2px,color:#fff

Giao tiếp Đồng bộ (HTTP/REST)

Các service giao tiếp đồng bộ qua HTTP REST APIs thông qua Traefik API Gateway.

Ví dụ Client → Service:

// Web App -> Auth Service
const response = await fetch('http://api.goodgo.vn/api/v1/auth/login', {
  method: 'POST',
  body: JSON.stringify({ email, password }),
});

Ví dụ Service → Service:

// Auth Service -> Notification Service
const response = await fetch('http://notification-service:5003/api/v1/notifications', {
  method: 'POST',
  headers: { 'X-Service-Auth': process.env.INTERNAL_API_KEY },
  body: JSON.stringify({ userId, message }),
});

API Gateway Routing

Traefik định tuyến requests dựa trên:

• Host header: api.goodgo.vn
• Path prefix: /api/v1/auth, /api/v1/users

Format Error Response Chuẩn

Tất cả services tuân theo định dạng error response nhất quán:

{
  "success": false,
  "error": {
    "code": "AUTH_001",
    "message": "Invalid credentials",
    "details": {}
  },
  "timestamp": "2024-01-01T00:00:00.000Z"
}

---

Sơ đồ Tổng quan

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
    
    classDef blue fill:#253041,stroke:#4b6584,color:#ffffff
    classDef orange fill:#3a2e1e,stroke:#7a5f3c,color:#ffffff
    classDef green fill:#1e3a29,stroke:#3c7a52,color:#ffffff
    
    class Gateway blue
    class Kafka orange
    class SD green

Bối cảnh Hệ thống

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")

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.

Protocols Giao tiếp

So sánh Protocols

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

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

Request-response đồng bộ sử dụng HTTP/REST.

Triển khai (.NET với IHttpClientFactory):

// EN: Service-to-service HTTP client
// VI: HTTP client cho giao tiếp giữa services
public class IamServiceClient : IIamServiceClient
{
    private readonly HttpClient _httpClient;
    private readonly ILogger<IamServiceClient> _logger;
    
    public IamServiceClient(HttpClient httpClient, ILogger<IamServiceClient> logger)
    {
        _httpClient = httpClient;
        _logger = logger;
    }
    
    public async Task<UserDto?> GetUserAsync(Guid userId, CancellationToken ct)
    {
        try
        {
            var response = await _httpClient.GetAsync($"/api/v1/users/{userId}", ct);
            response.EnsureSuccessStatusCode();
            
            return await response.Content.ReadFromJsonAsync<UserDto>(ct);
        }
        catch (HttpRequestException ex)
        {
            _logger.LogError(ex, "Failed to get user {UserId}", userId);
            throw;
        }
    }
}

// EN: Registration in Program.cs
// VI: Đăng ký trong Program.cs
builder.Services.AddHttpClient<IIamServiceClient, IamServiceClient>(client =>
{
    client.BaseAddress = new Uri("http://iam-service-net:8080");
    client.DefaultRequestHeaders.Add("X-Service-Name", "storage-service");
    client.Timeout = TimeSpan.FromSeconds(5);
})
.AddPolicyHandler(GetRetryPolicy())
.AddPolicyHandler(GetCircuitBreakerPolicy());

Pattern Event-Driven

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

Giao tiếp bất đồng bộ dựa trên events qua Kafka.

Khám phá Dịch vụ

Local (Docker Compose):

# Services discover via Docker DNS
http://service-name:port
http://iam-service:3001

Kubernetes:

# Services discover via K8s DNS
http://service-name.namespace.svc.cluster.local
http://iam-service.default.svc.cluster.local:3001

Pattern API Gateway

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]
    
    %% Dark color palette with white text
    classDef clientBlue fill:#1565c0,stroke:#fff,stroke-width:2px,color:#fff
    classDef gatewayBlue fill:#0f4c81,stroke:#fff,stroke-width:2px,color:#fff
    classDef featurePurple fill:#4527a0,stroke:#fff,stroke-width:2px,color:#fff
    classDef serviceGreen fill:#1e3a29,stroke:#3c7a52,stroke-width:2px,color:#fff
    
    class Client clientBlue
    class Gateway gatewayBlue
    class Route,LB,Auth,Rate,CORS featurePurple
    class Service1,Service2,Service1A,Service1B serviceGreen

Điểm vào duy nhất cho tất cả client requests với routing, auth, rate limiting.

Đặc điểm Hiệu suất

Kỳ vọng hiệu suất và chiến lược tối ưu cho giao tiếp giữa các services.

Chỉ số	Mục tiêu	Ghi chú
Thời gian phản hồi REST API	< 100ms	P95 cho các cuộc gọi service-to-service nội bộ
Độ trễ publish event	< 50ms	Thời gian publish tới Kafka
Service discovery lookup	< 10ms	Thời gian phân giải DNS
Chi phí routing của Gateway	< 20ms	Độ trễ thêm vào bởi Traefik
Thông lượng	10,000 req/s	Mỗi service instance
Xử lý Kafka event	< 500ms	P95 xử lý event end-to-end

Chiến lược Tối ưu:

• Connection Pooling: Tái sử dụng HTTP connections giữa services
• Circuit Breaker: Ngăn chặn cascading failures với thư viện Opossum
• Retry with Backoff: Exponential backoff cho transient failures
• Compression: Bật gzip cho payloads lớn
• Caching: Cache kết quả service discovery và responses

Cân nhắc Bảo mật

Biện pháp bảo mật để bảo vệ giao tiếp giữa các services.

Xác thực Service-to-Service

• Internal API Keys: Services xác thực sử dụng x-service-auth header
• JWT Tokens: Để truyền user context giữa services
• Mutual TLS (mTLS): Tùy chọn cho môi trường production (Kubernetes service mesh)

Bảo mật Mạng

• Network Policies: Kubernetes NetworkPolicies hạn chế traffic service-to-service
• Service Mesh: Istio/Linkerd cho security policies nâng cao (tùy chọn)
• Private Networks: Services giao tiếp trong private VPC/cluster network

Bảo vệ Dữ liệu

• Encryption in Transit: TLS 1.2+ cho mọi external communication
• Event Payload Encryption: Dữ liệu nhạy cảm được mã hóa trước khi publish tới Kafka
• API Gateway: Xử lý SSL termination và request validation

Best Practices Bảo mật

// Service client với xác thực
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 // Xác minh SSL certificates
    })
  });
}

Triển khai

Cách giao tiếp microservices được triển khai và mở rộng qua các môi trường.

graph TD
    subgraph "Production Cluster"
        LB[Load Balancer] --> Gateway[API Gateway<br/>3 replicas]
        
        Gateway --> ServiceA1[Service A<br/>Instance 1]
        Gateway --> ServiceA2[Service A<br/>Instance 2]
        Gateway --> ServiceB1[Service B<br/>Instance 1]
        Gateway --> ServiceB2[Service B<br/>Instance 2]
        
        ServiceA1 & ServiceA2 --> Kafka[Kafka Cluster<br/>3 brokers]
        ServiceB1 & ServiceB2 --> Kafka
        
        ServiceA1 & ServiceA2 --> DB[(PostgreSQL<br/>Primary + Replica)]
        ServiceB1 & ServiceB2 --> DB
        
        ServiceA1 & ServiceA2 --> Redis[(Redis Cluster<br/>3 nodes)]
        ServiceB1 & ServiceB2 --> Redis
    end
    
    %% Dark color palette with white text and white strokes
    classDef lbGrey fill:#424242,stroke:#fff,stroke-width:2px,color:#fff
    classDef gatewayBlue fill:#0f4c81,stroke:#fff,stroke-width:2px,color:#fff
    classDef servicePurple fill:#4527a0,stroke:#fff,stroke-width:2px,color:#fff
    classDef kafkaOrange fill:#3a2e1e,stroke:#fff,stroke-width:2px,color:#fff
    classDef dbGreen fill:#1e3a29,stroke:#fff,stroke-width:2px,color:#fff
    classDef redisRed fill:#3a1e1e,stroke:#fff,stroke-width:2px,color:#fff

    class LB lbGrey
    class Gateway gatewayBlue
    class ServiceA1,ServiceA2,ServiceB1,ServiceB2 servicePurple
    class Kafka kafkaOrange
    class DB dbGreen
    class Redis redisRed

Môi trường Triển khai

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

• Horizontal Pod Autoscaler (HPA): Tự động scale dựa trên CPU/memory
• Kafka Partitions: Scale event processing bằng cách tăng partitions
• Load Balancing: Cân bằng tải giữa pod replicas
• Gateway Scaling: Traefik scale độc lập với backend services

Giám sát & Khả năng quan sát

Cách giám sát và quan sát giao tiếp microservices.

Chỉ số Chính

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

Service Endpoints:

// Liveness - service có đang chạy không?
app.get('/health/live', (req, res) => {
  res.json({ status: 'ok', timestamp: new Date().toISOString() });
});

// Readiness - service có thể xử lý traffic không?
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:

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

• OpenTelemetry: Instrument tất cả service-to-service calls
• Jaeger: Hiển thị distributed traces
• Correlation IDs: Truyền qua x-correlation-id header để tracking requests

Dashboard Giám sát

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

• System Design - Kiến trúc tổng thể
• Event-Driven Architecture - Event patterns
• API Gateway Advanced - Gateway patterns
• Inter-Service Communication - Communication patterns
• Resilience Patterns - Circuit breaker, retry

---

Quick Tips

Mermaid Common Issues

• Arrow Syntax: --> (solid), -.-> (dotted), ==> (thick)
• Special Characters: Escape with quote marks "
• Subgraphs: Use subgraph "Title" ... end

Color Pattern Quick Reference

Element	Color	Hex	Stroke	Usage
Core	Blue	#253041	#4b6584	Primary components
Logic	Purple	#2e1e3a	#5f3c7a	Processing steps
Data	Green	#1e3a29	#3c7a52	Database, Cache
External	Orange	#3a2e1e	#7a5f3c	External APIs
Error	Red	#3a1e1e	#7a3c3c	Failures, Alerts

Visual Indicators

• 🔵 Blue: Core Infrastructure
• 🟢 Green: Data Operations
• 🟠 Orange: Event/External
• 🔴 Red: Critical/Error
• ⚪ Grey: Neutral/Boundary

---

Cập nhật lần cuối / Last Updated: 2026-01-14
Tác giả / Authors: GoodGo Architecture Team
Reviewers: To be assigned