# 最佳实践
## 配置管理
推荐：把监听地址、认证、超时、外部 adapter endpoint、采样率等放入配置结构，并使用环境变量覆盖敏感部署差异。
反例：在 handler 中硬编码 endpoint、token 或生产环境参数。
## 错误处理
推荐：在框架边界转换为统一错误和 `ApiResponse`，保留可诊断消息。
反例：在业务代码中 `unwrap()` 外部输入、数据库结果或网络调用。
## 超时、限流和熔断
推荐：外部调用必须配置 timeout；高并发入口使用 concurrency limit；不稳定依赖使用 circuit breaker。
反例：把所有失败都无限重试，或让请求等待外部依赖直到连接自然超时。
## 认证与 public path
推荐：默认保护业务路由，只把 `/ready`、`/metrics` 等明确 endpoint 加入 public allowlist。
反例：开发时为了方便关闭认证后忘记恢复。
## Request ID
推荐：入口处生成或透传 request-id，并在 REST/RPC/log/trace 中持续传递。
反例：只在日志里打印随机 ID，但不通过响应头或 RPC metadata 透出。
## Observability
推荐：REST 服务暴露基础 metrics；跨服务调用启用 tracing；OTLP exporter 要配置 shutdown/flush。
反例：只在本地打印日志，生产环境没有请求维度指标。
## Cache key
推荐：cache key 使用稳定 namespace 和索引列顺序，例如 `user:email:mobile:{}`。
反例：把业务对象 JSON 直接作为 key，或不同模块各自拼接不同格式。
## 代码生成
推荐：生成文件进入独立目录，默认不覆盖；需要覆盖时显式使用 `--force` 并先查看 diff。
反例：把生成命令直接指向手写业务目录并强制覆盖。
## 测试策略
推荐：默认 CI 只跑无外部依赖测试；外部服务测试使用 ignored 或 feature gate。
反例：默认测试依赖本机 Redis、etcd、Kubernetes 或 OTLP collector。
## 文档维护
推荐：新增能力时同步 README 导航、相关手册、教程和测试链接。
反例：只更新里程碑记录，不告诉新用户如何使用。