创建应用现代化评估

Google Cloud Modernization Hub 中的应用现代化改造评估 (codmod) 是一款 AI 赋能的工具，可自动执行应用的现代化改造评估流程。本页面概述了在工作站上安装、使用独立 codmod 命令行界面 (CLI) 工具以及排查其问题的步骤。如需直接在 Google Cloud 控制台中运行容器化codmod评估，请参阅评估 .NET 应用和评估 Java 应用。

关于应用现代化改造评估

codmod CLI 是一款便携式工具，它使用 Gemini 分析源代码，并根据 Google Cloud最佳实践提供现代化改造建议。

手动现代化评估可能需要数周时间。codmod 可自动执行此流程，将评估时间缩短至几个小时。该工具会提供有关应用架构、功能以及可能减缓向 Google Cloud迁移的潜在阻碍因素的循证信息。

此工具适用于 IT 架构师、决策者和应用所有者。

准备工作

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

  • Linux 或 Windows（10 或更高版本）工作站。
  • 一个启用了 Agent Platform API 的 Google Cloud 项目。
  • 在工作站上安装 Google Cloud CLI。如需了解详情，请参阅安装 gcloud CLI。

价格

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

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

这些值可能被高估，因为它们没有考虑由于以下原因而可能节省的费用：

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

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

其他信息

该工具使用 Agent Platform API 的高级代码理解和分析功能。如需详细了解可用模型及其功能，请参阅 Agent Platform 文档中的 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. 在 Google Cloud 控制台中或使用 CLI 确保在项目上启用了 Agent Platform API：

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

  2. 确保您在项目中拥有 Agent Platform User (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 [3.8-flash|3.5-flash|2.5-pro|2.5-flash|adaptive]：指定要使用的 Gemini 模型。默认值为 3.8-flash。
  • --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 语法的正则表达式。
  • --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 版本 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] 会建议可用的模型集（例如 3.8-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 报告中的反馈按钮。