Complete local setup development guide for Konveyor Analyzer-lsp 🚀

概述

现代化大型复杂代码库是一项重大挑战。识别迁移障碍、已弃用的API和技术特定模式需要深入准确的代码分析。Konveyor Analyzer LSP通过提供灵活强大的静态分析引擎来解决这个问题。它独特地利用语言服务器协议（LSP）来获取多种语言的丰富IDE级代码智能。

Konveyor analyzer-lsp是一个强大的代码分析引擎，通过语言服务器协议（LSP）集成支持多种编程语言。本指南将引导您完成完整的本地开发环境设置，包括Java（JDT-LS）、Go、Python、Node.js和YAML提供程序。

先决条件

在开始之前，您需要一些基本工具。每个工具在生态系统中都扮演着特定角色：Go用于编译核心分析器本身，而Java和Maven是JDT语言服务器所必需的，它为Java项目提供深度分析能力。Podman或Docker用于管理容器化的语言提供程序，确保清洁隔离的环境。最后，Git用于克隆项目仓库。

Go 1.23.9+ - 用于构建分析器
Java 17+ - JDT-LS必需
Maven - 用于Java依赖解析
Podman/Docker - 用于外部提供程序容器
Git - 用于克隆仓库

设置过程

设置过程包括两个主要阶段。首先，我们将克隆源代码并构建konveyor-analyzer命令行工具，这是协调分析的核心引擎。其次，我们将构建并运行各种特定语言的提供程序作为容器化服务。这将创建一个本地微生态系统，中央分析器可以与每个语言服务器通信以检查代码。

1. 克隆和构建

1
2
3
4
5
6
7
8


git clone https://github.com/konveyor/analyzer-lsp.git
cd analyzer-lsp

# 构建主分析器二进制文件
make analyzer

# 构建所有外部提供程序
make build

这将创建：

konveyor-analyzer - 主分析器二进制文件（25MB）
konveyor-analyzer-dep - 依赖分析器（24MB）
外部提供程序二进制文件和Docker镜像

2. 启动外部提供程序

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28


# 启动Podman机器（如果未运行）
podman machine start

# 构建提供程序镜像
make build-java-provider
make build-yq-provider
make build-generic-provider

# 启动所有提供程序
podman run --name java-provider -d -p 14651:14651 \
  -v $(pwd)/external-providers/java-external-provider/examples:/examples \
  java-provider --port 14651

podman run --name yq -d -p 14652:14652 \
  -v $(pwd)/examples:/examples \
  yq-provider --port 14652

podman run --name golang-provider -d -p 14653:14653 \
  -v $(pwd)/examples:/examples \
  generic-provider --port 14653

podman run --name nodejs -d -p 14654:14654 \
  -v $(pwd)/examples:/examples \
  generic-provider --port 14654 --name nodejs

podman run --name python -d -p 14655:14655 \
  -v $(pwd)/examples:/examples \
  generic-provider --port 14655 --name pylsp

3. 验证设置

1
2
3
4
5
6


# 检查运行的提供程序
podman ps

# 测试基本功能
./konveyor-analyzer --provider-settings provider_local_dev.json \
  --rules rule-example.yaml --output-file output.yaml --verbose 5

规则开发

这是分析器真正发挥作用的地方。您无需编写复杂的编程检查，而是在YAML中定义声明性规则。这些"Kantra规则"是操作的核心，告诉分析器在代码中精确查找什么。这种方法使得创建、共享和维护针对组织特定现代化目标定制的检查库变得容易。

理解Kantra规则

Kantra规则是基于YAML的配置，用于定义代码分析模式。每个规则包含：

1
2
3
4
5
6
7
8
9


ruleID: my-custom-rule
message: "Found deprecated API usage"
description: "Detects usage of deprecated APIs"
category: mandatory
effort: 3
when:
  java.referenced:
    pattern: "java\\.util\\.Date"
    location: "method"

规则结构

1
2
3
4
5
6
7
8


ruleID: unique-rule-identifier
message: "Human-readable violation message"
description: "Detailed rule description"
category: mandatory|optional|potential
effort: 1-5  # Migration effort estimate
labels: ["tag1", "tag2"]
when:
  # Condition logic using provider capabilities

提供程序能力

Java提供程序（JDT-LS）

1
2
3
4
5


when:
  java.referenced:
    pattern: "com\\.example\\.OldClass"
    location: "class"  # class, method, field, annotation, etc.
    annotation: "Deprecated"

内置提供程序

1
2
3
4
5


when:
  builtin.file:
    pattern: "*.xml"
  builtin.xml:
    xpath: "//dependency[groupId='javax.servlet']"

Go提供程序

1
2
3
4


when:
  go.referenced:
    pattern: "oldpackage"
    location: "import"

创建自定义规则

创建新的规则文件：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


cat > my-rules.yaml << EOF
rulesets:
  - name: "custom-rules"
    description: "My custom analysis rules"
    rules:
      - ruleID: deprecated-api-usage
        message: "Found deprecated API usage"
        description: "Detects usage of deprecated APIs in Java code"
        category: mandatory
        effort: 3
        when:
          java.referenced:
            pattern: "java\\.util\\.Date"
            location: "method"
EOF

测试您的规则：

1
2


./konveyor-analyzer --provider-settings provider_local_dev.json \
  --rules my-rules.yaml --output-file results.yaml

测试和验证

编写规则只是第一步；确保它正常工作且不产生误报至关重要。本节涵盖测试规则的基本工作流程。您将学习如何针对示例代码执行分析器，根据官方模式验证规则语法，以及使用日志记录和调试工具来排查遇到的问题。

运行分析

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


# 基本分析
./konveyor-analyzer --rules rule-example.yaml --output-file output.yaml

# 使用特定提供程序设置
./konveyor-analyzer --provider-settings provider_local_dev.json \
  --rules rule-example.yaml --output-file output.yaml

# 详细日志记录用于调试
./konveyor-analyzer --provider-settings provider_local_dev.json \
  --rules rule-example.yaml --output-file output.yaml --verbose 5

验证规则

1
2
3
4
5


# 生成OpenAPI规范用于模式验证
./konveyor-analyzer --get-openapi-spec openapi-spec.json

# 检查规则语法
./konveyor-analyzer --rules my-rules.yaml --dry-run

调试常见问题

提供程序连接问题：

1
2
3
4
5
6


# 检查提供程序状态
podman ps
podman logs java-provider

# 测试提供程序连接性
curl http://localhost:14651/health

规则解析错误：

1
2
3
4
5


# 验证YAML语法
yamllint my-rules.yaml

# 检查OpenAPI模式合规性
./konveyor-analyzer --get-openapi-spec schema.json

文件路径问题：

1
2
3


# 验证示例文件存在
ls -la examples/java/
ls -la examples/golang/

高级配置

虽然默认设置非常适合入门，但实际项目通常需要更定制的配置。本节探讨分析器的高级功能，从为复杂项目布局定制提供程序设置到编写将条件链接在一起的复杂规则。掌握这些配置将使您能够处理最独特的分析场景。

提供程序设置

在provider_local_dev.json中创建自定义提供程序配置：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


[
  {
    "name": "java",
    "address": "localhost:14651",
    "initConfig": [
      {
        "location": "path/to/java/project",
        "analysisMode": "source-only",
        "providerSpecificConfig": {
          "lspServerName": "java",
          "bundles": "/jdtls/java-analyzer-bundle.jar",
          "lspServerPath": "/jdtls/bin/jdtls"
        }
      }
    ]
  }
]

分析模式

source-only：仅分析源代码
full：包含依赖分析

自定义变量和链式调用

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


when:
  and:
    - java.referenced:
        pattern: "com\\.example\\.Service"
        location: "class"
        as: "service"
    - java.referenced:
        pattern: "com\\.example\\.Repository"
        location: "class"
        from: "service"  # 引用先前的条件

输出分析

分析运行完成后，分析器会生成一个结构化的YAML文件，包含其发现结果。此输出设计为既人类可读又机器可解析，便于一目了然地理解结果或将其集成到其他工具、CI/CD管道或自定义报告仪表板中。在这里，我们将分解输出文件的结构。

理解结果

分析器生成YAML输出，包含：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


- name: konveyor-analysis
  tags: ["Java", "Backend"]
  violations:
    rule-id:
      description: "Rule description"
      category: mandatory
      incidents:
        - uri: "file:///path/to/file.java"
          message: "Violation message"
          codeSnip: "source code snippet"
          lineNumber: 42
          variables:
            captured: "value"
      effort: 3

过滤结果

1
2
3
4
5
6
7


# 按类别过滤
./konveyor-analyzer --rules my-rules.yaml \
  --label-selector "category=mandatory"

# 限制事件数量
./konveyor-analyzer --rules my-rules.yaml \
  --limit-incidents 100

开发工作流程

有效使用analyzer-lsp遵循迭代开发周期。本节概述了创建、测试和完善规则的实际可重复工作流程。通过采用这种结构化方法，您可以高效地构建强大的规则集，为现代化项目提供准确且可操作的见解。

1. 规则开发周期

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


# 1. 创建/编辑规则
vim my-rules.yaml

# 2. 测试规则
./konveyor-analyzer --rules my-rules.yaml --output-file test.yaml

# 3. 验证结果
cat test.yaml

# 4. 迭代和完善

2. 集成测试

1
2
3
4
5
6
7


# 使用多个规则集测试
./konveyor-analyzer --rules "rule-example.yaml,my-rules.yaml" \
  --output-file combined-results.yaml

# 使用不同的提供程序配置测试
./konveyor-analyzer --provider-settings custom-providers.json \
  --rules my-rules.yaml

3. 性能优化

1
2
3
4
5


# 对大文件限制代码片段
./konveyor-analyzer --limit-code-snips 10 --rules my-rules.yaml

# 使用事件选择器进行过滤
./konveyor-analyzer --incident-selector "effort<3" --rules my-rules.yaml

最佳实践

遵循既定的最佳实践将帮助您编写不仅有效而且可维护和高性能的规则。本节提供从社区经验中提炼的关键建议，涵盖从如何设计清晰高效的规则到针对大型复杂代码库测试它们的策略。

规则设计

使用描述性规则ID：java-deprecated-api-usage vs rule1
提供清晰的消息：帮助开发人员理解问题
设置适当的工作量级别：1-5级的迁移复杂度
使用有意义的类别：mandatory、optional、potential

性能

限制事件数量：对大代码库使用--limit-incidents
按标签过滤：使用--label-selector专注于特定规则
优化模式：使用高效的正则表达式模式
使用链式调用：利用as和from处理复杂条件

测试

增量测试：从简单规则开始，逐步增加复杂性
验证模式：使用OpenAPI规范进行规则验证
检查提供程序日志：监控提供程序容器的问题
使用详细日志记录：使用--verbose 5进行调试

🔍 故障排除

常见问题

问题	解决方案
提供程序连接失败	检查`podman ps`并重启容器
规则解析错误	验证YAML语法和OpenAPI模式
未发现违规	检查文件路径和规则模式
性能问题	使用事件限制和过滤

获取帮助

日志：使用--verbose 5获取详细日志记录
提供程序日志：podman logs <container-name>
模式验证：生成OpenAPI规范进行规则验证
社区：查看Konveyor文档和GitHub问题

结论

您现在拥有一个完全可操作的analyzer-lsp开发环境，包括：

使用JDT-LS进行Java代码分析
多语言支持（Go、Python、Node.js、YAML）
规则开发和测试能力
OpenAPI模式生成用于验证
全面的代码分析工作流程

开始为您的代码库构建强大的迁移和现代化规则！

有关更多信息，请访问Konveyor slack或查看analyzer-lsp仓库。

Konveyor Analyzer-lsp 完整本地开发环境搭建指南 🚀

本文详细介绍了如何搭建Konveyor Analyzer-lsp的完整本地开发环境，包括构建核心分析器、配置多语言提供程序、创建Kantra规则以及测试验证流程。涵盖Java、Go、Python等语言支持，提供从基础设置到高级配置的完整开发指南。