@umacloud/knowledge 1.0.1

package/development/01-standards/microservices-communication.md

@@ -0,0 +1,502 @@
+---
+id: microservices-communication
+title: 微服务通信模式
+domain: development
+category: 01-standards
+difficulty: intermediate
+tags: [agent, checklist, communication, development, microservices, 场景选型指南, 实战代码示例, 常见陷阱]
+quality_score: 70
+last_updated: 2026-06-15
+---
+# 微服务通信模式
+
+## 概述
+微服务间的通信方式直接影响系统的性能、可靠性和可维护性。本指南覆盖REST、gRPC、GraphQL、事件驱动、消息队列五种核心通信模式,提供选型矩阵和实战代码。
+
+## 核心概念
+
+### 1. 通信模式分类
+- **同步通信**: 调用方等待响应 — REST/gRPC/GraphQL
+- **异步通信**: 调用方不等待响应 — 消息队列/事件驱动
+- **请求-响应**: 一对一通信 — HTTP/gRPC
+- **发布-订阅**: 一对多广播 — Kafka/RabbitMQ/NATS
+- **事件溯源**: 状态变更序列 — Event Store/Kafka
+
+### 2. 通信方式对比
+
+| 特性 | REST | gRPC | GraphQL | 消息队列 | 事件驱动 |
+|------|------|------|---------|----------|----------|
+| 模式 | 同步 | 同步/流 | 同步 | 异步 | 异步 |
+| 协议 | HTTP/1.1+ | HTTP/2 | HTTP | AMQP/自定义 | 自定义 |
+| 序列化 | JSON | Protobuf | JSON | 灵活 | 灵活 |
+| 性能 | 中 | 高 | 中 | 高 | 高 |
+| 类型安全 | 弱(需OpenAPI) | 强(.proto) | 中(Schema) | 弱 | 弱(需Schema) |
+| 浏览器支持 | 完美 | 需gRPC-Web | 完美 | 不直接 | WebSocket |
+| 学习曲线 | 低 | 中 | 中 | 中 | 高 |
+| 适用场景 | CRUD/公开API | 内部高频调用 | BFF/聚合 | 解耦/削峰 | 事件流 |
+
+### 3. 通信拓扑
+- **点对点**: 服务直接调用,简单但耦合
+- **API Gateway**: 统一入口,聚合转发
+- **Service Mesh**: Sidecar代理,透明通信(Istio/Linkerd)
+- **Event Bus**: 中心化事件总线(Kafka/RabbitMQ)
+
+## 实战代码示例
+
+### REST — 标准HTTP通信
+
+```python
+# 服务A调用服务B(httpx异步客户端)
+import httpx
+from tenacity import retry, stop_after_attempt, wait_exponential
+from circuitbreaker import circuit
+
+class UserServiceClient:
+    """用户服务HTTP客户端"""
+
+    def __init__(self, base_url: str = "http://user-service:8080"):
+        self.base_url = base_url
+        self.client = httpx.AsyncClient(
+            base_url=base_url,
+            timeout=httpx.Timeout(connect=5.0, read=10.0, write=5.0, pool=5.0),
+            limits=httpx.Limits(max_connections=100, max_keepalive_connections=20),
+        )
+
+    @retry(stop=stop_after_attempt(3), wait=wait_exponential(multiplier=1, max=10))
+    @circuit(failure_threshold=5, recovery_timeout=30)
+    async def get_user(self, user_id: int) -> dict:
+        response = await self.client.get(f"/api/v1/users/{user_id}")
+        response.raise_for_status()
+        return response.json()
+
+    @retry(stop=stop_after_attempt(3), wait=wait_exponential(multiplier=1, max=10))
+    async def create_user(self, data: dict) -> dict:
+        response = await self.client.post("/api/v1/users", json=data)
+        response.raise_for_status()
+        return response.json()
+
+    async def close(self):
+        await self.client.aclose()
+```
+
+### gRPC — 高性能内部通信
+
+```protobuf
+// user.proto
+syntax = "proto3";
+package user.v1;
+
+service UserService {
+  rpc GetUser(GetUserRequest) returns (GetUserResponse);
+  rpc CreateUser(CreateUserRequest) returns (CreateUserResponse);
+  rpc ListUsers(ListUsersRequest) returns (stream UserResponse);  // 服务端流
+  rpc Chat(stream ChatMessage) returns (stream ChatMessage);       // 双向流
+}
+
+message GetUserRequest {
+  int64 user_id = 1;
+}
+
+message GetUserResponse {
+  int64 id = 1;
+  string full_name = 2;
+  string email = 3;
+  UserProfile profile = 4;
+}
+
+message UserProfile {
+  string avatar_url = 1;
+  string bio = 2;
+}
+
+message ListUsersRequest {
+  int32 page_size = 1;
+  string page_token = 2;
+}
+
+message UserResponse {
+  int64 id = 1;
+  string full_name = 2;
+}
+```
+
+```python
+# gRPC服务端(Python)
+import grpc
+from concurrent import futures
+import user_pb2
+import user_pb2_grpc
+
+class UserServiceServicer(user_pb2_grpc.UserServiceServicer):
+
+    async def GetUser(self, request, context):
+        user = await db.get_user(request.user_id)
+        if not user:
+            context.set_code(grpc.StatusCode.NOT_FOUND)
+            context.set_details(f"User {request.user_id} not found")
+            return user_pb2.GetUserResponse()
+        return user_pb2.GetUserResponse(
+            id=user.id,
+            full_name=user.full_name,
+            email=user.email,
+        )
+
+    async def ListUsers(self, request, context):
+        """服务端流式返回用户列表"""
+        async for user in db.stream_users(
+            page_size=request.page_size,
+            page_token=request.page_token,
+        ):
+            yield user_pb2.UserResponse(
+                id=user.id,
+                full_name=user.full_name,
+            )
+
+async def serve():
+    server = grpc.aio.server(futures.ThreadPoolExecutor(max_workers=10))
+    user_pb2_grpc.add_UserServiceServicer_to_server(UserServiceServicer(), server)
+    server.add_insecure_port('[::]:50051')
+    await server.start()
+    await server.wait_for_termination()
+```
+
+```python
+# gRPC客户端
+import grpc
+import user_pb2
+import user_pb2_grpc
+
+async def get_user(user_id: int):
+    async with grpc.aio.insecure_channel('user-service:50051') as channel:
+        stub = user_pb2_grpc.UserServiceStub(channel)
+        try:
+            response = await stub.GetUser(
+                user_pb2.GetUserRequest(user_id=user_id),
+                timeout=5.0,
+            )
+            return {"id": response.id, "name": response.full_name}
+        except grpc.aio.AioRpcError as e:
+            if e.code() == grpc.StatusCode.NOT_FOUND:
+                return None
+            raise
+```
+
+### GraphQL — BFF聚合层
+
+```python
+# Strawberry GraphQL(Python)
+import strawberry
+from strawberry.fastapi import GraphQLRouter
+
+@strawberry.type
+class User:
+    id: int
+    name: str
+    email: str
+    orders: list["Order"]
+
+@strawberry.type
+class Order:
+    id: int
+    total: float
+    status: str
+    items: list["OrderItem"]
+
+@strawberry.type
+class OrderItem:
+    product_name: str
+    quantity: int
+    price: float
+
+@strawberry.type
+class Query:
+    @strawberry.field
+    async def user(self, id: int, info: strawberry.types.Info) -> User:
+        """聚合用户服务+订单服务"""
+        # 调用用户微服务
+        user_data = await info.context["user_client"].get_user(id)
+
+        # DataLoader批量加载订单(避免N+1)
+        orders = await info.context["order_loader"].load(id)
+
+        return User(
+            id=user_data["id"],
+            name=user_data["name"],
+            email=user_data["email"],
+            orders=orders,
+        )
+
+schema = strawberry.Schema(query=Query)
+graphql_app = GraphQLRouter(schema)
+```
+
+### 消息队列 — RabbitMQ
+
+```python
+# 生产者(发送订单创建事件)
+import aio_pika
+import json
+
+async def publish_order_created(order: dict):
+    connection = await aio_pika.connect_robust("amqp://guest:guest@rabbitmq/")
+    async with connection:
+        channel = await connection.channel()
+        exchange = await channel.declare_exchange(
+            "orders", aio_pika.ExchangeType.TOPIC, durable=True
+        )
+        message = aio_pika.Message(
+            body=json.dumps({
+                "event": "order.created",
+                "data": order,
+                "timestamp": datetime.now().isoformat(),
+                "correlation_id": str(uuid.uuid4()),
+            }).encode(),
+            delivery_mode=aio_pika.DeliveryMode.PERSISTENT,
+            content_type="application/json",
+        )
+        await exchange.publish(message, routing_key="order.created")
+
+# 消费者(处理订单创建事件)
+async def consume_orders():
+    connection = await aio_pika.connect_robust("amqp://guest:guest@rabbitmq/")
+    async with connection:
+        channel = await connection.channel()
+        await channel.set_qos(prefetch_count=10)
+
+        exchange = await channel.declare_exchange(
+            "orders", aio_pika.ExchangeType.TOPIC, durable=True
+        )
+        queue = await channel.declare_queue(
+            "notification-service.order-created",
+            durable=True,
+            arguments={"x-dead-letter-exchange": "orders-dlx"},
+        )
+        await queue.bind(exchange, routing_key="order.created")
+
+        async with queue.iterator() as queue_iter:
+            async for message in queue_iter:
+                async with message.process(requeue=False):
+                    try:
+                        data = json.loads(message.body)
+                        await send_order_notification(data["data"])
+                    except Exception as e:
+                        logger.error(f"Failed to process message: {e}")
+                        # 消息会进入死信队列
+                        raise
+```
+
+### 事件驱动 — Kafka
+
+```python
+# Kafka生产者
+from aiokafka import AIOKafkaProducer
+import json
+
+class EventPublisher:
+    def __init__(self):
+        self.producer = AIOKafkaProducer(
+            bootstrap_servers='kafka:9092',
+            value_serializer=lambda v: json.dumps(v).encode(),
+            key_serializer=lambda k: k.encode() if k else None,
+            acks='all',  # 等待所有副本确认
+            enable_idempotence=True,  # 幂等生产者
+        )
+
+    async def start(self):
+        await self.producer.start()
+
+    async def publish(self, topic: str, event: dict, key: str = None):
+        await self.producer.send_and_wait(
+            topic=topic,
+            value={
+                "event_id": str(uuid.uuid4()),
+                "event_type": event["type"],
+                "data": event["data"],
+                "timestamp": datetime.now().isoformat(),
+                "source": "order-service",
+            },
+            key=key,
+        )
+
+# Kafka消费者
+from aiokafka import AIOKafkaConsumer
+
+class EventConsumer:
+    def __init__(self, topics: list[str], group_id: str):
+        self.consumer = AIOKafkaConsumer(
+            *topics,
+            bootstrap_servers='kafka:9092',
+            group_id=group_id,
+            auto_offset_reset='earliest',
+            enable_auto_commit=False,
+            value_deserializer=lambda v: json.loads(v.decode()),
+        )
+        self.handlers: dict[str, Callable] = {}
+
+    def on(self, event_type: str, handler: Callable):
+        self.handlers[event_type] = handler
+
+    async def start(self):
+        await self.consumer.start()
+        try:
+            async for msg in self.consumer:
+                event = msg.value
+                handler = self.handlers.get(event["event_type"])
+                if handler:
+                    try:
+                        await handler(event["data"])
+                        await self.consumer.commit()
+                    except Exception as e:
+                        logger.error(f"Handler failed: {e}", extra={"event": event})
+                        # 实现重试或发送到死信主题
+                else:
+                    logger.warning(f"No handler for: {event['event_type']}")
+                    await self.consumer.commit()
+        finally:
+            await self.consumer.stop()
+
+# 使用
+consumer = EventConsumer(["orders"], group_id="inventory-service")
+consumer.on("order.created", handle_order_created)
+consumer.on("order.cancelled", handle_order_cancelled)
+await consumer.start()
+```
+
+## 场景选型指南
+
+### 选REST当
+- 面向外部的公开API
+- CRUD为主的简单服务间调用
+- 需要浏览器直接访问
+- 团队对HTTP/JSON最熟悉
+
+### 选gRPC当
+- 内部服务间高频调用(延迟敏感)
+- 需要流式通信(实时数据推送)
+- 多语言微服务(proto生成多语言代码)
+- 需要强类型契约
+
+### 选GraphQL当
+- BFF(Backend for Frontend)聚合层
+- 客户端需要灵活查询不同字段组合
+- 移动端需要减少请求次数和数据量
+- 多个前端消费同一API
+
+### 选消息队列(RabbitMQ)当
+- 需要任务队列(邮件发送/图片处理)
+- 需要精确的消息路由(Topic/Header)
+- 需要消息确认和重试机制
+- 中小规模,延迟要求不极端
+
+### 选事件流(Kafka)当
+- 大规模事件流处理(日志/点击流)
+- 需要事件重放(新消费者从头消费)
+- 需要高吞吐(百万级/秒)
+- 事件溯源(Event Sourcing)架构
+
+## 最佳实践
+
+### 1. 服务间调用韧性
+- 设置合理的超时(connect/read/write分开)
+- 实现重试(指数退避+抖动)
+- 使用断路器(防止级联故障)
+- 实现降级策略(返回缓存/默认值)
+
+### 2. 消息可靠性
+- 生产者: 确认机制(acks=all)
+- 消费者: 手动提交offset
+- 死信队列处理失败消息
+- 幂等消费(用event_id去重)
+
+### 3. 契约管理
+- REST: OpenAPI/Swagger规范
+- gRPC: .proto文件版本管理
+- GraphQL: Schema注册中心
+- 事件: Schema Registry(Avro/JSON Schema)
+
+### 4. 可观测性
+- 分布式追踪(传播trace_id/correlation_id)
+- 每次跨服务调用记录日志
+- 监控延迟/错误率/吞吐量
+- 消息队列监控积压(consumer lag)
+
+## 常见陷阱
+
+### 陷阱1: 分布式事务不一致
+```python
+# 错误: 跨服务同步调用假装是事务
+def create_order(data):
+    order = order_service.create(data)
+    payment = payment_service.charge(order)  # 如果这里失败?
+    inventory = inventory_service.deduct(order)  # 这里又失败?
+
+# 正确: 使用Saga模式
+async def create_order_saga(data):
+    order = await order_service.create(data, status="pending")
+    try:
+        await payment_service.charge(order)
+        await inventory_service.reserve(order)
+        await order_service.confirm(order.id)
+    except Exception:
+        await order_service.cancel(order.id)
+        await payment_service.refund(order)  # 补偿操作
+```
+
+### 陷阱2: 同步调用链过深
+```
+# 错误: A→B→C→D→E 链式同步调用
+# 总延迟 = A + B + C + D + E,任何一个挂掉全链失败
+
+# 正确: 异步解耦非关键路径
+# A→B(同步,关键路径) → 发事件 → C/D/E异步处理
+```
+
+### 陷阱3: 消息顺序假设
+```python
+# 错误: 假设消息总是按发送顺序到达
+# 在多分区/多消费者场景下顺序不保证
+
+# 正确: 需要顺序时使用相同的partition key
+await producer.send("orders", value=event, key=str(order_id))
+# 同一order_id的事件会进入同一分区,保证顺序
+```
+
+### 陷阱4: 忽略幂等性
+```python
+# 错误: 重复消费导致重复扣款
+async def handle_payment(event):
+    await charge_user(event["user_id"], event["amount"])
+
+# 正确: 幂等处理
+async def handle_payment(event):
+    if await is_processed(event["event_id"]):
+        return  # 已处理,跳过
+    await charge_user(event["user_id"], event["amount"])
+    await mark_processed(event["event_id"])
+```
+
+## Agent Checklist
+
+### 通信方式选择
+- [ ] 根据场景选择合适的通信模式(同步/异步)
+- [ ] 评估延迟/吞吐/可靠性需求
+- [ ] 确认团队对选定技术的熟悉度
+- [ ] 考虑运维复杂度(消息队列需要额外基础设施)
+
+### 韧性设计
+- [ ] 超时配置合理(分层超时)
+- [ ] 重试策略实现(指数退避+抖动)
+- [ ] 断路器配置(失败阈值/恢复时间)
+- [ ] 降级策略明确(缓存/默认值/跳过)
+
+### 消息可靠性
+- [ ] 生产者确认机制启用
+- [ ] 消费者手动提交offset
+- [ ] 死信队列已配置
+- [ ] 幂等消费已实现
+
+### 可观测性
+- [ ] 分布式追踪贯穿调用链
+- [ ] 跨服务调用有日志和指标
+- [ ] 消息积压有监控告警
+- [ ] 错误率和延迟有仪表盘