推荐使用echo.NewHTTPError()抛出错误以触发全局错误处理器，确保状态码、日志、监控等全链路生效；避免直接调用c.JSON(400, ...)或c.Status()+c.JSON()，否则错误不冒泡、中间件无法感知。
echo.NewHTTPError() 是改状态码的唯一推荐方式
直接调用
c.JSON(400, map[string]string{"error": "bad request"})</p>
<p>这类写法不会触发全局错误处理器，状态码是“硬编码”进响应的，后续中间件（如日志、监控）完全感知不到这个错误事件。Echo 的设计要求错误必须“冒泡”到 <code>HTTPErrorHandler 才算真正进入错误流控体系。
正确做法是抛出一个可识别的错误对象：
-
return echo.NewHTTPError(http.StatusBadRequest, "invalid id")→ 自动被HTTPErrorHandler捕获，Code和Message可直接提取 -
return echo.NewHTTPError(http.StatusNotFound)→ 不传 message 时自动使用标准文本"Not Found" - 不要用
panic("not found")替代 —— 它不带状态码语义，且需额外加middleware.Recover()才能捕获，还容易漏掉非 panic 错误
路由未匹配时的状态码怎么设成 404？
Echo 默认 404 响应是纯文本 "Not Found"，状态码确实是 404，但内容不可定制。如果你希望返回 JSON 格式的 404（比如 {"code": 404, "message": "route not found"}），不能靠中间件拦截，必须重写 e.HTTPErrorHandler 并识别未匹配场景。
关键点在于：未匹配路由会触发 echo.NewHTTPError(http.StatusNotFound)，但不是由你写的 handler 抛出的，而是框架内部逻辑生成的 —— 它仍走 HTTPErrorHandler 流程。
- 在自定义
HTTPErrorHandler中判断he.Code == http.StatusNotFound - 此时可统一返回 JSON：
c.JSON(he.Code, map[string]string{"code": strconv.Itoa(he.Code), "message": he.Message}) - 注意不要覆盖
e.NotFoundHandler—— 它只控制响应体，不改变状态码，且与HTTPErrorHandler并行存在，容易造成行为冲突
中间件里怎么提前返回 401 或 403？
身份校验类中间件（如 JWT 验证）必须用 return echo.NewHTTPError() 终止请求，而不是 c.String(401, "...") 或 c.JSON(401, ...)。
-
return echo.NewHTTPError(http.StatusUnauthorized, "token expired")→ 触发HTTPErrorHandler，日志、脱敏、traceID 注入全链路生效 -
return echo.NewHTTPError(http.StatusForbidden)→ 同理，框架自动补上"Forbidden"作为 message - 切忌在中间件里写
c.Response().Status = 401+return nil—— 这会让请求继续往下走，可能被后续 handler 覆盖状态码或写出重复 body
为什么 c.Status() + c.JSON() 组合很危险？
c.Status() 只设置响应状态码，不终止执行；c.JSON() 写响应体并隐式设置 Content-Type，但它本身不抛错也不中断流程。两者叠加看似可控，实则埋下三类隐患：
- 后续中间件或 handler 仍可能再次调用
c.JSON()，导致 HTTP body 写两次，客户端收到截断或解析失败 - 错误没进
HTTPErrorHandler，日志里查不到这条错误记录，监控指标缺失 - 开发环境堆栈无法自动打印，生产环境也拿不到原始错误类型（比如是 DB 连接失败还是空指针），排查只能靠猜
真正需要精细控制响应头（比如加 X-RateLimit）时，应该在 HTTPErrorHandler 里做：c.Response().Header().Set("X-RateLimit", "100")，再调 c.JSON() —— 这样既保状态码语义，又不破坏错误流控。
