创建应用现代化评估

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

关于应用现代化改造评估

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

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

此工具适用于以下角色：

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

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

Google Cloud

准备工作

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

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

价格

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

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

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

  • 缩短查询的费用降低。
  • 隐式缓存的费用降低。
  • 承诺使用折扣 (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.0-flash|2.5-flash|2.5-pro|adaptive]：指定要使用的 Gemini 模型。默认值为 2.5-pro。与 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 OS 上运行的应用搭配使用，评估将围绕转型历程展开，这些历程将基于 .NET 的框架进行现代化改造，以使用最新版本并减少对 Microsoft 许可的依赖。
  • 云到云工作负载转型 (CLOUD_TO_CLOUD)：与在其他超大规模企业基础设施上运行的应用搭配使用。评估将专注于转型应用的建议更改，例如将其他云供应商服务映射到服务。Google Cloud
  • 旧版 Java 转型 (JAVA_LEGACY_TO_MODERN)：与运行 Java 8 或类似版本 的 Java 应用搭配使用，评估将专注于查找升级依赖项以及代码中受更改为 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 或 AWS 的 Graviton 实例等其他 CSP 成功过渡到 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] 建议使用预定义的意图。
  • 上下文感知建议 ：补全功能会根据命令进行调整。 例如：
    • 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 命令（例如 source ~/.bashrc），以使更改生效。

问题排查

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

  • 报告错误 ：如果需要调查错误，请收集调试信息以帮助我们的开发团队。日志提供了用于问题排查的关键详细信息。运行以下 命令收集日志，然后将生成的归档文件压缩并与 团队分享，电子邮件地址为 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 报告中的反馈 按钮。