调试技能Skill debugging

---

名称: 调试 描述: 使用各种调试技术和工具，系统性地诊断和解决软件缺陷、测试失败、数据质量问题及性能问题。触发关键词：调试、bug、错误、异常、崩溃、问题、故障排除、修复、堆栈跟踪、诊断、调查、根因、原因、失败、损坏、不工作、意外、不稳定、间歇性、回归、性能下降。 允许工具：Read、Grep、Glob、Bash、Edit

调试

概述

本技能提供了系统性的方法来查找和修复跨所有领域的缺陷：应用程序代码、测试、数据管道、机器学习模型和基础设施。涵盖了调试策略、工具使用以及针对各种类型问题的技术，包括崩溃、不稳定测试、数据质量问题及模型性能下降。

指令

1. 理解问题

• 一致地重现问题
• 收集错误消息和堆栈跟踪
• 识别缺陷何时被引入
• 确定预期与实际行为

2. 隔离问题

• 创建最小化重现案例
• 使用二分查找缩小原因范围
• 检查最近更改（Git 二分查找）
• 验证环境和依赖项

3. 诊断根因

• 添加战略日志
• 使用调试器逐步执行代码
• 分析堆栈跟踪
• 检查常见模式

4. 修复和验证

• 实施针对性修复
• 添加回归测试
• 验证修复不会引入新问题
• 记录根因

最佳实践

1. 先重现: 从不修复无法重现的问题
2. 阅读错误消息: 它们通常包含答案
3. 检查最近更改: 大多数缺陷是最近引入的
4. 质疑假设: 验证你的认知
5. 隔离变量: 一次更改一件事
6. 使用版本控制: Git 二分查找功能强大
7. 编写测试: 证明缺陷存在，然后证明其被修复

专业调试领域

调试不稳定测试

不稳定测试非确定性地通过/失败。常见根因：

时序问题:

• 异步代码中的竞态条件
• UI元素等待时间不足
• 网络请求超时
• 后台作业未完成

非确定性状态:

• 未使用种子的随机数据生成
• 无序集合（集合、映射迭代）
• 浮点精度问题
• 测试中基于时间戳的逻辑

测试隔离失败:

• 测试间共享全局状态
• 数据库在运行间未清理
• 文件/资源未正确清理
• 测试执行顺序依赖

调试技术:

# 多次运行测试以重现不稳定性
for i in {1..100}; do cargo test test_name || break; done

# 使用详细日志运行以暴露时序
RUST_LOG=debug cargo test test_name

# 检查共享状态问题
cargo test -- --test-threads=1  # 强制串行执行

# 识别依赖时序的测试
cargo test -- --nocapture | grep -i "timeout\|sleep\|wait"

修复:

• 添加显式等待而非任意睡眠
• 种子随机生成器：rand::thread_rng().seed(42)
• 在测试夹具/拆卸中清理状态
• 使用测试隔离模式（事务、临时目录）
• 模拟时间依赖代码

调试数据管道

数据管道缺陷表现为结果错误、特定数据崩溃或性能问题。

常见问题:

• 阶段间模式不匹配
• 空值/缺失值处理
• 数据类型转换（精度损失、溢出）
• 编码问题（UTF-8、特殊字符）
• 大型数据集的内存问题

调试技术:

# 采样问题数据以进行本地调试
df_sample = df.filter("problematic_condition").limit(1000)
df_sample.write.parquet("debug_sample.parquet")

# 添加数据质量断言
assert df.filter(col("user_id").isNull()).count() == 0, "找到空 user_ids"
assert df.filter(col("amount") < 0).count() == 0, "找到负数金额"

# 分析内存和性能
df.explain()  # 显示执行计划
df.cache()    # 物化以进行分析

# 检查模式演化问题
df.printSchema()
df.dtypes  # 验证预期类型

根因分析:

• 检查上游数据源的模式更改
• 在管道阶段边界验证数据
• 在每个转换记录样本
• 使用数据分析工具查找异常
• 测试边缘情况：空值、空字符串、极端值

调试机器学习模型

机器学习调试涉及代码缺陷和模型行为问题。

训练问题:

• 损失不下降（学习率、梯度流）
• 损失爆炸（梯度爆炸、数值不稳定）
• 过拟合（模型记忆训练数据）
• 欠拟合（模型对数据过于简单）

推理问题:

• 预测分布偏移
• 随时间性能下降
• 训练/推理间结果不一致
• 模型服务中的内存泄漏

调试技术:

# 检查梯度流
for name, param in model.named_parameters():
    if param.grad is not None:
        print(f"{name}: 梯度范数 = {param.grad.norm()}")
    else:
        print(f"{name}: 无梯度")  # 死层！

# 检测数值问题
torch.autograd.set_detect_anomaly(True)  # 捕捉 NaN/Inf

# 验证数据预处理
print("训练数据统计:", train_data.mean(), train_data.std())
print("推理数据统计:", inference_data.mean(), inference_data.std())
# 如果统计显著不同，预处理不匹配！

# 分析模型性能
import torch.autograd.profiler as profiler
with profiler.profile(use_cuda=True) as prof:
    model(input_data)
print(prof.key_averages().table())

# 测试单个示例
model.eval()
with torch.no_grad():
    output = model(single_input)
    print(f"输入: {single_input}, 输出: {output}")

根因分析:

• 验证数据预处理匹配训练
• 检查标签泄漏或数据污染
• 验证特征分布（训练与生产）
• 测试具有预期输出的已知示例
• 使用可解释性工具（SHAP、注意力权重）

示例

示例 1: 系统调试过程

# 步骤 1: 理解错误
"""
错误: TypeError: 无法读取未定义的属性 'name'
于 processUser (src/users.py:45)
于 handleRequest (src/server.py:123)
"""

# 步骤 2: 添加诊断日志
def process_user(user_id: str) -> dict:
    logger.debug(f"处理用户ID: {user_id}")

    user = get_user(user_id)
    logger.debug(f"检索的用户: {user}")  # <-- 用户为 None!

    # 缺陷: 访问属性前未检查空值
    return {"name": user.name}  # 在此处崩溃

# 步骤 3: 修复并进行适当的空值处理
def process_user(user_id: str) -> dict:
    logger.debug(f"处理用户ID: {user_id}")

    user = get_user(user_id)
    if user is None:
        logger.warning(f"用户未找到: {user_id}")
        raise UserNotFoundError(f"用户 {user_id} 未找到")

    return {"name": user.name}

# 步骤 4: 添加回归测试
def test_process_user_not_found():
    with pytest.raises(UserNotFoundError):
        process_user("不存在ID")

示例 2: 使用 Git 二分查找查找缺陷引入

# 启动二分查找会话
git bisect start

# 标记当前提交为坏（包含缺陷）
git bisect bad

# 标记已知好提交（缺陷存在前）
git bisect good v1.2.0

# Git 检出中间提交，测试它
# 运行你的测试
npm test

# 标记结果
git bisect good  # 或 git bisect bad

# 重复直到 Git 识别首个坏提交
# Git 将输出: "abc123 是首个坏提交"

# 查看有问题的提交
git show abc123

# 结束二分查找会话
git bisect reset

示例 3: 常见缺陷模式

# 模式 1: 差一错误
# 缺陷: 缺失最后一个元素
for i in range(len(items) - 1):  # 错误！
    process(items[i])
# 修复:
for i in range(len(items)):
    process(items[i])

# 模式 2: 竞态条件
# 缺陷: 检查后执行无同步
if not file.exists():
    file.create()  # 另一个线程可能在检查和创建间创建
# 修复: 使用原子操作
file.create_if_not_exists()

# 模式 3: 浮点数比较
# 缺陷: 直接相等比较
if 0.1 + 0.2 == 0.3:  # 这是 False！
    do_something()
# 修复: 使用近似比较
if abs((0.1 + 0.2) - 0.3) < 1e-9:
    do_something()

# 模式 4: 可变默认参数
# 缺陷: 共享可变默认
def add_item(item, items=[]):  # 同一列表实例被重用！
    items.append(item)
    return items
# 修复: 使用 None 默认
def add_item(item, items=None):
    if items is None:
        items = []
    items.append(item)
    return items

# 模式 5: 静默失败
# 缺陷: 吞没异常
try:
    risky_operation()
except Exception:
    pass  # 缺陷被隐藏！
# 修复: 适当处理或重新抛出
try:
    risky_operation()
except SpecificException as e:
    logger.error(f"操作失败: {e}")
    raise

示例 4: 调试工具使用

# Python 调试
python -m pdb script.py  # 交互式调试器
python -m trace --trace script.py  # 跟踪执行

# Node.js 调试
node --inspect script.js  # Chrome DevTools
node --inspect-brk script.js  # 在第一行中断

# Rust 调试
RUST_BACKTRACE=1 cargo run  # 完整堆栈跟踪
RUST_LOG=debug cargo run    # 详细日志

# 内存分析（Python）
python -m memory_profiler script.py

# CPU 分析（Python）
python -m cProfile -o output.prof script.py
python -m pstats output.prof

# Strace 用于系统调用（Linux）
strace -f -e trace=file python script.py

# 网络调试
tcpdump -i any port 8080
curl -v http://localhost:8080/api/health

示例 5: 调试不稳定测试

# 不稳定测试 - 间歇性失败
def test_user_registration():
    user = create_user(email="test@example.com")
    # 有时失败: "用户已存在"
    assert user.id is not None

# 诊断: 测试隔离失败 - 数据库在运行间未清理

# 修复: 添加适当的拆卸
@pytest.fixture(autouse=True)
def clean_database():
    yield
    # 在每个测试后清理
    User.query.delete()
    db.session.commit()

def test_user_registration():
    user = create_user(email="test@example.com")
    assert user.id is not None

# 替代修复: 每个测试运行使用唯一数据
def test_user_registration():
    email = f"test-{uuid.uuid4()}@example.com"
    user = create_user(email=email)
    assert user.id is not None

示例 6: 调试数据管道

# 数据管道在生产数据上崩溃但在测试数据上工作
def transform_orders(df):
    # 缺陷: 当折扣列有空值时崩溃
    df["final_price"] = df["price"] * (1 - df["discount"])
    return df

# 诊断: 添加断言以早期捕获不良数据
def transform_orders(df):
    # 检查输入数据的假设
    assert "price" in df.columns, "缺少价格列"
    assert "discount" in df.columns, "缺少折扣列"

    # 暴露缺陷
    null_discounts = df[df["discount"].isnull()]
    if len(null_discounts) > 0:
        print(f"找到 {len(null_discounts)} 个订单有空值折扣")
        print(null_discounts.head())

    # 修复: 显式处理空值
    df["discount"] = df["discount"].fillna(0.0)
    df["final_price"] = df["price"] * (1 - df["discount"])
    return df

# 添加数据验证测试
def test_transform_orders_handles_nulls():
    df = pd.DataFrame({
        "price": [100, 200],
        "discount": [0.1, None]  # 空折扣
    })
    result = transform_orders(df)
    assert result["final_price"].tolist() == [90.0, 200.0]

示例 7: 调试机器学习模型性能

# 模型准确率从 95% 降至生产中的 75%

# 步骤 1: 比较训练与生产数据分布
train_stats = train_df.describe()
prod_stats = production_df.describe()
print("检测到特征漂移:")
for col in train_stats.columns:
    train_mean = train_stats.loc["mean", col]
    prod_mean = prod_stats.loc["mean", col]
    drift = abs(prod_mean - train_mean) / train_mean
    if drift > 0.1:
        print(f"{col}: {drift*100:.1f}% 漂移")

# 步骤 2: 测试单个示例以找到模式
test_cases = [
    {"input": [...], "expected": 1, "predicted": model.predict([...])},
    {"input": [...], "expected": 0, "predicted": model.predict([...])},
]
for case in test_cases:
    if case["expected"] != case["predicted"]:
        print(f"预测错误: {case}")

# 步骤 3: 根因 - 特征预处理更改
# 训练: 特征用训练数据的 StandardScaler 标准化
# 生产: 特征用不同的缩放器参数标准化！

# 修复: 保存并加载缩放器与模型
import joblib
joblib.dump(scaler, "scaler.pkl")
# 在生产中:
scaler = joblib.load("scaler.pkl")
features_scaled = scaler.transform(features)
predictions = model.predict(features_scaled)