service-debugging

服务调试

以结构化的方法调查并修复服务问题。输入症状，找出根因。

适用场景

• API 端点返回错误（4xx、5xx）
• 性能下降或查询缓慢
• 服务无法启动或发生崩溃
• 服务之间的数据不一致
• 部署后出现故障
• 用户反馈“有东西坏了”

流程

1. 收集症状

在动手修改代码之前，先收集以下信息：

• 什么出了问题？（具体的端点、功能或行为）
• 从什么时候开始的？（部署后？逐渐出现？突然发生？）
• 影响了哪些人？（所有用户、特定用户、特定数据？）
• 错误消息是什么？（日志、HTTP 响应、堆栈跟踪）

2. 检查显而易见的问题

先运行以下检查——它们可以发现 80% 的问题：

# Recent deploys (did someone push something?)
git log --oneline -10

# Service health
curl -s http://localhost:8080/health | jq .

# Recent errors in logs
grep -i "error\|exception\|fatal" logs/app.log | tail -20

# Database connectivity
psql -h $DB_HOST -U $DB_USER -d $DB_NAME -c "SELECT 1"

# Environment variables (missing or wrong?)
env | grep -i "DB_\|API_\|SECRET_" | sort

3. 缩小范围

症状	首先检查
500 错误	查看日志中的堆栈跟踪 → 找到抛出异常的代码行
404 错误	路由注册 → 控制器是否已加载？
401/403 错误	身份验证配置 → @Secured 是否正确？令牌是否有效？
响应缓慢	数据库 → 对慢查询运行 EXPLAIN
超时	外部服务 → 下游 API 是否有响应？
数据缺失	软删除 → 是否设置了 deleted_at？查询过滤条件是否错误？
服务无法启动	Bean 创建 → 检查 @Factory 和 @Singleton 的装配

4. 重现问题

• 能否在本地触发这个 Bug？
• 会导致失败的最小请求是什么？
• 失败是持续发生还是间歇发生？

5. 查找根因

如果是回归问题，请使用 git bisect：

git bisect start
git bisect bad HEAD
git bisect good <last-known-good-commit>
# Test each commit until you find the one that broke it

使用 grep 查找相关代码：

# Find where the error message comes from
grep -r "error message text" --include="*.kt" src/

# Find all callers of a broken function
grep -r "functionName" --include="*.kt" src/

6. 修复并验证

1. 编写一个能重现 Bug 的测试（红）
2. 修复代码（绿）
3. 运行完整测试套件
4. 如果是面向用户的问题，手动测试

有关常见 Bug 及其修复方法，请参阅 common-issues.md。

注意事项

• 不要只修复症状，要修复根因。 添加空值检查来掩盖数据问题，只会让数据问题之后再次造成影响。
• 先检查部署日志，再归咎于代码。 配置变更、环境变量更新和基础设施变更引发的故障，比代码 Bug 更常见。
• “在我的机器上能运行”通常意味着环境存在差异。 比较本地环境变量、数据库状态和服务版本与目标环境是否一致。
• 间歇性故障通常由竞态条件引起。 如果每 10 次失败 1 次，请检查并发访问、共享可变状态或连接池耗尽。
• 不要把重启服务作为调试的第一步。 重启会丢失有助于诊断问题的状态。先查看日志，必要时再重启。
• 软删除记录是“数据缺失”最常见的原因。 务必在查询中检查 deleted_at IS NULL。

规则

• 修改代码前，务必先收集症状
• 修复前先编写一个失败测试
• 检查近期 git 历史记录——多数 Bug 都是回归问题
• 未了解根因前，不要部署修复
• 如果事件影响了用户，请记录该事件