feat: 根目录文档、脚本、gitignore

2026-10-08 16:15:33 +08:00
commit e98660ce4e
284 changed files with 26838 additions and 0 deletions
@@ -0,0 +1,372 @@
+# jdtls (Java Language Server) 使用指南
+
+> 通过 Serena MCP 工具调用 jdtls 进行 Java 代码分析
+
+## 前置条件
+
+### 1. 确保 jdtls 已安装
+
+jdtls 通常通过 VS Code 的 Java 扩展自动安装，或者手动安装：
+
+```bash
+# 检查 jdtls 路径
+which jdtls
+# 或
+ls ~/.vscode/extensions/redhat.java-*/server/
+```
+
+### 2. 项目结构要求
+
+jdtls 需要以下文件来识别 Java 项目：
+
+- Maven: `pom.xml`
+- Gradle: `build.gradle` 或 `build.gradle.kts`
+- Eclipse: `.project` 和 `.classpath`
+
+---
+
+## 通过 Serena 使用 jdtls
+
+### 激活项目
+
+```yaml
+# Step 1: 激活 Java 项目
+tool: mcp__serena__activate_project
+params:
+  project: "/path/to/java/project"
+
+# 返回: 项目已激活，jdtls 已初始化
+```
+
+### 验证配置
+
+```yaml
+# 检查当前配置
+tool: mcp__serena__get_current_config
+
+# 确认输出包含:
+# - active_project: /path/to/java/project
+# - language_server: jdtls
+```
+
+---
+
+## 符号提取操作
+
+### 获取文件符号概览
+
+```yaml
+# 获取单个文件的符号列表（不含代码体）
+tool: mcp__serena__get_symbols_overview
+params:
+  relative_path: "src/main/java/com/example/OrderController.java"
+  depth: 1      # 0=仅顶层, 1=含直接成员, 2=含嵌套成员
+
+# 返回示例:
+# Classes:
+#   - OrderController (class) [59-1241]
+# Methods:
+#   - getOrderList (method) [120-145]
+#   - createOrder (method) [150-180]
+#   - updateOrder (method) [185-210]
+```
+
+### 查找符号
+
+```yaml
+# 按名称模式查找符号
+tool: mcp__serena__find_symbol
+params:
+  name_path_pattern: "OrderController"    # 可以是部分名称
+  relative_path: "src/main/java/"         # 限定搜索范围
+  include_body: false                     # 是否包含代码体
+  include_info: true                      # 是否包含 hover 信息
+  depth: 1                                # 包含成员的深度
+
+# 名称模式规则:
+# - "OrderController"           -> 匹配任何包含此名称的符号
+# - "controller/OrderController" -> 匹配此路径后缀
+# - "/com.example.OrderController" -> 精确匹配完整路径
+# - "OrderController/getOrderList" -> 匹配类中的方法
+# - "OrderController[0]"        -> 匹配重载方法的第一个
+```
+
+### 获取符号详情（含代码体）
+
+```yaml
+# 获取完整的符号定义（含代码）
+tool: mcp__serena__find_symbol
+params:
+  name_path_pattern: "OrderService/saveOrder"
+  relative_path: "src/main/java/com/example/service/OrderService.java"
+  include_body: true
+  depth: 0
+
+# 返回包含:
+# - 方法签名
+# - Javadoc 注释
+# - 完整方法体
+# - 行号范围
+```
+
+---
+
+## 引用分析操作
+
+### 查找符号引用
+
+```yaml
+# 查找某个符号被哪些地方引用
+tool: mcp__serena__find_referencing_symbols
+params:
+  name_path: "OrderService/saveOrder"
+  relative_path: "src/main/java/com/example/service/OrderService.java"
+  include_info: true
+
+# 返回示例:
+# References (5 found):
+#   - OrderController.createOrder [180:12-180:35]
+#     snippet: "orderService.saveOrder(dto)"
+#   - OrderController.updateOrder [210:12-210:35]
+#     snippet: "orderService.saveOrder(updated)"
+#   - OrderServiceTest.testSave [45:8-45:30]
+#     snippet: "service.saveOrder(testDto)"
+```
+
+### 模式搜索（补充 LSP）
+
+```yaml
+# 当 LSP 无法找到时，使用模式搜索
+tool: mcp__serena__search_for_pattern
+params:
+  substring_pattern: "orderService\\.save"
+  paths_include_glob: "**/*.java"
+  restrict_search_to_code_files: true
+  context_lines_before: 2
+  context_lines_after: 2
+
+# 适用场景:
+# - 动态调用 (反射)
+# - 字符串拼接的方法名
+# - 注解中的引用
+```
+
+---
+
+## 调用链构建
+
+### 构建向下调用链 (callee)
+
+```python
+# 伪代码: 递归构建调用链
+
+def build_callee_chain(symbol_path, file_path, depth, max_depth):
+    if depth > max_depth:
+        return None
+
+    # Step 1: 获取方法体
+    symbol = find_symbol(
+        name_path_pattern=symbol_path,
+        relative_path=file_path,
+        include_body=True
+    )
+
+    # Step 2: 在方法体中查找调用
+    # 使用 LSP 或正则匹配
+    calls = extract_method_calls(symbol.body)
+
+    # Step 3: 对每个调用递归
+    callees = []
+    for call in calls:
+        # 尝试定位被调用方法
+        target = find_symbol(
+            name_path_pattern=call.method_name,
+            relative_path=call.potential_file
+        )
+        if target:
+            callees.append({
+                'symbol': target,
+                'evidence': call.location,
+                'children': build_callee_chain(
+                    target.path, target.file, depth + 1, max_depth
+                )
+            })
+
+    return {
+        'symbol': symbol,
+        'callees': callees
+    }
+```
+
+### 实际操作步骤
+
+```yaml
+# 1. 获取入口方法
+tool: mcp__serena__find_symbol
+params:
+  name_path_pattern: "OrderController/createOrder"
+  relative_path: "src/main/java/com/example/controller/"
+  include_body: true
+  depth: 0
+
+# 2. 分析方法体中的调用
+# 从返回的 body 中提取: orderService.saveOrder(dto)
+
+# 3. 定位被调用方法
+tool: mcp__serena__find_symbol
+params:
+  name_path_pattern: "OrderService/saveOrder"
+  relative_path: "src/main/java/"
+  include_body: true
+
+# 4. 查找该方法的引用（验证调用关系）
+tool: mcp__serena__find_referencing_symbols
+params:
+  name_path: "OrderService/saveOrder"
+  relative_path: "src/main/java/com/example/service/OrderService.java"
+
+# 5. 递归处理下一层
+```
+
+---
+
+## Java 特有处理
+
+### 注解识别
+
+```yaml
+# 常见注解及其语义含义
+
+API 入口点注解:
+  - "@RestController": REST API 控制器
+  - "@Controller": MVC 控制器
+  - "@RequestMapping": 请求映射
+  - "@GetMapping": GET 请求
+  - "@PostMapping": POST 请求
+  - "@PutMapping": PUT 请求
+  - "@DeleteMapping": DELETE 请求
+
+服务层注解:
+  - "@Service": 业务服务
+  - "@Component": 通用组件
+  - "@Transactional": 事务方法
+
+数据层注解:
+  - "@Repository": 数据访问
+  - "@Mapper": MyBatis Mapper
+  - "@Table": JPA 表映射
+  - "@Entity": JPA 实体
+
+数据对象注解:
+  - "@Data": Lombok 数据类
+  - "@Getter/@Setter": Lombok 访问器
+  - "@Builder": Lombok 构建器
+```
+
+### MyBatis Mapper 处理
+
+```yaml
+# MyBatis Mapper 接口无法通过 LSP 追踪到 SQL
+# 需要关联 XML 文件
+
+# 1. 找到 Mapper 接口
+tool: mcp__serena__find_symbol
+params:
+  name_path_pattern: "OrderMapper"
+  relative_path: "src/main/java/"
+
+# 2. 查找对应的 XML
+tool: mcp__serena__search_for_pattern
+params:
+  substring_pattern: "OrderMapper"
+  paths_include_glob: "**/*.xml"
+
+# 3. 读取 XML 获取 SQL 定义
+tool: mcp__serena__list_dir
+params:
+  relative_path: "src/main/resources/mapper/"
+```
+
+---
+
+## LSP SymbolKind 映射
+
+```yaml
+# jdtls 返回的 SymbolKind 数值对照
+
+1: File
+2: Module
+3: Namespace
+4: Package
+5: Class           # 类
+6: Method          # 方法
+7: Property
+8: Field           # 字段
+9: Constructor     # 构造函数
+10: Enum           # 枚举
+11: Interface      # 接口
+12: Function       # 函数
+13: Variable       # 变量
+14: Constant       # 常量
+15: String
+16: Number
+17: Boolean
+18: Array
+19: Object
+20: Key
+21: Null
+22: EnumMember     # 枚举值
+23: Struct
+24: Event
+25: Operator
+26: TypeParameter  # 泛型参数
+```
+
+---
+
+## 常见问题
+
+### Q: jdtls 启动慢
+
+```
+A: 首次打开项目时，jdtls 需要构建索引。
+   - Maven 项目: 会下载依赖
+   - 大项目: 索引可能需要几分钟
+   建议: 等待 Serena 报告项目就绪
+```
+
+### Q: 找不到符号
+
+```
+A: 可能原因:
+   1. 项目未正确识别 (缺少 pom.xml 或 build.gradle)
+   2. 编译错误导致索引不完整
+   3. 符号在排除目录中
+
+解决:
+   1. 确保项目根目录正确
+   2. 先执行 mvn compile 或 gradle build
+   3. 使用 search_for_pattern 作为备选
+```
+
+### Q: 引用结果不完整
+
+```
+A: jdtls 的 references 可能遗漏:
+   1. 反射调用
+   2. 字符串拼接的方法名
+   3. 动态代理
+
+解决:
+   使用 search_for_pattern 补充搜索
+```
+
+---
+
+## 最佳实践
+
+1. **先概览后详细** - 用 `get_symbols_overview` 了解文件结构，再用 `find_symbol` 获取详情
+2. **限定搜索范围** - 总是传入 `relative_path` 以提高效率
+3. **分批处理** - 大项目分模块处理，避免一次性加载全部
+4. **缓存结果** - 符号信息变化不频繁，可以缓存复用
+5. **结合搜索** - LSP 不足时用 `search_for_pattern` 补充