不能直接用 zap.logger 替换 echo.logger——因二者类型不兼容，前者是结构体，后者是仅含输出方法的极简接口，硬赋值编译失败；强行桥接会丢失 caller、结构化字段及性能优势。
直接用 echo.Logger 替换为 zap.Logger 不可行——Echo v5 默认用 slog，且其内置 logger 接口与 zap.Logger 类型不兼容。必须通过中间件或自定义 echo.HTTPErrorHandler 注入结构化日志能力。
为什么不能直接赋值 echo.Logger = zap.L()
Echo 的 echo.Logger 是一个极简接口（仅含 Output、SetOutput、SetLevel 等），而 zap.Logger 是完整结构体，字段和方法完全不匹配。硬赋值会编译失败；强行桥接（如包装成 slog.Logger）会丢失 caller 信息、结构化字段和性能优势。
-
echo.Logger本质是文本写入器，不支持zap.String("key", "val")这类字段追加 - 若用
zap.Sugar()转成slog，会触发反射序列化，压测时 GC 压力翻倍 - 默认
echo.Logger输出无时间戳、无 level 字段，ELK 或 Loki 无法解析结构
正确注入方式：用中间件 + context 透传 *zap.Logger
避免在每个 handler 里重复 new logger，也不依赖全局单例 zap.L()（不可配置、难 mock）。把 *zap.Logger 实例塞进 context.Context，让 handler 按需取用并叠加请求级字段。
- 初始化时创建带通用字段的 logger：
logger := zap.NewProduction().With(zap.String("service", "user-api")) - 中间件中用
c.Set("logger", logger.With(zap.String("req_id", uuid.NewString())))，而非每次调用logger.With() - handler 内取出：
logger := c.Get("logger").(*zap.Logger)，再补路径、method 等字段 - 切忌在中间件里调用
logger.Sync()—— 它会阻塞整个请求链路
错误处理必须重写 HTTPErrorHandler
Echo 默认 panic 恢复后只打一行字符串日志，丢失 error 堆栈、status code 和上下文字段。替换 echo.HTTPErrorHandler 才能保证错误日志可检索、可关联。
- 注册时：
e.HTTPErrorHandler = func(err error, c echo.Context) { logger.Error("http_error", zap.Error(err), zap.Int("status", c.Response().Status), zap.String("path", c.Request().URL.Path)) } - 别用
logger.Info(fmt.Sprintf(...))拼接，否则触发内存分配，高并发下 GC 频繁 - 字段名统一用下划线（
req_id、http_status），否则 Kibana/Loki 无法索引
日志滚动与分文件输出要靠 lumberjack + WriteSyncer
Zap 本身不提供滚动功能，必须组合 lumberjack.Logger 构造 zapcore.WriteSyncer，再锁住防止多 goroutine 写冲突。
- 配置示例：
syncer := zapcore.AddSync(&lumberjack.Logger{ Filename: "logs/app.log", MaxSize: 100, MaxBackups: 5, MaxAge: 7, }) - 生产环境务必包一层
zapcore.Lock(syncer)，裸用lumberjack在高并发下会 panic - 想分离 error 日志？建两个
WriteSyncer，用levelEnablerFunc分流：func(lvl zapcore.Level) bool { return lvl >= zapcore.ErrorLevel } - 禁用 encoder 时间格式化：
EncodeTime: zapcore.ISO8601TimeEncoder，别用time.Now().Format()—— 每次调用都分配内存
真正麻烦的不是配置几行代码，而是字段命名一致性、caller 行号是否开启、error 是否带堆栈、日志是否被采样丢弃——这些细节没对齐，查问题时就会发现 Kibana 里搜不到 http_status: 500，或者 trace ID 在不同服务间断掉。
