统一封装响应必须严格限定response结构体为code/message/data/timestamp四字段，code为http状态码，message为非指针string，data仅限可序列化类型，timestamp用unixmilli()，分页字段不得混入data，泛型约束与中间件拦截需协同设计。
直接用 echo.Context 手动调用 c.JSON() 封装响应，看似简单，实则埋下类型不一致、错误码错乱、分页字段污染、泛型擦除四大隐患。真正可靠的统一封装，必须把结构体定义、泛型约束、中间件拦截、错误冒泡四者拧成一股绳。
Response 结构体字段必须严格限定为 Code/Message/Data/Timestamp
别抄网上“全能 struct”，字段一多就失控。Echo 里最常犯的错是把业务码和 HTTP 状态码混进同一个字段，或者塞进 success、timestamp、total 这类语义越界字段。
-
Code必须是 HTTP 状态码（如http.StatusOK、http.StatusBadRequest），不是业务码——CDN 缓存、浏览器重试、Nginxerror_page全靠它判断 -
Message是非指针string，空值写""，不是nil；生产环境只传用户可见提示，严禁透传"pq: duplicate key"这类原始错误 -
Data类型为interface{}，但实际只允许传可序列化类型（User{}、[]Post、map[string]string），且所有字段首字母大写；禁止传func、chan、未导出字段的struct，否则json.Marshal会 panic -
Timestamp用time.Now().UnixMilli()，不是time.Time或Format()；前端直接用Date.now()对齐，避免时区/解析歧义，也减少 GC 压力 - 分页字段（
total、page、page_size）绝对不塞进Data——它是传输元信息，不是业务数据。要么单独提一层字段，要么由前端按 header 或约定路径解析
泛型封装函数末尾必须显式 return，且只设 HTTP 状态码
最常见的 panic 是封装函数里漏了 return，导致 c.JSON() 后继续执行，触发 http: multiple response.WriteHeader call。这不是 Echo 的 bug，是你没遵守它的控制流契约。
Echo框架 5.1.0 版本源码包下载，适合关注 RealIP 行为变化、StartConfig.Listener、NewDefaultFS 和观测性中间件入口的开发团队。
-
Success(c *echo.Context, data interface{})末尾必须跟return，且只设http.StatusOK；不要在里面写if err != nil { Error() }——错误分支该由 handler 自己控制 -
Error(c *echo.Context, statusCode int, message string)内部固定用c.JSON(statusCode, Response{})，不硬编码200；statusCode必须是真实 HTTP 码（400、401、500） - 禁用
c.AbortWithError()这类混合函数——c.Abort()和c.JSON()是两件事，混用极易漏响应 - 所有封装函数签名统一为
func(c echo.Context) error，不接收*http.Request或全局http.ResponseWriter，避免 goroutine 竞态
错误必须“冒泡”到 HTTPErrorHandler，不能在 handler 里手动 c.JSON
写 c.JSON(500, map[string]string{"error": "xxx"}) 是危险起点。它绕过了 Echo 的错误处理链，导致中间件（如日志、监控）收不到真实错误，无法统一格式，HTTP 状态码和业务错误混在一起，调试时找不到源头。
- 业务逻辑中应优先用
return c.JSON(code, data)仅用于成功响应；错误一律用return echo.NewHTTPError(statusCode, message)或自定义错误类型 - 避免在 handler 中调用
c.String()、c.NoContent()等底层方法处理错误，它们不触发HTTPErrorHandler - 注册
e.HTTPErrorHandler = customHTTPErrorHandler必须在路由注册前设置；典型定制点：记录错误堆栈（仅开发）、过滤敏感字段、区分内部错误与用户错误、添加traceID到响应头 - 不要在 handler 里
panic——Echo 不捕获panic，除非你额外加了e.Use(middleware.Recover())，但 recover 后的错误仍需交由HTTPErrorHandler处理
泛型 Handler 能解决 interface{} 透传导致的类型黑洞
传统中间件靠 context.Context 传递数据，但 value 键名字符串 + interface{} 值 = 编译期零检查。泛型 Handler 可把输入结构体和输出结构体直接带入类型系统，避免运行时断言 panic。
- 定义泛型 handler：
type Handler[T any, R any] func(*echo.Context, T) (R, error) - 封装统一绑定与序列化逻辑：输入自动
c.ShouldBindJSON(&req)，输出自动c.JSON(http.StatusOK, resp)，无需每次重复写 - 认证中间件想从 context 提取
*User，用泛型可声明func Auth[T *User](next Handler[T, R]) Handler[T, R]，而不是ctx.Value("user").(*User)这种易 panic 写法 - 泛型配置解析器比
map[string]interface{}更可靠：核心函数func LoadConfig[T any](path string) (T, error)，调用时直接指定目标结构体类型，如cfg, _ := LoadConfig[ServerConfig]("config.yaml") - 性能注意：泛型中间件不会增加运行时开销，但若滥用
[T any]代替具体约束（如[T User | Admin]），会导致编译器生成过多实例，增大二进制体积
泛型不是装饰，是堵住类型黑洞的水泥。一旦你在 Handler 或 Response 层放弃泛型约束，后续所有 JSON 序列化、OpenAPI 生成、前端反序列化都会退化成运行时黑盒——而这个问题，上线后根本没法 debug。
