代码库搜索

何时使用此技能

• 查找特定函数或类
• 追踪函数调用和依赖关系
• 理解代码结构和架构
• 查找使用示例
• 识别代码模式
• 定位错误或问题
• 代码考古（理解遗留代码）
• 更改前的影响分析

指示

步骤 1：理解您在寻找什么

功能实现：

• 功能 X 在哪里实现的？
• 功能 Y 是如何工作的？
• 哪些文件涉及功能 Z？

错误定位：

• 这个错误是从哪里来的？
• 哪段代码处理这种情况？
• 这些数据在哪里被修改？

API 使用：

• 这个 API 是如何使用的？
• 这个函数在哪里被调用？
• 有哪些使用此功能的示例？

配置：

• 设置在哪里定义？
• 这是如何配置的？
• 有哪些配置选项？

步骤 2：选择搜索策略

语义搜索（用于概念性问题）：

使用时机：您从概念上知道您在寻找什么
示例：
- “我们如何处理用户认证？”
- “邮箱验证在哪里实现？”
- “我们如何连接到数据库？”

优点：
- 通过含义查找相关代码
- 适用于不熟悉的代码库
- 适合探索性搜索

Grep（用于精确文本/模式）：

使用时机：您知道确切的文本或模式
示例：
- 函数名：“def authenticate”
- 类名：“class UserManager”
- 错误消息：“无效凭据”
- 特定字符串：“API_KEY”

优点：
- 快速且精确
- 支持正则表达式模式
- 适用于已知术语

Glob（用于文件发现）：

使用时机：您需要按模式查找文件
示例：
- “**/*.test.js”（所有测试文件）
- “**/config*.yaml”（配置文件）
- “src/**/*Controller.py”（控制器）

优点：
- 按类型快速查找文件
- 发现文件结构
- 定位相关文件

步骤 3：搜索工作流

1. 从宽泛开始，然后缩小范围：

步骤 1：语义搜索“认证是如何工作的？”
结果：指向 auth/ 目录

步骤 2：在 auth/ 中 Grep 特定函数
模式：“def verify_token”
结果：在 auth/jwt.py 中找到

步骤 3：读取该文件
文件：auth/jwt.py
结果：理解实现

2. 使用目录定位：

# 从无目标开始（全局搜索）
查询：“用户登录在哪里实现？”
目标：[]

# 用特定目录细化
查询：“登录在哪里验证？”
目标：[“backend/auth/”]

3. 组合搜索：

# 查找功能实现位置
语义：“用户注册流程”

# 查找所有涉及的文件
Grep：“def register_user”

# 查找测试文件
Glob：“**/*register*test*.py”

# 理解实现
读取：registration.py， test_registration.py

步骤 4：常见搜索模式

查找函数定义：

# Python
grep -n "def function_name" --type py

# JavaScript
grep -n "function functionName" --type js
grep -n "const functionName = " --type js

# TypeScript
grep -n "function functionName" --type ts
grep -n "export const functionName" --type ts

# Go
grep -n "func functionName" --type go

# Java
grep -n "public.*functionName" --type java

查找类定义：

# Python
grep -n "class ClassName" --type py

# JavaScript/TypeScript
grep -n "class ClassName" --type js,ts

# Java
grep -n "public class ClassName" --type java

# C++
grep -n "class ClassName" --type cpp

查找类/函数的使用：

# Python
grep -n "ClassName(" --type py
grep -n "function_name(" --type py

# JavaScript
grep -n "new ClassName" --type js
grep -n "functionName(" --type js

查找导入/引用：

# Python
grep -n "from.*import.*ModuleName" --type py
grep -n "import.*ModuleName" --type py

# JavaScript
grep -n "import.*from.*module-name" --type js
grep -n "require.*module-name" --type js

# Go
grep -n "import.*package-name" --type go

查找配置：

# 配置文件
glob "**/*config*.{json,yaml,yml,toml,ini}"

# 环境变量
grep -n "process\\.env\\." --type js
grep -n "os\\.environ" --type py

# 常量
grep -n "^[A-Z_]+\\s*=" --type py
grep -n "const [A-Z_]+" --type js

查找 TODO/FIXME：

grep -n "TODO|FIXME|HACK|XXX" -i

查找错误处理：

# Python
grep -n "try:|except|raise" --type py

# JavaScript
grep -n "try|catch|throw" --type js

# Go
grep -n "if err != nil" --type go

步骤 5：高级技巧

追踪数据流：

1. 查找数据创建的位置
   语义：“用户对象在哪里创建？”

2. 搜索变量使用情况
   Grep：“user\\.” 并带上上下文行数

3. 跟踪转换过程
   读取：修改 user 的文件

4. 查找数据被消费的位置
   Grep：“user\\.” 在相关文件中

查找函数的所有调用点：

1. 查找函数定义
   Grep：“def process_payment”
   结果：payments/processor.py:45

2. 查找该模块的所有导入
   Grep：“from payments.processor import”
   结果：多个文件

3. 查找函数的所有调用
   Grep：“process_payment\\(”
   结果：所有调用点

4. 读取每个调用点以了解上下文
   读取：每个带有上下文的文件

端到端理解一个功能：

1. 查找 API 端点
   语义：“用户注册端点在哪里？”
   结果：routes/auth.py

2. 追踪到控制器
   读取：routes/auth.py
   查找：调用 AuthController.register

3. 追踪到服务层
   读取：controllers/auth.py
   查找：调用 UserService.create_user

4. 追踪到数据库
   读取：services/user.py
   查找：数据库操作

5. 查找测试
   Glob：“**/*auth*test*.py”
   读取：测试文件以获取示例

查找相关文件：

1. 从已知文件开始
   示例：models/user.py

2. 查找此文件的导入
   Grep：“from models.user import”

3. 查找此文件导入的文件
   读取：models/user.py
   注意：导入语句

4. 构建依赖图
   映射：所有相关文件

影响分析：

在更改函数 X 之前：

1. 查找所有调用点
   Grep：“function_name\\(”

2. 查找所有测试
   Grep：“test.*function_name” -i

3. 检查相关功能
   语义：“什么依赖于 X？”

4. 审查每个使用点
   读取：每个使用该函数的文件

5. 计划更改
   记录：影响和所需的更新

步骤 6：搜索优化

使用适当的上下文：

# 查看周围上下文
grep -n "pattern" -C 5  # 前后各 5 行
grep -n "pattern" -B 3  # 前 3 行
grep -n "pattern" -A 3  # 后 3 行

大小写敏感：

# 忽略大小写
grep -n "pattern" -i

# 大小写敏感（默认）
grep -n "Pattern"

文件类型过滤：

# 特定类型
grep -n "pattern" --type py

# 多种类型
grep -n "pattern" --type py,js,ts

# 排除类型
grep -n "pattern" --glob "!*.test.js"

正则表达式模式：

# 任意字符：.
grep -n "function.*Name"

# 行首：^
grep -n "^class"

# 行尾：$
grep -n "TODO$"

# 可选：?
grep -n "function_name_?()"

# 一次或多次：+
grep -n "[A-Z_]+"

# 零次或多次：*
grep -n "import.*"

# 选择：|
grep -n "TODO|FIXME"

# 组：()
grep -n "(get|set)_user"

# 转义特殊字符：\
grep -n "function\(\)"

最佳实践

1. 从语义搜索开始：对于不熟悉的代码或概念性问题
2. 使用 grep 进行精确搜索：当您知道确切术语时
3. 组合多次搜索：逐步构建理解
4. 阅读周围上下文：不要只看匹配的行
5. 检查文件历史：使用 git blame 获取上下文
6. 记录发现：记下重要发现
7. 验证假设：阅读实际代码，不要猜测
8. 使用目录定位：尽可能缩小范围
9. 跟踪数据流：追踪数据在系统中的流动
10. 检查测试：测试通常显示使用示例

常见搜索场景

场景 1：理解一个错误

1. 查找错误消息
   Grep：“确切的错误消息”

2. 查找它被抛出的地方
   读取：包含错误的文件

3. 查找什么触发了它
   语义：“是什么导致 X 错误？”

4. 查找相关代码
   Grep：相关的函数名

5. 检查测试
   Glob：“**/*test*.py”
   查找：相关的测试用例

场景 2：学习一个新的代码库

1. 查找入口点
   语义：“应用程序从哪里开始？”
   常见文件：main.py， index.js, app.py

2. 查找主要路由/端点
   Grep：“route|endpoint|@app\\.”

3. 查找数据模型
   语义：“数据模型在哪里定义？”
   常见：models/， entities/

4. 查找配置
   Glob：“**/*config*”

5. 阅读 README 和文档
   读取：README.md， docs/

场景 3：重构准备

1. 查找所有使用点
   Grep：“function_to_change”

2. 查找测试
   Grep：“test.*function_to_change”

3. 查找依赖项
   语义：“X 依赖于什么？”

4. 检查导入
   Grep：“from.*import.*X”

5. 记录范围
   列出：所有受影响的文件

场景 4：添加功能

1. 查找类似功能
   语义：“类似的功能是如何实现的？”

2. 查找添加代码的位置
   语义：“新功能应该放在哪里？”

3. 检查模式
   读取：类似的实现

4. 查找要模仿的测试
   Glob：类似功能的测试文件

5. 检查文档
   Grep：“TODO.*new feature” -i

工具集成

Git 集成：

# 谁更改了这行？
git blame filename

# 文件的历史记录
git log -p filename

# 查找函数何时被添加
git log -S "function_name" --source --all

# 查找提到 X 的提交
git log --grep="feature name"

IDE 集成：

• 使用“转到定义”进行快速导航
• 使用“查找所有引用”查看使用情况
• 使用“在文件中查找”进行广泛搜索
• 使用符号搜索查找类/函数

文档：

• 检查内联注释
• 查找文档字符串
• 阅读 README 文件
• 检查架构文档

故障排除

未找到结果：

• 检查拼写和大小写敏感
• 尝试语义搜索而不是 grep
• 扩大搜索范围（移除目录目标）
• 尝试不同的搜索词
• 检查文件是否在 .gitignore 中

结果太多：

• 添加目录定位
• 使用更具体的模式
• 按文件类型过滤
• 使用精确短语（引号）

结果错误：

• 在查询中更具体
• 对精确术语使用 grep 而不是语义搜索
• 为语义查询添加上下文
• 检查文件类型

参考资料

• Ripgrep 用户指南
• 正则表达式教程
• Git Blame 指南

示例

示例 1：基本用法

示例 2：高级用法