网关层必须为每个下游服务单独设置context超时、熔断器按upstream独立实例化、降级响应结构体与主接口完全一致；否则将导致误熔断、雪崩或前端解析失败。
网关层必须为每个下游服务单独设置 context 超时，不能共用一个全局 timeout；熔断器必须 per-upstream 实例化；降级响应结构体必须与主接口完全一致——违反任一条件，线上就容易出雪崩、误熔断或前端解析失败。
为什么
不能在 handler 入口设一次
入口统一设
看似省事，实则破坏分级控制能力：
下游 A 服务平均耗时 2s（慢），B 服务 80ms（快），共用 1.5s timeout → B 每次都被 cancel，错误日志刷屏
漏传一处，下游 gRPC 或 DB 层就收不到 cancel 信号，goroutine 泄漏风险陡增
HTTP 层需 800ms 响应，但下游 gRPC 接口允许 1.2s，DB 查询只给 300ms —— 全局 timeout 无法表达这种分层 SLA
实操建议：
路由匹配后立即按
查配置中心（如 Nacos）获取专属 timeout，例如
调用前显式执行
用中间件统一校验：若发现
，直接 panic 并告警 —— 表示超时未透传
为什么
必须每个下游服务一个实例
整个网关只初始化一个
实例，然后所有
都往里塞，后果很直接：
用户服务返回大量 503 → 订单服务调用也被熔断（共享
计数）
函数里判
，但订单服务用 HTTP，用户服务用 gRPC → 错误码语义不统一，熔断逻辑失效
导致半开探测刚进来就拒绝全部请求，实际应设为
才有统计意义
实操建议：
按
键值对注册 breaker：
设为 30s～2m（太短会被瞬时抖动带偏）；
是 Open 态持续时间，不是 HTTP 超时，推荐 15s
必须区分协议：HTTP 失败指
，gRPC 指
为什么降级函数返回
会炸前端
降级写成
，而主逻辑返回的是
，问题立刻暴露：
字段名不一致：
vs
→ 前端解构失败，页面白屏
降级里又调了 Redis 获取缓存用户 → Redis 也挂了，
直接让整个请求失败，降级变“升空”
没设
→ 浏览器当 text/plain 解析，CORS 报错或 JSON.parse 异常
实操建议：
降级函数签名必须和主逻辑完全一致，包括是否是指针类型：
所有降级数据启动时预加载进内存（如从本地 JSON 文件读取默认
对象），零外部依赖
用
或显式
+
，确保 header 和 body 同步
最容易被忽略的其实是「超时与熔断阈值的联动」：比如 HTTP 超时设 800ms，但熔断的
却用 5 秒内失败 3 次来判定——这会导致超时还没触发几次，熔断器就提前打开了。真正该做的是让熔断统计窗口（
）覆盖至少 3 个超时周期，并把单次超时明确计入失败计数。
context.WithTimeoutcontext.WithTimeout(req.Context(), 5*time.Second)req.WithContext(ctx)upstream.Nameuser-svc.timeout=600msreq = req.WithContext(context.WithTimeout(req.Context(), timeout))req.Context().Done() == nilgobreaker.CircuitBreakercbcb.Execute(...)ConsecutiveFailuresReadyToTripstatus.Code() == codes.UnavailableMaxRequests: 1≥10upstream.Namebreakers["user-svc"] = gobreaker.NewCircuitBreaker(settings)IntervalTimeoutReadyToTripresp.StatusCode >= 500status.Code() ∈ {codes.Internal, codes.Unavailable, codes.DeadlineExceeded}map[string]interface{}return map[string]interface{}{"code": 503, "msg": "fallback"}struct{ UserID int `json:"user_id"` }user_idUserIDpanicw.Header().Set("Content-Type", "application/json")func() (*User, error)*Userhttp.Error(w, "fallback", http.StatusServiceUnavailable)w.WriteHeader()json.NewEncoder(w).Encode(...)ReadyToTripInterval