Java Proto 名稱

由 Java protoc 外掛生成的名稱。

本文件包含有關基於不同 proto 選項的 proto 的完全限定 Java 名稱的資訊。此名稱對應於您需要匯入以使用該訊息的包。

建議

從 2024 版開始，最佳實踐是

  • 設定 option java_package = "com.example.package"
  • 不要設定 java_outer_classname 或 features.(pb.java).nest_in_file_class = YES。

從 2024 版開始，預設行為已得到改進，因此預設行為被認為是當前最佳實踐。

使用 Proto2、Proto3 或 2023 版時，最佳實踐是

  • 設定 option java_multiple_files = true;
  • 設定 option java_outer_classname = "FileNameProto";
  • 設定 option java_package = "com.google.package";

說明

多個檔案

使用 java_multiple_files = true 後，每條訊息生成的 Java 類都將放在單獨的 .java 檔案中。這使得將訊息從一個 .proto 檔案移動到另一個檔案變得更加容易。

從 2024 版開始，此功能已被 features.(pb.java).nest_in_file_class 功能取代，該功能具有預設值 NO，與舊版語法的 java_multiple_files = true 行為相匹配。

外部類名

為 .proto 檔案本身會生成一個 Java 類。如果未指定，該檔案的類名將自動生成。但是，如何生成該名稱的規則過於複雜且不直觀。最佳策略是顯式設定 java_outer_classname 選項，將 .proto 檔名轉換為 PascalCase 並移除 '.'。例如

  • 檔案 student_record_request.proto 應設定為

    option java_outer_classname = "StudentRecordRequestProto";

從 2024 版開始，java_outer_classname 仍然可用，但預設行為已更改為匹配此建議，因此無需設定。

Java 包

生成繫結檔案的 Java 包將自動設定為 proto 包。但通常這不符合 Java 約定。為確保 Java 包名稱符合約定，我們建議顯式設定 java_package 選項。例如，在 Google 內部，約定是在 proto 包前加上 com.google.。

不可變 API 訊息名稱

protoc 的 Java 外掛將根據此表生成名稱。

java_multiple_filesjava_packagejava_outer_classname生成的完整訊息名稱
true未定義忽略com.google.protos.$package.$message
true已定義忽略$java_package.$message
false未定義未定義com.google.protos.$package.$derived_outer_class.$message
false未定義已定義com.google.protos.$package.$java_outer_classname.$message
false已定義未定義$java_package.$derived_outer_class.$message
false已定義已定義$java_package.$java_outer_classname.$message

圖例

  • $message 是 proto 訊息的實際名稱。

  • $package 是 proto 包的名稱。這是 proto 檔案中 package 指令指定的名稱，通常位於檔案頂部。

  • $derived_outer_class 是從 proto 檔名派生的名稱。通常透過移除檔名中的標點符號並將其轉換為 PascalCase 來計算。例如，如果 proto 檔案是 foo_bar.proto，則 $derived_outer_class 的值為 FooBar。

    如果生成的類名與 proto 檔案中定義的某個訊息相同，則 derived_outer_class 會附加 OuterClass。例如，如果 proto 檔案是 foo_bar.proto 且包含 FooBar 訊息，則 $derived_outer_class 的值為 FooBarOuterClass。使用 v1 API 時情況相同，無論類名是否與定義的訊息之一相同。

  • 所有其他 $names 都是 .proto 檔案中定義的相應檔案選項的值。