服务通信与 API 网关

服务通信分同步请求与异步消息。同步调用立即得到结果，但调用方会等待下游；异步消息能削峰和解耦时间，但需要处理重复、乱序、积压和最终一致性。

协议选择

方式	适合场景	主要风险
HTTP/REST	对外 API、通用内部调用、跨语言	文档/契约漂移、调用链过长
gRPC	内部低延迟、强类型、高吞吐调用	网关/调试工具要求、版本兼容
消息队列	事件通知、削峰、耗时异步任务	重复消费、积压、顺序和一致性

不要让一笔业务经过十几个同步服务。调用链越长，整体延迟越高，可用性也更容易受单点拖累。

API 契约

• 明确路径、方法、字段、状态码、错误结构和超时。
• 新字段尽量可选，消费者应忽略不认识的字段。
• 删除/改名字段前统计消费者并设置弃用期。
• 使用 OpenAPI/Protobuf 管理契约并做兼容性测试。
• 请求携带 traceparent 或统一 Trace ID，便于跨服务关联。

API Gateway 的职责

互联网 / 客户端
  → Load Balancer / Ingress
  → API Gateway
       ├─ TLS 与身份认证
       ├─ 路由、灰度、限流
       ├─ 请求大小和超时
       └─ 访问日志与指标
  → 内部服务

Gateway 适合承担横切入口能力，不应塞入大量业务编排，否则会成为新的巨型单体。Kubernetes Ingress/Gateway API 解决流量进入集群和路由，业务 API Gateway 还可能承担用户认证、租户、配额和 API 产品治理，两者可以组合但职责不同。

运维检查

1. 客户端 DNS/TLS 是否正常。
2. Gateway 路由是否命中正确服务和版本。
3. Gateway 到下游的连接、超时、重试和连接池是否合理。
4. 下游是否返回慢、错误或被限流。
5. Trace 是否在代理和消息边界正确传播。

排障时分别测试 Gateway 入口、服务发现地址和目标实例，避免只看到客户端 502 就判断应用挂了。