维护模式中间件必须注册在e.use()链最前端，直接操作c.response().writer返回503，放行/health等探针路径，用atomic.bool实现热更新，避免依赖外部调用。
维护模式中间件必须在路由匹配前生效
维护模式不是业务逻辑，而是全局流量开关，必须在 e.Use() 链最前端注册，否则请求已进入具体路由或 handler，再拦截就晚了。它不能依赖路径匹配、不能放在某个 e.Group() 里，必须作用于整个 Echo 实例。
用 c.Response().Writer 直接写响应，别走 c.String() 或 c.JSON()
维护模式下要跳过所有后续中间件和 handler，直接返回固定状态码和 body。若调用 c.String(503, "...")，会触发 Echo 的默认错误处理流程，可能被 middleware.Recover() 拦截或受其他中间件（如 CORS、Logger）干扰。
正确做法是绕过 Echo 的响应封装，直接操作底层 http.ResponseWriter：
Echo框架 5.1.0
下载
Echo框架 5.1.0 版本源码包下载，适合关注 RealIP 行为变化、StartConfig.Listener、NewDefaultFS 和观测性中间件入口的开发团队。
func MaintenanceMode() echo.MiddlewareFunc {
return func(next echo.HandlerFunc) echo.HandlerFunc {
return func(c echo.Context) error {
if isMaintenanceMode() {
c.Response().Writer.WriteHeader(http.StatusServiceUnavailable)
c.Response().Writer.Write([]byte("Service temporarily unavailable"))
return nil // 终止链，不调 next
}
return next(c)
}
}
}
-
isMaintenanceMode()可读环境变量、配置文件或 Redis 键，避免硬编码 - 必须显式调用
WriteHeader()，否则 Go HTTP 默认发 200 - 返回
nil而非echo.NewHTTPError(...)，否则会继续走错误处理链
避免与健康检查端点冲突
维护模式开启时，/health 这类探针接口仍需可用，否则 Consul 或 Kubernetes 会误判服务宕机。中间件里必须放行特定路径：
if c.Request().URL.Path == "/health" || c.Request().URL.Path == "/readyz" {
return next(c)
}
- 路径判断用
c.Request().URL.Path，不是c.Path()（后者已被路由解析重写） - 不要用正则或前缀匹配泛化放行，只精确放行已知的健康检查路径
- 如果用了带查询参数的健康检查（如
/health?verbose=true），注意Path不含 query，无需额外处理
动态开关必须支持热更新，不能重启服务
维护模式开关若靠重启生效，就失去快速止损意义。推荐方案：
- 用原子布尔值（
sync/atomic.Bool）存状态，isMaintenanceMode()直接读取 - 暴露一个管理接口（如
POST /admin/maintenance），校验 token 后调用atomic.StoreBool() - 禁止在中间件里查数据库或远程 API 判断状态——每次请求都查，性能崩盘且易拖垮依赖
- 如果用配置中心（如 Consul KV），监听变更事件后更新本地原子变量，不要每次请求都拉一次
最常被忽略的是：开关生效后，旧连接仍在处理中，新请求才被拦截。真正的“立即生效”需要配合反向代理（如 Nginx）层做连接拒绝，Echo 层只能做到新请求不进业务逻辑。
