唯一触发全局错误处理器的路径是c.Error(echo.NewHTTPError())，直接c.JSON(404,...)等不触发；未匹配路由需e.Any("/*")兜底；中间件中也须用c.Error()而非直接响应。
c.Error(echo.NewHTTPError()) 是唯一进全局错误处理器的路径
直接用 c.JSON(404, ...) 或 c.String(404, ...) 不会触发 HTTPErrorHandler，它们只是普通响应，框架不认为这是“错误”。只有显式构造并传入 echo.NewHTTPError() 的实例，才会被全局错误处理器捕获。
常见错误现象：你写了 c.JSON(404, map[string]string{"error": "not found"})，日志没记录、环境差异化逻辑（比如 debug 模式返回详细信息）也不生效——因为压根没走 HTTPErrorHandler。
- 必须写成
c.Error(echo.NewHTTPError(http.StatusNotFound, "user not found")) - 不要用
c.Error(fmt.Errorf("..."))，它会被当成 500 错误，无法区分业务 404 和真实异常 -
echo.NewHTTPError()的第二个参数是message字段来源，后续在HTTPErrorHandler中可通过he.Message安全提取
未匹配路由默认不进 HTTPErrorHandler，得手动兜底
Echo 对未注册路径的默认响应是硬编码的 "Not Found" 字符串，状态码 404，但它绕过所有中间件和 HTTPErrorHandler。要让它也走统一错误处理，必须加一个兜底路由。
正确做法是在所有业务路由注册完之后，追加：
e.Any("/*", func(c echo.Context) error {
return c.Error(echo.NewHTTPError(http.StatusNotFound, "route not found"))
})
注意两点：
- 必须用
e.Any()，不是e.GET()，否则非 GET 方法（如 PUT、DELETE、OPTIONS）仍会跳过你的 handler - 这个
e.Any("/*")必须放在最后，否则会提前匹配，把真实路由遮住
HTTPErrorHandler 中区分 404 和 500 的关键细节
404 高频且低风险，500 代表服务异常，二者日志粒度和响应内容策略完全不同。混在一起处理容易暴露路径、泄露内部结构，或掩盖真正问题。
Echo框架 5.1.0 版本源码包下载，适合关注 RealIP 行为变化、StartConfig.Listener、NewDefaultFS 和观测性中间件入口的开发团队。
典型错误写法：c.JSON(code, map[string]interface{}{"message": err.Error()}) —— 把原始错误堆栈或路径（如 /var/www/app/internal/...）直接返回给前端。
- 对 404：固定响应文案，例如
"Resource not found"，不要拼接he.Message，除非你做过白名单校验 - 对 500：生产环境必须隐藏细节，只返回通用提示，如
"Something went wrong" - 日志里保留原始路径：
c.Logger().Errorf("404: %s | path=%s method=%s", err.Error(), c.Request().URL.Path, c.Request().Method)
中间件里抛错也要走统一路径
身份验证、权限校验等中间件中，不能用 c.String(401, ...) 或 c.JSON(403, ...) 直接响应。那样会中断中间件链，但跳过 HTTPErrorHandler，导致日志缺失、响应格式不一致。
正确姿势是立即 return c.Error(...)：
func authMiddleware(next echo.HandlerFunc) echo.HandlerFunc {
return func(c echo.Context) error {
token := c.Request().Header.Get("Authorization")
if token == "" {
return c.Error(echo.NewHTTPError(http.StatusUnauthorized, "missing auth header"))
}
return next(c)
}
}
这样既终止当前请求，又确保错误进入全局流程。别忘了在中间件里调用 next(c) 前做检查，否则可能漏掉拦截。
真正容易被忽略的是：兜底路由和中间件里的 c.Error() 必须用同一套 echo.NewHTTPError() 构造逻辑，否则 HTTPErrorHandler 里类型断言 err.(*echo.HTTPError) 会失败，退化到默认 500 处理分支。
