本文檔的重點是為下游開發人員提供明確的參考，說明在針對 Hadoop 原始碼建置應用程式時應注意的事項。本文檔主要是 Hadoop 相容性指南 的精華，因此重點在於 Hadoop 各種介面在不同發行版本之間的相容性保證。
本文件之目標受眾為從事建置或依賴 Apache Hadoop 之專案或應用程式的開發人員，無論依賴關係是來自原始程式碼本身、建置產出，或與執行中系統互動。
Hadoop 開發社群定期推出新 Hadoop 版本，以導入新功能並修正現有問題。版本分為三類
在撰寫呼叫方法或使用屬於 Apache Hadoop 的類別的軟體時，開發人員應遵守下列準則。若未遵守準則，可能會導致從一個 Hadoop 版本轉換到另一個 Hadoop 版本時產生問題。
套件、類別和方法可能會加上受眾註解。三個隱私權等級為：公開、受限私人和私人。下游開發人員應僅使用標示為公開的套件、類別、方法和欄位。未標示為公開的套件、類別和方法被視為 Hadoop 內部，且僅供 Hadoop 的其他元件使用。
如果某個元素的註解與其包含元素的註解衝突，那麼最具限制性的註解將優先。例如，如果 Private 方法包含在 Public 類別中，則該方法應視為 Private。如果 Public 方法包含在 Private 類別中，則該方法應視為 Private。
如果方法沒有隱私權註解，則它會繼承其類別的隱私權。如果類別沒有隱私權，則它會繼承其套件的隱私權。如果套件沒有隱私權，則應假設為 Private。
套件、類別和方法可以用穩定性註解進行註解。有三個類別的穩定性：Stable、Evolving 和 Unstable。穩定性註解決定何時允許進行 不兼容變更。Stable 表示在主要版本之間不允許進行任何不兼容變更。Evolving 表示在次要版本之間不允許進行任何不兼容變更。Unstable 表示隨時允許進行不兼容變更。作為下游開發人員，最好避免使用 Unstable API，並盡可能優先選擇 Stable API。
如果方法沒有穩定性註解，則它會繼承其類別的穩定性。如果類別沒有穩定性，則它會繼承其套件的穩定性。如果套件沒有穩定性，則應假設為 Unstable。
根據上述 API 穩定性規則，新版本允許如下變更 API
| 版本類型 | 穩定 API 變更 | 演進式 API 變更 | 不穩定 API 變更 |
|---|---|---|---|
| 主要 | 允許 | 允許 | 允許 |
| 次要 | 不允許 | 允許 | 允許 |
| 維護 | 不允許 | 不允許 | 允許 |
請注意，主要版本允許中斷任何 API 的相容性，儘管 Hadoop 開發人員社群盡可能努力維護相容性，即使在主要版本之間也是如此。另請注意，Unstable API 隨時都可能在沒有通知的情況下變更。
標示為 @Deprecated 的類別或方法不再安全可用。已棄用的元素應繼續運作，但可能會在後續版本中移除，而且很可能會被移除。穩定性註解將決定已棄用元素最早可以在何時移除。穩定元素直到下一個主要版本才能移除。演進中元素直到下一個次要版本才能移除。不穩定元素隨時都可能移除，而且通常在移除前不會標示為已棄用。穩定和演進中元素在移除前必須分別標示為已棄用一個完整的主要或次要版本（依序）。例如，如果穩定在 Hadoop 3.1 中標示為已棄用，則直到 Hadoop 5.0 才能移除。
Apache Hadoop 開發人員社群致力於確保 API 行為在不同版本間保持一致，儘管為了正確性而做的變更可能會導致行為變更。API Java 文件被視為預期 API 行為的主要依據。在 Java 文件不足或遺失的情況下，單元測試被視為預期行為的備用依據。在沒有單元測試的情況下，預期行為應從命名中推論。下游開發人員應盡可能避免查看 API 本身的原始程式碼來確定預期行為，因為這種方法可能會建立對實作細節的依賴性，而 Hadoop 開發人員社群並未明確將這些細節視為預期行為。
在 Java 文件不足以推論預期行為的情況下，強烈建議下游開發人員提交 Hadoop JIRA，以要求新增或改善 Java 文件。
請注意，為了正確性而執行的修正可能會導致 API 預期行為變更，儘管預期這些變更會附帶釐清新行為的說明文件。
Apache Hadoop 開發人員社群嘗試在不同版本間維護最終使用者應用程式的二進位相容性。理想情況下，在升級到新的 Hadoop 版本時，不需對應用程式進行任何更新，假設應用程式不使用私人、有限私人或不穩定API。特別是，MapReduce 應用程式保證在不同版本間具有二進位相容性。
Hadoop 相容性規範 說明 Hadoop 開發社群預期要遵守的標準，但由於各種原因，原始碼可能無法符合 相容性規範 的理想。
下游開發人員會遇到的兩個常見問題是
在這些情況下，強烈建議下游開發人員透過寄送電子郵件到適當的 開發人員郵件清單 或 提交 JIRA，或同時執行這兩個動作，向 Hadoop 開發人員社群提出問題。開發人員社群會感謝您的回饋。
在針對 Hadoop 開發應用程式時遇到問題時，建議下游開發人員主動與 Hadoop 開發人員社群聯繫。如果一個開發人員遇到問題，很有可能其他開發人員也遇到或將會遇到相同的問題。
在 Hadoop 中處理串流的特定情況下，例如 FSDataOutputStream，應用程式可以使用 StreamCapabilities 類別的方法，以透過程式查詢串流的功能。動態調整串流功能可以讓應用程式在面對變更的實作和環境時更為強健。
Hadoop REST API 是各種下游和內部應用程式及服務的主要介面。為了支援 REST 應用程式，Hadoop REST API 會進行版本控管，且在版本內不會不相容地變更。端點本身以及支援的參數清單和端點產出都禁止在 REST 端點版本內不相容地變更。不過，請注意，新增欄位和其他附加變更被視為相容變更，因此 REST API 的任何使用者都應該有足夠的彈性來忽略未知欄位。
REST API 版本是一個單一數字，與 Hadoop 版本號碼無關。版本號碼編碼在端點 URL 中，並加上前置的「v」，例如「v1」。新的 REST 端點版本只能在次要或主要版本中新增。REST 端點版本只能在標示為已棄用且經過一個完整的次要版本後才能移除。
Hadoop 會產生各種輸出，應用程式用戶端或下游程式庫可能會使用這些輸出。使用 Hadoop 輸出時，請考慮下列事項
Hadoop 用於儲存資料的二進位檔案格式，例如順序檔案、HAR 檔案等，保證在次要版本之間保持相容性。此外，在主要版本之間進行變更時，必須維持向後和向前相容性。請注意，只有順序檔案格式保證不會不相容地變更，而不是其中包含的序列化類別。
除了作業產生的資料外，Hadoop 會以各種格式將其狀態資訊保存在各種資料儲存中，例如 HDFS 元資料儲存、YARN 資源管理員狀態儲存和 YARN 聯盟狀態儲存。所有 Hadoop 內部資料儲存都被視為內部和私人的 Hadoop。下游開發人員不應嘗試使用 Hadoop 狀態儲存的資料，因為資料和/或資料格式可能會意外變更。
構成 Hadoop 指令列介面的工具組，同時供最終使用者使用，也供下游開發人員使用，後者會建立執行 CLI 工具並剖析輸出的工具。因此，Hadoop CLI 工具會被視為介面，並在主要版本之間保持穩定。在主要版本之間，不會移除任何 CLI 工具選項，也不會變更其語意。CLI 工具的輸出也會在主要版本號碼中保持相同。請注意，對 CLI 工具輸出的任何變更都視為不相容的變更，因此在主要版本之間，CLI 輸出不會變更。請注意，CLI 工具輸出不同於 CLI 工具產生的記錄檔輸出。記錄檔輸出不適用於自動化使用，且隨時可能變更。
Hadoop 顯示的網頁 UI 僅供人工使用。不支援從 UI 擷取資料。不會針對各個版本中任何網頁 UI 所顯示的資料，進行任何確保相容性的工作。
Hadoop 使用兩種主要形式的設定檔：XML 設定檔和記錄檔設定檔。
XML 設定檔包含一組屬性，以名稱值對的形式呈現。屬性的名稱和意義由 Hadoop 定義，且保證在次要版本之間保持穩定。屬性只能在主要版本中移除，而且僅限於已標記為已棄用至少一個完整主要版本的屬性。大多數屬性都有預設值，如果屬性未在 XML 設定檔中明確設定，就會使用預設值。預設屬性值不會在維護版本中變更。有關 Hadoop 各個元件支援的屬性詳細資訊，請參閱元件文件。
下游開發人員和使用者可以將自己的屬性新增到 XML 設定檔中，供其工具和應用程式使用。雖然 Hadoop 沒有對定義新屬性做出正式限制，但與 Hadoop 定義的屬性衝突的新屬性，可能會導致意外和不理想的結果。建議使用者避免使用與 Hadoop 定義的屬性名稱空間衝突的自訂設定檔屬性名稱，因此應避免使用 Hadoop 使用的任何前綴，例如 hadoop、io、ipc、fs、net、ftp、ha、file、dfs、mapred、mapreduce 和 yarn。
Hadoop 程式和 CLI 產生的記錄檔輸出，由一組設定檔管理。這些檔案控制 Hadoop 各個元件輸出的最低記錄檔訊息層級，以及這些訊息的儲存位置和方式。在次要版本之間，不會對記錄檔設定檔進行任何變更，以減少、消除或重新導向記錄檔訊息。
Hadoop 使用多種格式的許多其他類型組態檔案，例如 JSON 資源設定檔組態或 XML 公平排程器組態。在次要版本中，不會對組態檔案格式引入不相容的變更。即使在次要版本之間，也將盡可能避免不相容的組態檔案格式變更。
作為 Hadoop 的下游開發人員或使用者，可以存取 Hadoop 平台的所有元素，包括原始碼、組態檔案、建置人工製品等。雖然平台的開放性質允許這樣做，但開發人員不應建立對 Hadoop 這些內部詳細資料的依賴性，因為它們可能會隨時變更。不過，Hadoop 開發社群將嘗試在主要版本中保持現有結構的穩定性。
Hadoop 組態檔案、作業歷程資訊（由作業歷程伺服器使用）和 Hadoop 產生的記錄檔的位置和一般結構將在維護版本中維持。
Hadoop 建置程序產生的建置人工製品（例如 JAR 檔案）可能會隨時變更，不應視為可靠，但用戶端人工製品除外。用戶端人工製品及其內容將在主要版本中保持相容性。Hadoop 開發社群的目標是讓應用程式碼能夠在次要版本中持續運作不變，並在可能的情況下，在主要版本中持續運作不變。目前的用戶端人工製品清單如下
某些 Hadoop 元件會透過環境變數接收資訊。例如，HADOOP_OPTS 環境變數會由大部分 Hadoop 程序解讀為啟動新 JVM 時要使用的其他 JVM 引數字串。在次要版本之間，Hadoop 解讀環境變數的方式不會以不相容的方式變更。換句話說，放入相同變數的相同值應該會在同一個主要版本中的所有 Hadoop 版本產生相同的結果。
Hadoop 仰賴大量的第三方函式庫才能運作。Hadoop 開發人員社群盡可能隱藏這些相依性，避免下游開發人員接觸到。某些常見函式庫（例如 Guava）可能會在 Hadoop 與下游應用程式之間造成重大的相容性問題，如果這些相依性暴露在下游。不過，Hadoop 確實會公開部分相依性，特別是在 Hadoop 3 之前。Hadoop 透過主要版本之間的用戶端人工製品公開的新相依性不會再增加。
常見的下游反模式是使用 hadoop classpath 的輸出設定下游應用程式的類別路徑，或將所有 Hadoop 附帶的第三方 JAR 檔案新增到下游應用程式的類別路徑。這種做法會在下游應用程式與 Hadoop 的第三方相依性之間建立緊密的關聯，導致脆弱的應用程式難以在 Hadoop 的相依性變更時維護。強烈建議不要採用這種做法。
Hadoop 仰賴 Java 虛擬機器才能運作，這可能會影響下游應用程式。為了將中斷降到最低，Hadoop 主要版本之間不會變更支援的 JVM 最低版本。如果在主要版本之間，目前支援的 JVM 最低版本不再受支援，支援的 JVM 最低版本可能會在次要版本中變更。
Hadoop 也包含多個原生元件，包括壓縮、容器執行器二進位檔和各種原生整合。這些原生元件為 Hadoop 引入一組原生相依性。原生相依性組可以在次要版本中變更，但 Hadoop 開發人員社群會盡可能將任何相依性版本變更限制為次要版本變更。
Hadoop 目前由 Hadoop 開發人員社群在執行於 x86 和 AMD 處理器的 Linux 和 Windows 上提供支援。這些作業系統和處理器在可預見的未來可能會持續獲得支援。如果支援計畫變更，將會在實際移除之前，將要移除的作業系統或處理器標記為已棄用，至少一個完整的次要版本，理想情況是一個完整的次要版本。Hadoop 可能可以在其他作業系統和處理器架構上運作，但社群可能無法在發生問題時提供協助。
Hadoop 程序所需的最少資源在版本之間（甚至維護版本）之間的變更方式沒有保證。不過，Hadoop 開發人員社群會盡量避免在次要版本中增加需求。
任何檔案系統支援 Hadoop，例如透過 FileSystem API，在大部分情況下，將會在主要版本中持續支援。唯一會在主要版本中停止支援檔案系統的情況，是如果提供了乾淨的遷移路徑至替代的用戶端實作。
對於開發應用程式和專案的問題，請聯絡相關元件的開發人員郵件清單