创建应用现代化评估

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.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 操作系统上运行的应用搭配使用，评估将侧重于转型历程，即基于 .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 加载 completion，请运行相应的命令。相关说明因 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-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 报告中的反馈按钮。