外观模式用于统一微服务HTTP调用的超时、重试、熔断、链路追踪与Header透传等交叉关注点，避免逻辑散落；ServiceClient.Do()强制收口所有出站请求，区分4xx/5xx/传输层错误以适配不同重试策略，并自动透传OpenTelemetry上下文。
为什么不用 http.Client 直接调用，而要套一层外观？
因为微服务间调用不是发个请求就完事——超时控制、重试策略、熔断降级、链路追踪注入、Header 透传（比如 X-Request-ID、X-B3-TraceId）这些逻辑一旦散落在各处，改一个超时时间就得 grep 十几个文件。外观模式在这里不是为了“设计感”，是为把「必须统一」的交叉关注点收口到一个地方。
常见错误现象：context.DeadlineExceeded 在业务代码里到处 if err == context.DeadlineExceeded 判断；下游服务挂了，上游还在疯狂重试；Trace ID 在日志里断掉，排查时找不到完整链路。
- 所有出站 HTTP 调用必须走封装后的
ServiceClient.Do()，禁止直接 newhttp.Client - 外观层不暴露底层
http.RoundTripper或http.Transport，只通过构造函数参数配置超时、重试次数、是否启用熔断 - 默认开启
context.WithTimeout包裹，且 timeout 值由服务等级协议（SLA）决定，不是拍脑袋写个 5s
ServiceClient 怎么处理下游返回的 4xx/5xx 和连接失败
外观层必须区分三类错误：客户端错（4xx）、服务端错（5xx）、传输层错（连接拒绝、DNS 失败、TLS 握手超时）。它们的重试策略完全不同——400/401/403 绝对不能重试，502/503 可以重试，而 net/http: request canceled 或 i/o timeout 得结合熔断器判断是否跳过重试。
容易踩的坑：把所有 error 都塞进同一个重试逻辑，结果用户输错 token 导致每秒重试 10 次，触发下游鉴权服务限流。
立即学习“go语言免费学习笔记（深入）”；
- 用
errors.As()分离标准 Go error 类型：*url.Error、*net.OpError、net/http.ProtocolError - 对 5xx 响应体做轻量解析（只读
Status和Content-Type），避免无脑读Body导致连接无法复用 - 重试前检查熔断器状态，用
github.com/sony/gobreaker的CircuitBreaker.Execute包裹整个调用，而不是只包http.Do
如何让外观层自动透传 OpenTelemetry Trace Context
如果每次调用都要手动从 ctx 提取 trace.SpanContext()、再塞进 req.Header.Set()，那和没封装没区别。外观必须做到「调用即透传」，且兼容已有的 OTel SDK 初始化方式。
性能影响很实际：在高并发下反复序列化/反序列化 trace header 会吃 CPU；更隐蔽的问题是，如果用了 otelhttp.NewTransport，又在外层再手动设 header，会导致 trace 被覆盖或 span 关系错乱。
- 构造
ServiceClient时传入otel.Tracer实例，而非自己 new 一个 —— 避免 tracer scope 错乱 - 用
otel.GetTextMapPropagator().Inject()注入 context，而不是硬编码X-B3-系列 header（兼容 W3C Trace Context 标准） - 禁止在外观层启动新 span；它只是传播者，span 生命周期由上游业务 ctx 决定
外观模式不是银弹：哪些情况不该硬套
当你的微服务调用只有 1 个下游、QPS
最容易被忽略的复杂点是「多租户场景下的隔离」——比如不同客户调用同一套外观逻辑，但要走不同的认证 Token、不同的超时阈值、甚至不同的重试退避策略。这时候外观类得支持 per-request option，而不是全局单例配置。
- 避免把
ServiceClient设计成单例全局变量；用依赖注入传入具体实例，方便单元测试 mock - 如果下游有强弱依赖之分（比如核心订单服务 vs 非核心推荐服务），别共用一个外观类型；拆成
OrderClient和RecommendClient，各自控制熔断阈值 - 外观层绝不处理业务逻辑转换（比如把 JSON 响应反序列化成领域模型）；那是 repository 层的事
