建立應用程式現代化評估

Migration Center 應用程式現代化評估 (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 評估程式碼的費用主要取決於程式碼集的大小，並以權杖計算。下表列出根據程式碼行數和所選模型，您預期會看到的費用估算值：

程式碼集 程式碼行數 (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 $3000 $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. 確認專案已在控制台啟用 Vertex AI API，或使用 CLI 啟用：

    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 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 VM) 所需的工作量。評估重點在於找出潛在的程式碼可攜性問題、架構專屬依附元件、建構系統修改項目，以及成功從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 報表格式。
  • 、revise section、list-sections 預期 --from-report 標記會指向 HTML 格式的報表。create section

預估評估費用

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 bucket，查看是否發布了新版 codmod。如果找到新版本，終端機上會顯示通知訊息。訊息中會顯示新版本號碼，以及更新下載連結。 確保您能使用最新功能、改善項目和錯誤修正。

停用版本檢查

如要停用自動版本檢查，可以使用 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 的殼層指令列完成功能。這項功能可讓您按下 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 的自動完成功能，請執行適當的指令。操作說明會因使用的殼層而異。使用 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)

請務必重新啟動殼層或提供設定檔來源 (例如 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 報表中的「意見回饋」按鈕。