數據 API 產生器的原則
一組原則會控管與重大變更、通知、發行和版本控制相關的數據 API 產生器。
版本設定和版本
數據 API 產生器內容中的 發行 是指依格式識別 Major.Minor.Patch 的每個已發行軟體版本。 這些版本分為三種類別： 穩定、 重大變更和 預覽。
穩定版本
穩定版本的數據 API 產生器回溯相容。 回溯相容表示您撰寫的任何依賴一個數據 API 產生器版本的程式代碼都可以採用較新的穩定版本，而不需要任何程式代碼變更才能維持正確性或現有功能。
重大變更版本
數據 API 產生器 的重大變更版本 與回溯相容。 在現有用戶端程式代碼中採用重大變更版本可能需要變更程式代碼，以確保客戶端的行為與以舊版為目標時的行為完全相同。
重大變更版本會透過重大變更清單文章和 GitHub 版本的變更描述來宣佈。 除非變更修正重大安全性、隱私權或法律問題，否則發行預覽/發行候選版本在重大變更版本之前。 雖然舊版的數據 API 產生器可能仍可在 GitHub 發行頁面上使用，但建議您升級至最新版本，其中可能包含錯誤修正。
預覽版本
數據 API 產生器預覽版本會以 X.Y.Z-rc 版本設定設定來識別。 後 -rc 綴表示組建是「候選版」。預覽版本可用來收集新功能和其他變更的意見反應。
除非我們打算從最後一個穩定版本進行重大變更，否則我們會發佈下一個預覽版本，其中包含最新穩定版本和新預覽功能的所有專案。 下一個數據 API 產生器更新可能會中斷我們在預覽版本之間新增的一些新預覽功能。 這種中斷行為表示您可能需要變更程序代碼，才能讓專案再次運作。
預覽版本不適用於長期或生產環境使用。 當新的穩定版本或預覽版本可供使用時，舊版預覽版本可能無法再存取。 最好只在您主動處理新功能，並準備好在發行后不久切換到非預覽版本時，才使用預覽版本。 如果預覽版的某些功能包含在新的穩定版本中，剩餘的預覽功能會新增至新的預覽版本，供您試用。
版本變更數據表
重要
當變更解決重大產品 Bug、法律、安全性或隱私權考慮時，我們可能會對次要或修補程式版本帶來重大變更。
| 發行類型 | 舊版 | 新版本 | 備註 |
|---|---|---|---|
| 中斷變更 | 1.Y.Z |
2.Y.Z |
新功能和錯誤修正，以及任何重大變更。 |
| 穩定 | 1.1.Z |
1.2.Z |
除非變更可解決重大產品 Bug、法律、安全性或隱私權考慮，否則新功能和 Bug 修正不會有任何重大變更。 |
| 穩定 | 1.1.1 |
1.1.2 |
除非變更解決重大產品錯誤、法律、安全性或隱私權考慮，否則沒有新功能或重大變更的錯誤修正。 |
| 預覽 | X.Y.1-rc |
X.Y.2-rc |
新的預覽功能和 Bug 修正。 如果主要版本已增加，則會包含 (重大變更。) |
重大變更
為了設定安全性、增強功能及維護程式碼品質的優先順序，我們軟體的新版本可能包含重大變更。 雖然我們努力透過仔細的架構選擇將這些變更降到最低，但仍會發生這些變更。 在這種情況下，我們會優先宣告它們，並提供可能的解決方案。
重要
如果變更被視為非中斷，或是要解決重大產品錯誤或法律、安全性或隱私權考慮的重大變更，我們可能會事先通知變更。
什麼是重大變更？
重大變更是一項修改，要求您更新應用程式以避免中斷。 在數據 API 產生器中，重大變更可能包括變更 REST API 合約、GraphQL 架構產生，以及影響相容性和功能的其他元素。
重大變更範例
下列範例是資料 API 產生器的重大變更 非必要 清單：
- REST API 合約修改
- GraphQL 架構產生中的變更
- 影響回溯相容性的變更
- 拿掉或重新命名 API 或參數
- 錯誤碼的變更
- 調整許可權定義功能
- 拿掉允許的參數、要求欄位或回應欄位
- 新增強制參數或要求欄位而不使用預設值
- 修改預定的 API 端點功能
非重大變更的定義
非中斷性變更是指可以整合至應用程式的變更，而不會造成中斷。 非中斷性變更通常會在實作之後進行通訊。 您的應用程式應該設計為處理這些變更，而不需事先通知。
非重大變更範例
下列範例是數據 API 產生器之非重大變更 的非必要 清單：
- 新端點簡介
- 將方法新增至現有的端點
- 回應和要求中的新欄位合併
- 回應內欄位順序的調整
- 選擇性要求標頭簡介
- 數據長度和回應大小的變更
- 錯誤訊息和代碼的變更
- HTTP 回應碼的修正
- 產生的 OpenAPI 檔中的額外元數據
如何溝通重大變更？
我們會優先通知您重大變更。 您可以在 GitHub 上的資料 API 產生器版本版本資訊以及專用 的重大變更清單一文中找到重大變更通知。
目前重大變更清單
本文宣佈重大變更和功能淘汰。
- 目前沒有任何重大變更