老舊的API，你應該如何處理？

時間 2021-08-14

標籤 javascript php css html java git github web 面試編程欄目 JavaScript 简体版

原文原文鏈接

點擊上方 "編程技術圈"關注, 星標或置頂一塊兒成長javascript

後臺回覆「大禮包」有驚喜禮包！
php

每日英文css

There is a time in life that is full of uneasiness.We have no other choice but to face it.html

生命中總有那麼一段時光，充滿不安，但是除了勇敢面對，咱們別無選擇。java

每日掏心話git

你過得快不快樂，只有你本身知道。若是用樂觀曠達，積極向上的心態去看待，那麼，壞機會也會成爲好機會。github

責編：樂樂 | 來自：架構頭條web

編程技術圈(ID:study_tech)第 1168 次推文面試

往日回顧：記住看小電影前必定要檢查網址是否是 HTTPS 的，否則…編程

正文

做者 | Tim Perry

譯者 | 張衛濱

策劃 | 萬佳

廢棄 API 端點是一項很是具備挑戰性的工做，咱們須要考慮全部依賴該 API 的客戶端，避免出現級聯的故障。針對該問題，有兩個新的 HTTP 頭信息草案，本文詳細闡述了該如何使用這兩個新的頭信息安全地關閉 API。

萬物都會有終結，HTTP API 也不例外。不論你的 API 今天看上去多麼偉大，早晚有一天你會想發佈一個全新的版本，新版本能更好地解決相同問題，在各方面可能都會有所改善，可是它由於有了新參數，與舊版本也沒法兼容，或者你只是想完全關閉舊的 API。總而言之，你如今的 API 不會永遠存在。

可是，這並不是垂手可得就能完成的，由於你的 API 有客戶端。若是你關閉端點、參數或整個 API 而沒有作出恰當的警告的話，那他們確定會很是不爽。

那麼，該怎樣安全地關閉 API，讓你的用戶儘量地感到輕鬆愉快呢？

在這方面，咱們有正確的作事方式，包括兩個新的頭信息草案，它們正在被新的 IETF 「Building Blocks for HTTP APIs」工做組進行標準化，旨在造成一個精確的過程。咱們瞭解一下。

1制定計劃

初始第一步：檢查相關的 API 是否真的有客戶端。

但願你能有某些 API 的度量指標，至少在某些地方存有日誌。若是沒有的話，那把它們添加上，若是你有這些東西的話，而且你能肯定沒有人再使用這個 API 了，那麼恭喜你，你贏了。如今，你就能夠把它關掉，刪掉代碼，不要再管這篇文章了，好好睡一覺。

下一個問題，若是比較遺憾，你沒法去睡覺的話，那就要問問本身，除了關閉這個 API，還有沒有其餘方案。你關閉的全部東西都有可能破壞別人的代碼，而且會消耗他們的時間來修復這些問題。若是 API 能繼續運行的話，對客戶端的生態系統和整個 web 的健康都是有好處的。

在不少場景下，舊的 API 能夠在內部進行轉換，透明地轉化成對新 API 的調用，這樣能夠避免維護兩個徹底獨立的版本。這是 Stripe 的 API 版本管理方式的一個基本組成部分，他們在全部發生變化的 API 中都包含了轉換，以確保對不兼容的舊版本 API 的請求能繼續像之前那樣運行，根據須要自動轉換請求和響應從而可使用較新的代碼。

https://stripe.com/blog/api-versioning#versioning-under-the-hood

這樣的轉換並不老是可行的，並且若是永遠這樣作的話會帶來明顯的額外複雜性，可是若是你能夠作到這一點的話，就能爲用戶提供很是有價值的穩定性，而且能夠節省大量廢棄舊版本或維護舊版本相關的工做。

可是，若是這個服務 / 端點 / 參數已經用到了生產環境，並且繼續支持它是不現實的作法，那麼它必需要被淘汰。

要實現這一點，咱們就要有一個計劃。咱們首先要問本身三個關鍵的問題：

你但願用戶該怎麼作？常見的答案包括：升級到相關功能的一個更新的、依然能獲得支持的版本；使用一些可替代的端點 / 參數 / 服務；使用不一樣的服務，它們與你無關，不須要你關心。

用戶應該什麼時候遷離這個 API？你所提出的替代方案如今就能夠用了嗎？

截止時間是何時？也就是，這個 API 什麼時候會徹底中止使用？（若是不能徹底肯定的話，你能夠稍微延遲迴答這個問題）。

計劃準備就緒以後，咱們就該把它告訴人們了。

2溝通

首先，要把這一決定告訴人們。

發郵件到郵件列表，在 Twitter 或微博上發帖，若是有 API 規範的話，對其進行更新（好比，OpenAPI 在 operations 和 parameters 上有一個deprecated字段），並在相關的在線文檔上大聲強調這一點。

你應該包含上文提到的全部信息：他們應該作些什麼做爲替代方案，你建議他們何時開始遷移以及他們必需要進行遷移的最後期限（若是已經肯定期限的話）。

在將這些信息告訴給人們後，接下來就該告訴計算機，而這就是新的 IETF 頭信息能夠發揮做用的地方。

Deprecation 頭信息

Deprecation 頭信息能告訴客戶端請求的資源如今依然像之前那樣運行，可是這種方式已經再也不推薦使用了。

https://datatracker.ietf.org/doc/draft-ietf-httpapi-deprecation-header/?include_text=1

經過一個簡單的 HTTP 頭信息，咱們就能夠聲明這一點：

Deprecation: true

另外，咱們還能提供一個日期。這個日期告訴用戶他們什麼時候該開始進行遷移。這個日期能夠是一個過去時間（這表明他們應該當即開始遷移），也能是未來時間（一般這意味着他們要遷移到的新環境尚未準備就緒）。以下所示：

Deprecation: Thu, 21 Jan 2021 23:59:59 GMT

若是你要廢棄整個端點或服務，那麼你能夠在每一個響應中都帶上這樣的頭信息。若是你想要廢棄的是一個具體的特性，多是一個參數、請求方法或者請求體中的某個特定字段的話，那麼你應該在該特性被使用的時候纔在響應中包含這個頭信息。

爲了給客戶端更多的信息，咱們還可使用Link HTTP 響應頭信息連接至端點或人類易讀的文檔。在同一個Link頭信息中，咱們能夠包含多個這樣的連接，只須要使用逗號進行分割便可（後面咱們會看到一個完整的例子）。該規範定義了四個與 API 廢棄相關的連接：

Deprecation 連接

咱們能夠爲 deprecation 連接指向一我的類易於閱讀的描述：

Link: <https://developer.example.com/deprecation>; rel="deprecation"; type="text/html"

這是告訴用戶發生了什麼以及他們該怎麼辦的主要方式。你應該始終使用它。若是尚未完整的詳情和最終的關閉日期，那麼即便只是一個佔位符，這也是頗有幫助的。在這種狀況下，不要忘記讓用戶訂閱更新，這能夠採用郵件列表、RSS 或其餘相似的方式來實現。

在公衆號後端架構師後臺回覆「架構整潔」，獲取一份驚喜禮包。

Latest-Version 連接

若是你但願客戶端轉移至 API 相同端點的最新版本，那麼可使用該連接指向它，以下所示：

Link: <https://api.example.com/v10/customers>; rel="latest-version"

Successor-Version 連接

若是你的 API 有多個可用的版本，一般最好每次向前遷移一個版本，而不是直接從最老的、現已廢棄的版本跳到最新的版本。爲了幫助解決這個問題，咱們連接至已廢棄版本的下一個版本，而不是最新版本，以下所示：

Link: <https://api.example.com/v2/customers>; rel="successor-version"

Alternate 連接

若是該 API 沒有新的等價版本，用戶最好遷移到一個徹底不一樣的資源，它多是一個很好的替代方案，那麼咱們使用 alternate 連接來指明這一點，以下所示：

Link: <https://api.example.com/v2/users/123/clients>; rel="alternate"

Sunset 頭信息

若是你知道了 API 什麼時候徹底關閉的話，那麼就應該添加一個 Sunset 頭信息。

https://datatracker.ietf.org/doc/rfc8594/?include_text=1

Sunset 頭信息告訴客戶端 API 什麼時候會中止運行。這是一個強制的截止時間：API 客戶端必需要在這個日期前進行遷移，咱們承諾在這個時間前不會破壞任何事情。

在這裏，咱們必需要提供一個時間，它應該是一個將來的時間。不過，若是它是一個過去的時間，這也是能夠的：此時就至關於說「這個 API 會在任意時刻關閉，你須要當即中止使用它」。它以下所示：

Sunset: Tue, 20 Jul 2021 23:59:59 GMT

這很是簡單，它不只能夠用到 API 關閉的場景中：咱們能用它來標記未來 URL 遷移的 HTTP 重定向，或者代表特定 URL 有限的生命週期（適用於臨時性的內容，或者適用於具備監管要求的特定資源，好比數據保留策略）。它所說明的就是「這個端點可能在該日期後不會再按照你的預期運行，請作好準備」。

Sunset 連接

該規範也提供了一個 Sunset 連接的關係。按照設計，它會連接相當於關閉特定端點更加詳細的信息（若是你有 deprecation 連接的話，它們可能會是同一個）或者關於服務的通用 Sunset 策略。以下所示：

Link: <http://developer.example.com/our-sunset-policy>;rel="sunset";type="text/html"

在這裏咱們也要指出，通用的 Sunset 策略是很是有用的！Sunset 策略會告訴客戶端，當咱們關閉端點的時候（好比，一年後替代方案上線），用戶該如何確保他們能得知這一狀況（郵件列表、狀態頁面、HTTP 頭信息等）以及他們一般應該作些什麼（更新、檢查文檔、聽從Link頭信息）。

若是立刻就要廢棄某個 API 的話，添加這樣的連接做用其實不大，可是若是你能在一年前就將其發佈出去的話，你的客戶端可能已經爲此作好了準備。

除此以外，發佈 Sunset/Deprecation 策略的最好時間就是如今。若是你剛好正以某種方式編寫 Deprecation 文檔的話，這麼作是值得考慮的。

組合到一塊兒

按照設計，這些組成部分能很好地協做。例如，爲了代表某個最近廢棄的 API，該 API 會在 6 個月內完全關閉，咱們要連接至文檔並提供下一個版本的直接連接，那麼咱們應該在響應中包含以下的頭信息連接：

Deprecation: Thu, 21 Jan 2021 23:59:59 GMT
Sunset: Tue, 20 Jul 2021 23:59:59 GMT
Link: <https://api.example.com/v2/customers>; rel="successor-version",
    <https://developer.example.com/shutting-down-customers-v1>; rel="deprecation"

3漸進式關閉

若是全部這些都已經準備到位，而且 sunset 截止時間已過，那麼咱們就能夠將 API 關閉了。

可是，這並不意味着你須要當即且完全消滅該 API。漸進式關閉能有助於確保任何使用該 API 的全部客戶端都有最後的機會在它完全消失前獲得最後一次警告。GitHub 在 2018 年移除一些加密支持的時候曾經這樣作：首先禁用一個小時，而後啓用它，最後在兩週後完全禁用了它。

https://github.blog/2018-02-01-crypto-removal-notice/

這裏還有另一個技巧：安卓在 2015 年爲已廢棄的原生 API 增長了愈來愈多的延遲，在完全關閉 API 前，最終達到了 16 秒的等待。

https://twitter.com/jbaruch/status/930476565065953280

這些漸進式的關閉爲那些錯過截止日期的客戶端提供了一些靈活性，而且能幫助那些沒有注意到廢棄時間點的客戶端，從而能在 API 完全關閉以前處理一些問題。

4謹慎行事

無論採用哪一種方式，只要你盡了最大的努力去溝通關於 API 關閉的事情，那麼如今就能夠關閉端點 / 特性 / 整個服務，刪除代碼，而後睡個好覺。

像這樣當心謹慎地進行廢棄和關閉，可讓你的客戶端儘量清楚地知道他們該如何依賴你的 API，什麼時候須要採起行動，以及他們須要作什麼。這種變動多是一件大事兒，這些信息是很重要的。

這些新的草案頭信息讓咱們不只能夠與人類溝通，還能將這些信息暴露給自動化系統。隨着這些頭信息的普及，我很高興地開始看到有更多的工具創建在它們之上。通用的 HTTP 客戶端能夠根據這些數據自動記錄有用的警告日誌，API 生成器自己也能根據 API 規範處理愈來愈多的問題，而 HTTP 調試器（如 HTTP Toolkit）能夠在截獲的實時流量中爲你突出顯示廢棄端點的使用。這是一個使人激動的時刻，咱們能夠開始安全地關閉 API 了！

https://httptoolkit.tech/

須要注意的是，這些頭信息是 HTTP 規範的草案。在最終肯定前，它們有可能會發生變化。也就是說，它們經歷了幾輪修改，從如今開始，它們不太可能發生巨大的變化，如今能普遍測試它們了。

不過這也意味着還有時間進行反饋! 若是你對它們的工做方式和如何更好地運行有想法的話，請與「Building Blocks for HTTP APIs」工做組聯繫。你能夠給郵件列表發郵件：httpapi@ietf.org。

原文連接：

https://httptoolkit.tech/blog/how-to-turn-off-your-old-apis/

PS：歡迎在留言區留下你的觀點，一塊兒討論提升。若是今天的文章讓你有新的啓發，歡迎轉發分享給更多人。