创建应用现代化评估

Migration Center App Modernization Assessment (codmod) 是一款 AI 赋能的工具，可自动执行应用的现代化改造评估流程。本页概述了安装、使用 codmod 工具以及排查其问题的步骤。

关于应用现代化改造评估

典型的现代化改造评估流程需要几周时间，并且需要大量专业知识。通过自动执行此过程，codmod 工具可将此时间显著缩短到几个小时。

此工具旨在提供有关当前应用的架构、功能和可能减缓向云端转换的潜在阻碍因素的循证信息。

此工具适用于以下角色：

  • IT 架构师
  • 决策者
  • 应用所有者

codmod 工具旨在通过清晰地展示所需的更改以及将应用转换为 Google Cloud所带来的好处，加快应用转换速度。codmod 是一款便携式 CLI 工具，它使用 Gemini 分析源代码，并根据 Google Cloud 最佳实践提供建议。

准备工作

codmod 工具需要满足以下前提条件：

  • Linux 或 Windows（10 或更高版本）工作站。
  • 有权访问已启用 Vertex AI API 的 Google Cloud 项目。
  • 在工作站上安装 gcloud CLI。如需了解详情，请参阅安装 gcloud CLI。

价格

使用 Gemini 进行代码评估的费用主要取决于代码库的大小，并以 token 为单位进行衡量。下表显示了您预计会看到的费用估算值，具体取决于您的代码行数和所选模型：

代码库 代码行数 (LOC) 估算费用
自适应 2.5-flash 2.5-pro 3.5-flash 3.8-flash（默认）
Spring Petclinic ~6,500 $20 $3 $20 $3 $9
James Project ~1,000,000 $40 $30 $200 $200 $200
Elasticsearch ~5,000,000 $200 $200 $900 $500 $500

这些值可能被高估，因为它们没有考虑以下因素可能带来的节省：

  • 降低了简短查询的价格。
  • 隐式缓存的价格更低。
  • 承诺使用折扣 (CUD)。

这些参数的费用预计在总费用中占比微乎其微，尤其是对于较大的代码库。如需了解详情，请参阅 Gemini API 价格。

其他信息

该工具使用 Vertex AI API 的高级代码理解和分析功能。如需详细了解可用模型及其功能，请参阅 Vertex AI API 文档中的 Google 模型。

为了保持最佳性能和成本效益，codmod 的代码库大小限制约为 600 万行代码。对于超出此限制的代码库，我们建议将其拆分为更小、更易于管理的部分进行分析。分析较小的部分也有助于进行更集中的评估，并可能缩短总体处理时间。

设置 codmod

本部分提供了使用 codmod 工具的安装和身份验证说明。

安装 codmod

Windows

在 Windows PowerShell 中运行以下命令，下载最新版本的 codmod：

$version=curl.exe -s https://codmod-release.storage.googleapis.com/latest
curl.exe -O "https://codmod-release.storage.googleapis.com/${version}/windows/amd64/codmod.exe"

Linux

运行以下命令，下载最新版本的 codmod：

version=$(curl -s https://codmod-release.storage.googleapis.com/latest)
curl -O "https://codmod-release.storage.googleapis.com/${version}/linux/amd64/codmod"
chmod +x codmod

如需使用 codmod 命令，请将可执行文件添加到路径中，或创建别名。

向 Google Cloud进行身份验证

如需使用 codmod 工具，您需要一个 Google Cloud 项目。

  1. 在控制台中或使用 CLI 确保已在项目中启用 Vertex AI API：

    gcloud services enable aiplatform.googleapis.com --project <project-id>

  2. 确保您在项目中拥有 roles/aiplatform.user 角色或类似角色。

  3. 如需进行身份验证，请运行以下命令：

    gcloud auth application-default login

或者，您也可以使用服务账号并设置 GOOGLE_APPLICATION_CREDENTIALS 环境变量。如需了解详情，请参阅应用默认凭证的工作原理。

管理 codmod 配置

以下部分介绍了如何使用 codmod config 命令配置 codmod。

列出所有设置

如需查看所有当前配置属性及其值，请运行以下命令：

codmod config list

为标志设置默认值

如需为属性设置默认值，请使用 set 命令。例如，如需设置默认项目 ID，请运行以下命令：

codmod config set project "PROJECT_ID"

将 PROJECT_ID 替换为 Google Cloud 项目 ID。

如需设置默认区域，请运行以下命令：

codmod config set region "REGION"

将 REGION 替换为 Google Cloud 区域。请参阅可用区域列表。 如果您不确定要使用哪个区域，请使用 us-central1。

获取特定值

如需查看单个属性的值，请使用 get 命令。例如，如需获取已配置的项目 ID，请运行以下命令：

codmod config get project

取消设置默认值

如需移除已配置的默认值并还原为工具的原始默认设置，请使用 unset 命令。例如，如需移除默认项目 ID，请运行以下命令：

codmod config unset project

创建 codmod 评估报告

以下部分介绍了如何创建默认评估，以及如何根据需要对其进行自定义。

创建默认报告

如需创建评估报告，请运行带有以下标志的 codmod 工具：

codmod create -c "CODEBASE" -o "OUTPUT"

替换以下内容：

  • CODEBASE：指定包含要分析的源代码的目录，可以指定多次。
  • OUTPUT：指定生成的报告的保存路径。报告采用 HTML 格式。

您可以使用 -p "PROJECT_ID" 和 -r "REGION" 标志分别替换默认项目和区域。

您还可以指定以下可选标志：

  • --modelset [2.5-flash|2.5-pro|3.5-flash|3.8-flash|adaptive]：指定要使用的 Gemini 模型。默认值为 3.8-flash。与 2.5-pro 相比，自适应模式可显著降低费用，但可能会牺牲报告质量。
  • --format <html|markdown|odt|json>：生成的报告所使用的格式。默认值为 HTML。
  • --allow-large-codebase：默认情况下，codmod 会在分析超过 100 万行代码的代码库之前请求确认，以避免产生高昂费用。此选项用作非交互式确认。您还可以通过运行 codmod config set allow_large_codebase true 默认启用此功能。
  • --improve-fidelity：设置后，codmod 会串行（而非并行）生成章节。这可以提高最终报告不同部分之间的一致性，但需要更长的运行时间。
  • --force-include <strings>、--force-exclude <strings>：默认情况下，codmod 会扫描常见的文件扩展名，包括 Java、.NET 和 Python。使用这些标志可包含或排除文件扩展名。参数必须是采用 RE2 语法的正则表达式。
  • --experiments：指定 --experiments=enable_pdf,enable_images 以支持 codmod 中的 PDF 和图片。
  • --context <string>：您要提供的有关项目的任何其他背景信息。该工具在生成报告时会考虑这些上下文信息。
  • --context-file <path>：与 --context 相同，其中上下文在给定文件中提供。
  • --supporting-documents <path>：指定包含代码库相关支持文档的目录。此目录中的文件可以从 --context 或 --context-file 标志提供的上下文中引用，以包含在分析中。支持的格式包括文本、PDF 和图片（PNG、JPG、JPEG）。

创建完整报告

如果您需要完整分析，请使用 create full 命令创建报告：

codmod create full -c "~/mycodebase/" -o "report.html"

创建侧重于数据层的报告

如果需要更深入地关注数据层，可以创建一份侧重于此领域的报告：

codmod create data-layer -c "CODEBASE" -o "OUTPUT"

为特定转换意图创建报告

如果您希望报告侧重于特定的现代化改造意图，可以使用以下受支持的意图之一：

  • Microsoft 工作负载转换 (MICROSOFT_MODERNIZATION)：与在 Microsoft 操作系统上运行的应用搭配使用，评估将侧重于转换历程，这些历程将对基于 .NET 的框架进行现代化改造，以使用最新版本并减少对 Microsoft 许可的依赖。
  • 云到云工作负载转换 (CLOUD_TO_CLOUD)：与在其他超大规模基础设施上运行的应用搭配使用。评估将重点关注为转换应用而建议的更改，例如将其他云供应商服务映射到Google Cloud 服务。
  • 旧版 Java 转换 (JAVA_LEGACY_TO_MODERN)：适用于运行 Java 8 或类似版本的应用，评估将重点查找升级依赖项以及代码中受更改为 Java 21（当前 LTS）影响的区域。
  • 旧版 Java WILDFLY 转换 (WILDFLY_LEGACY_TO_MODERN)：适用于在最新版本之前的 WildFly 应用服务器版本上运行的 Java EE/Jakarta EE 代码库。评估将重点识别升级依赖项以及受 WildFly 应用服务器版本升级影响的代码区域，包括 API 差异和兼容性所需的更改。
  • C/C++ 应用到 Arm 架构迁移 (ARM_MIGRATION)：与 C/C++ 应用搭配使用，可评估其就绪情况以及从基于 x86 的架构迁移到基于 Arm 的架构（例如 Google Cloud Axion C4A 虚拟机）所需的工作量。评估重点在于确定潜在的代码可移植性问题、特定于架构的依赖项、构建系统修改，以及从Google Cloud 或其他 CSP（例如 AWS 的 Graviton 实例）成功过渡到 Arm 所需的测试注意事项。

如需创建意图聚焦报告，请使用 --intent 标志：

codmod create -c "CODEBASE" -o "OUTPUT" --intent "INTENT"

创建包含其他部分的报告

该工具支持添加默认情况下不包含的其他部分，以降低费用。支持以下部分：

  • files：项目文件夹的结构化分层视图以及每个文件夹内容的说明，可帮助您了解项目文件。
  • classes：代码类的目录，其中包含每个类及其对其他类的依赖项的相关信息。支持的语言包括 Java 和 C#。

如需创建其他部分，请使用 --optional-sections 标志：

codmod create -c "CODEBASE" -o "OUTPUT" --optional-sections "SECTIONS"

将 SECTIONS 替换为逗号分隔列表。

创建自定义报告

如果您想探索一些特定的自定义主题，可以使用以下命令根据您提供的上下文创建自定义报告：

codmod create custom -c "CODEBASE" -o "OUTPUT" --context "CONTEXT"

默认情况下，系统会使用 LLM 扩展所提供的上下文并对其进行调整，以确保生成连贯的部分。您可以通过指定 --improve-context=false 来停用此行为。

其他标志：

  • --from-template <path>：指定一个模板文件，该文件以文本或 PDF 文件格式定义文档结构。codmod 会检测结构，并请求批准以继续生成报告。
  • --skip-template-approval：使用 --from-template 标志时跳过审批请求。

修改现有报告

您可以根据特定部分在报告中创建新部分或修改现有部分。例如，您可能希望专注于系统架构的特定方面或特定类型的安全漏洞。

修改报告的命令需要以下标志：

  • --context 和 --context-file 之一：指定修改请求。
  • --from-report：指定现有报告文件的路径。
  • --from-section：要用作新部分基础的部分的名称（例如“概览”或“架构”）。

如需显示特定报告中的所有可用部分，请运行以下命令：

codmod list-sections --from-report "REPORT"

修改报告部分

运行以下命令，修改现有部分：

codmod revise section -c "CODEBASE" --from-report "REPORT" \
  -o "REVISED_REPORT" --from-section "SECTION_NAME" \
  --context "CONTEXT"

创建新的报告部分

使用以下命令创建新部分：

codmod create section -c "CODEBASE" --from-report "REPORT" \
  -o "REGENERATED_REPORT" --from-section "SECTION_NAME" \
  --context "CONTEXT"
  • create section 命令中的 from-section 标志是可选的。
  • 默认情况下，系统会使用 LLM 扩展所提供的上下文并对其进行调整，以确保生成连贯的内容。您可以通过指定 --improve-context=false 来停用此行为。

请注意以下几点：

  • create section 和 revise section 仅支持 html 报告格式。
  • create section、revise section、list-sections 预期 --from-report 标志指向 HTML 格式的报告。

估算评估费用

codmod 工具可让您计算创建报告的大致费用，从而帮助您了解使用该工具的费用。如需查看费用估算，请运行以下命令：

codmod create --estimate-cost -c "CODEBASE"

create section 和 create custom 命令不支持费用估算。

设置详细程度

codmod 详细程度使用 --verbosity LEVEL 标志进行配置。 日志的详细程度级别为以下之一：debug、info、warn、error 或 none。默认值为 warn。

检查并更新 codmod CLI 版本

codmod CLI 可以自动检查是否有更新的版本。

自动检查

CLI 每 24 小时轮询一次 Cloud Storage 存储桶，以查看是否发布了较新版本的 codmod。如果发现较新版本，您会在终端上看到一条通知消息。 该消息包含新版本号和下载更新的链接。 此流程有助于确保您能及时了解最新功能、改进和 bug 修复。

停用版本检查

如果您希望停用自动版本检查，可以使用 config set 命令：

codmod config set disable_version_check true

如需重新启用版本检查，请将值设置回 false：

codmod config set disable_version_check false

您可以通过运行以下命令来查看此设置和其他配置的当前状态：

codmod config list

命令行补全

codmod CLI 工具支持 Bash、Zsh、Fish 和 PowerShell 的 shell 命令行补全功能。此功能可帮助您快速输入命令、标志和参数，只需按 Tab 键即可查看和选择可用选项。

自动补全功能具有以下优势：

  • 自动补全命令和标志：开始输入 codmod 命令或标志，然后按 Tab 即可查看可能的补全内容。
  • 发现选项：查看某些标志的有效值。例如：
    • codmod create --modelset [TAB] 会建议可用的模型集（例如 2.0-flash、2.5-pro）。
    • codmod create --format [TAB] 建议输出格式（例如 html、json、markdown）。
    • codmod create --intent [TAB] 会建议预定义的 intent。
  • 情境感知建议：补全功能会根据命令进行调整。 例如：
    • codmod config set [TAB] 会建议您可以设置的可用配置键。
    • codmod config get [TAB] 会建议您可以获取的可用配置键。
    • 仅针对需要文件或目录路径的标志或参数（例如 --codebase、--output-path）提供文件路径补全功能。其他标志（例如 --project）不再建议文件名。

启用 shell 补全

在启用 shell 补全之前，请确保 codmod 命令正常运行，方法是将可执行文件添加到路径或创建别名。

如需为 shell 加载补全，请运行相应的命令。说明因 shell 而异。使用 help 命令获取具体说明：

# For Bash
codmod completion bash --help

# For Zsh
codmod completion zsh --help

# For Fish
codmod completion fish --help

# For PowerShell
codmod completion powershell --help

例如，如需在 Linux 上加载 Bash 补全，您可以将以下内容添加到 ~/.bashrc：

source <(codmod completion bash)

请务必重启 shell 或获取配置文件（例如 source ~/.bashrc），使更改生效。

问题排查

  • 权限遭拒：如果您遇到“权限遭拒”错误，请确保您已通过运行 chmod +x codmod 命令向 codmod 二进制文件授予执行权限。
  • CLI 似乎挂起：分析可能需要很长时间，但您通常可以在 CLI 的进度条中看到进度。如果 15 分钟后进度条仍保持在 0%，请验证您是否有足够的配额来使用相关模型。默认情况下，codmod 使用 gemini-3.8-flash 模型。不过，这可能会发生变化，因为不同的模型集会针对不同的目的使用不同的模型。

  • 报告错误：如果发生需要调查的错误，请收集调试信息，以协助我们的开发团队。日志可提供用于问题排查的关键详细信息。运行以下命令以收集日志，然后将生成的归档文件压缩并分享给 codmod-feedback-external@google.com 团队。

    codmod collect-logs -o "codmod_logs.zip"

开源许可

您可以运行以下命令，下载最新版本 codmod 的依赖项的开源声明：

version=$(curl -s https://codmod-release.storage.googleapis.com/latest)
curl -O "https://codmod-release.storage.googleapis.com/${version}/THIRD_PARTY_NOTICES.txt"

获取支持和提供反馈

为了帮助提高此产品的质量，我们会收集经过伪匿名处理的使用情况数据。我们会按照Google Cloud 隐私权声明处理这些数据。 您可以随时运行以下命令来更改偏好设置：

codmod config set disable_usage_reporting true

您可以通过以下方式获取支持和提供反馈：

  • 如需获取 codmod 的支持，请点击生成的 HTML 报告中的支持按钮，或发送电子邮件至 codmod-feedback-external@google.com。
  • 如需分享有关 codmod 的反馈，请点击生成的 HTML 报告中的反馈按钮。