fix-bug

修复 GitHub Issue 中报告的 Bug

将 GitHub Issue 转化为 DBHub 代码库中有效修复的系统化工作流。

工作流

1. 获取 → 2. 分析 → 3. 定位 → 4. 复现 → 5. 规划 → 6. 实现 → 7. 验证 → 8. PR

步骤 1：获取 Issue

# From URL: https://github.com/owner/repo/issues/123
gh issue view 123 --json title,body,labels,comments,state

# From another repo
gh issue view 123 --repo owner/repo --json title,body,labels,comments,state

输入	获取方式
https://github.com/owner/repo/issues/42	gh issue view 42 --repo owner/repo
#42 或 42	gh issue view 42（当前仓库）
owner/repo#42	gh issue view 42 --repo owner/repo

步骤 2：分析 Issue

从 Issue 中提取以下信息：

• 问题所在：预期行为与实际行为的差异
• 复现步骤：如何触发 Bug
• 环境：数据库类型、连接方式（DSN、SSH 隧道、TOML 配置）、传输方式（stdio/HTTP）
• 标签/评论：可能揭示受影响的部分或此前的调查情况
• 关联的 PR/Issue：检查相关背景信息

步骤 3：定位相关代码

根据 Issue 详情确定代码库中受影响的部分。DBHub 采用清晰的模块化结构，大多数 Bug 都属于以下某一类：

Bug 类别	查看位置	关键文件
连接失败	连接器实现	src/connectors/{db-type}/index.ts、src/connectors/manager.ts
SQL 执行错误	工具处理程序	src/tools/execute-sql.ts、src/utils/allowed-keywords.ts
架构/表列表	搜索工具	src/tools/search-objects.ts
DSN 解析问题	解析器逻辑	src/connectors/{db-type}/index.ts (DSNParser)、src/utils/dsn-obfuscate.ts、src/utils/safe-url.ts
SSH 隧道问题	隧道实用工具	src/utils/ssh-tunnel.ts、src/utils/ssh-config-parser.ts
TOML 配置问题	配置加载	src/config/toml-loader.ts、src/types/config.ts
多数据库路由	管理器和工具	src/connectors/manager.ts、src/utils/tool-handler-helpers.ts
自定义工具问题	自定义处理程序	src/tools/custom-tool-handler.ts、src/tools/registry.ts
HTTP 传输	服务设置	src/server.ts
只读限制违规	SQL 验证	src/utils/allowed-keywords.ts、src/utils/sql-parser.ts
行数限制	SQL 重写	src/utils/sql-row-limiter.ts
API 端点问题	API 处理程序	src/api/sources.ts、src/api/requests.ts
AWS IAM 身份验证	令牌签名	src/utils/aws-rds-signer.ts

搜索 Issue 中提到的错误消息、函数名称或文件路径。从入口点开始，沿着代码路径追踪到故障位置。

步骤 4：复现

如果该领域有集成测试： 编写一个失败测试来复现 Bug。DBHub 的测试基础设施让这项工作十分简单：

• 数据库连接器 Bug → 扩展 src/connectors/__tests__/ 中现有的集成测试
• 实用工具 Bug → 在 src/utils/__tests__/ 中现有的单元测试中添加用例
• 工具处理程序 Bug → 添加到 src/tools/__tests__/
• 配置 Bug → 添加到 src/config/__tests__/

针对多数据库或 readonly/max_rows 场景，使用 src/__fixtures__/ 中的测试夹具。

如果没有适用的测试基础设施： 追踪代码路径，通过阅读代码确认逻辑缺陷。

步骤 5：规划修复

对于非简单修复（涉及多个文件、影响架构）：使用 EnterPlanMode。

对于简单修复（单个函数、根因明确）：直接开始处理。

步骤 6：实现

• 修复根因，而不只是表面症状
• 保持更改最少且聚焦
• 遵循现有代码规范（风格指南见 CLAUDE.md）
• 对所有数据库操作使用参数化查询
• 在适当情况下使用 zod schema 验证输入

步骤 7：验证

运行相关测试以确认修复：

pnpm test:unit                    # Quick check — no Docker needed
pnpm test src/path/to/test.ts     # Run the specific test file
pnpm test:integration             # Full integration suite if needed

检查以下内容：

• 失败测试（如果有编写）现在是否通过
• 现有测试是否均未发生回归
• 差异是否完整解决了问题

步骤 8：创建 PR

1. 创建分支：

   git checkout -b fix/issue-123
   

2. 提交更改并引用该问题：

   git add <changed-files>
   git commit -m "$(cat <<'EOF'
   Fix: <short description>
   
   Closes #123
   EOF
   )"
   

3. 推送并创建 PR：

   git push -u origin fix/issue-123
   gh pr create --title "Fix: <short description>" --body "$(cat <<'EOF'
   ## Summary
   <What was broken and how this fixes it>
   
   ## Changes
   <Bullet list of changes>
   
   Closes #123
   
   ## Test plan
   - [ ] Existing tests pass
   - [ ] New test covers the bug scenario (if applicable)
   EOF
   )"
   

4. 将 PR URL 返回给用户。

常见错误

• 只修复表面问题，而非根本原因：修复前先追踪完整的代码路径
• 跳过复现：没有复现步骤的修复只是猜测
• 范围蔓延：修复报告的问题，不要重构周边代码
• 遗漏边界情况：检查修复是否处理了评论中提到的相关场景
• 未使用正确的数据库进行测试：如果 Bug 与特定数据库有关，请使用相应的连接器进行测试