www.夜夜骑.com,手机免费毛片,特级西西西西4444级酉西88wwww特,国产精品一色哟哟哟,性欧美孕妇孕交,亚洲激情动漫,日韩免费观看一区二区,夜夜爱夜夜爽

微信搜索逆鋒起筆關(guān)注后回復(fù)編程pdf
領(lǐng)取編程大佬們所推薦的 23 種編程資料！

作者 | Tim Perry

譯者 | 張衛(wèi)濱

策劃 | 萬佳

廢棄 API 端點是一項非常具有挑戰(zhàn)性的工作，我們需要考慮所有依賴該 API 的客戶端，避免出現(xiàn)級聯(lián)的故障。針對該問題，有兩個新的 HTTP 頭信息草案，本文詳細(xì)闡述了該如何使用這兩個新的頭信息安全地關(guān)閉 API。

萬物都會有終結(jié)，HTTP API 也不例外。不論你的 API 今天看上去多么偉大，遲早有一天你會想發(fā)布一個全新的版本，新版本能更好地解決相同問題，在各方面可能都會有所改善，但是它因為有了新參數(shù)，與舊版本也無法兼容，或者你只是想徹底關(guān)閉舊的 API?？偠灾?，你現(xiàn)在的 API 不會永遠(yuǎn)存在。

但是，這并非輕而易舉就能完成的，因為你的 API 有客戶端。如果你關(guān)閉端點、參數(shù)或整個 API 而沒有做出恰當(dāng)?shù)木娴脑?，那他們肯定會非常不爽?/section>

那么，該怎樣安全地關(guān)閉 API，讓你的用戶盡可能地感到輕松愉快呢？

在這方面，我們有正確的做事方式，包括兩個新的頭信息草案，它們正在被新的 IETF “Building Blocks for HTTP APIs”工作組進(jìn)行標(biāo)準(zhǔn)化，旨在形成一個精確的過程。我們了解一下。

1. 制定計劃

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

希望你能有某些 API 的度量指標(biāo)，至少在某些地方存有日志。如果沒有的話，那把它們添加上，如果你有這些東西的話，并且你能確定沒有人再使用這個 API 了，那么恭喜你，你贏了?，F(xiàn)在，你就可以把它關(guān)掉，刪掉代碼，不要再管這篇文章了，好好睡一覺。

下一個問題，如果比較遺憾，你無法去睡覺的話，那就要問問自己，除了關(guān)閉這個 API，還有沒有其他方案。你關(guān)閉的所有東西都有可能破壞別人的代碼，并且會消耗他們的時間來修復(fù)這些問題。如果 API 能繼續(xù)運(yùn)行的話，對客戶端的生態(tài)系統(tǒng)和整個 web 的健康都是有好處的。

在很多場景下，舊的 API 可以在內(nèi)部進(jìn)行轉(zhuǎn)換，透明地轉(zhuǎn)化成對新 API 的調(diào)用，這樣可以避免維護(hù)兩個完全獨立的版本。這是 Stripe 的 API 版本管理方式的一個基本組成部分，他們在所有發(fā)生變化的 API 中都包含了轉(zhuǎn)換，以確保對不兼容的舊版本 API 的請求能繼續(xù)像以前那樣運(yùn)行，根據(jù)需要自動轉(zhuǎn)換請求和響應(yīng)從而可以使用較新的代碼。

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

這樣的轉(zhuǎn)換并不總是可行的，而且如果永遠(yuǎn)這樣做的話會帶來明顯的額外復(fù)雜性，但是如果你可以做到這一點的話，就能為用戶提供非常有價值的穩(wěn)定性，并且可以節(jié)省大量廢棄舊版本或維護(hù)舊版本相關(guān)的工作。

但是，如果這個服務(wù) / 端點 / 參數(shù)已經(jīng)用到了生產(chǎn)環(huán)境，而且繼續(xù)支持它是不現(xiàn)實的做法，那么它必須要被淘汰。

要實現(xiàn)這一點，我們就要有一個計劃。我們首先要問自己三個關(guān)鍵的問題：

你希望用戶該怎么做？常見的答案包括：升級到相關(guān)功能的一個更新的、依然能得到支持的版本；使用一些可替代的端點 / 參數(shù) / 服務(wù)；使用不同的服務(wù)，它們與你無關(guān)，不需要你關(guān)心。

用戶應(yīng)該何時遷離這個 API？你所提出的替代方案現(xiàn)在就可以用了嗎？

截止時間是什么時候？也就是，這個 API 何時會完全停止使用？（如果不能完全確定的話，你可以稍微延遲回答這個問題）。

計劃準(zhǔn)備就緒之后，我們就該把它告訴人們了。

2. 溝通

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

發(fā)郵件到郵件列表，在 Twitter 或微博上發(fā)帖，如果有 API 規(guī)范的話，對其進(jìn)行更新（比如，OpenAPI 在 operations 和 parameters 上有一個deprecated字段），并在相關(guān)的在線文檔上大聲強(qiáng)調(diào)這一點。

你應(yīng)該包含上文提到的所有信息：他們應(yīng)該做些什么作為替代方案，你建議他們什么時候開始遷移以及他們必須要進(jìn)行遷移的最后期限（如果已經(jīng)確定期限的話）。

在將這些信息告訴給人們后，接下來就該告訴計算機(jī)，而這就是新的 IETF 頭信息可以發(fā)揮作用的地方。

Deprecation 頭信息

Deprecation 頭信息能告訴客戶端請求的資源現(xiàn)在依然像以前那樣運(yùn)行，但是這種方式已經(jīng)不再推薦使用了。

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

通過一個簡單的 HTTP 頭信息，我們就可以聲明這一點：

Deprecation: true

另外，我們還能提供一個日期。這個日期告訴用戶他們何時該開始進(jìn)行遷移。這個日期可以是一個過去時間（這代表他們應(yīng)該立即開始遷移），也能是將來時間（通常這意味著他們要遷移到的新環(huán)境還沒有準(zhǔn)備就緒）。如下所示：

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

如果你要廢棄整個端點或服務(wù)，那么你可以在每個響應(yīng)中都帶上這樣的頭信息。如果你想要廢棄的是一個具體的特性，可能是一個參數(shù)、請求方法或者請求體中的某個特定字段的話，那么你應(yīng)該在該特性被使用的時候才在響應(yīng)中包含這個頭信息。

為了給客戶端更多的信息，我們還可以使用Link HTTP 響應(yīng)頭信息鏈接至端點或人類易讀的文檔。在同一個Link頭信息中，我們可以包含多個這樣的鏈接，只需要使用逗號進(jìn)行分割即可（后面我們會看到一個完整的例子）。該規(guī)范定義了四個與 API 廢棄相關(guān)的鏈接：

Deprecation 鏈接

我們可以為 deprecation 鏈接指向一個人類易于閱讀的描述：

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

這是告訴用戶發(fā)生了什么以及他們該怎么辦的主要方式。你應(yīng)該始終使用它。如果還沒有完整的詳情和最終的關(guān)閉日期，那么即使只是一個占位符，這也是很有幫助的。在這種情況下，不要忘記讓用戶訂閱更新，這可以采用郵件列表、RSS 或其他類似的方式來實現(xiàn)。

Latest-Version 鏈接

如果你希望客戶端轉(zhuǎn)移至 API 相同端點的最新版本，那么可以使用該鏈接指向它，如下所示：

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

Latest-Version 鏈接

如果你的 API 有多個可用的版本，通常最好每次向前遷移一個版本，而不是直接從最老的、現(xiàn)已廢棄的版本跳到最新的版本。為了幫助解決這個問題，我們鏈接至已廢棄版本的下一個版本，而不是最新版本，如下所示：

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

Successor-Version 鏈接

如果該 API 沒有新的等價版本，用戶最好遷移到一個完全不同的資源，它可能是一個很好的替代方案，那么我們使用 alternate 鏈接來指明這一點，如下所示：

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

Sunset 頭信息

如果你知道了 API 何時完全關(guān)閉的話，那么就應(yīng)該添加一個 Sunset 頭信息。

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

Sunset 頭信息告訴客戶端 API 何時會停止運(yùn)行。這是一個強(qiáng)制的截止時間：API 客戶端必須要在這個日期前進(jìn)行遷移，我們承諾在這個時間前不會破壞任何事情。

在這里，我們必須要提供一個時間，它應(yīng)該是一個未來的時間。不過，如果它是一個過去的時間，這也是可以的：此時就相當(dāng)于說“這個 API 會在任意時刻關(guān)閉，你需要立即停止使用它”。它如下所示：

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

這非常簡單，它不僅可以用到 API 關(guān)閉的場景中：我們能用它來標(biāo)記將來 URL 遷移的 HTTP 重定向，或者表明特定 URL 有限的生命周期（適用于臨時性的內(nèi)容，或者適用于具有監(jiān)管要求的特定資源，比如數(shù)據(jù)保留策略）。它所說明的就是“這個端點可能在該日期后不會再按照你的預(yù)期運(yùn)行，請做好準(zhǔn)備”。

Sunset 鏈接

該規(guī)范也提供了一個 Sunset 鏈接的關(guān)系。按照設(shè)計，它會鏈接至關(guān)于關(guān)閉特定端點更加詳細(xì)的信息（如果你有 deprecation 鏈接的話，它們可能會是同一個）或者關(guān)于服務(wù)的通用 Sunset 策略。如下所示：

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

在這里我們也要指出，通用的 Sunset 策略是非常有用的！Sunset 策略會告訴客戶端，當(dāng)我們關(guān)閉端點的時候（比如，一年后替代方案上線），用戶該如何確保他們能得知這一情況（郵件列表、狀態(tài)頁面、HTTP 頭信息等）以及他們通常應(yīng)該做些什么（更新、檢查文檔、遵從Link頭信息）。

如果馬上就要廢棄某個 API 的話，添加這樣的鏈接作用其實不大，但是如果你能在一年前就將其發(fā)布出去的話，你的客戶端可能已經(jīng)為此做好了準(zhǔn)備。

除此之外，發(fā)布 Sunset/Deprecation 策略的最好時間就是現(xiàn)在。如果你恰好正以某種方式編寫 Deprecation 文檔的話，這么做是值得考慮的。

組合到一起

按照設(shè)計，這些組成部分能很好地協(xié)作。例如，為了表明某個最近廢棄的 API，該 API 會在 6 個月內(nèi)徹底關(guān)閉，我們要鏈接至文檔并提供下一個版本的直接鏈接，那么我們應(yīng)該在響應(yīng)中包含如下的頭信息鏈接：

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. 漸進(jìn)式關(guān)閉

如果所有這些都已經(jīng)準(zhǔn)備到位，并且 sunset 截止時間已過，那么我們就可以將 API 關(guān)閉了。

但是，這并不意味著你需要立即且徹底消滅該 API。漸進(jìn)式關(guān)閉能有助于確保任何使用該 API 的所有客戶端都有最后的機(jī)會在它徹底消失前得到最后一次警告。GitHub 在 2018 年移除一些加密支持的時候曾經(jīng)這樣做：首先禁用一個小時，然后啟用它，最后在兩周后徹底禁用了它。

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

這里還有另外一個技巧：安卓在 2015 年為已廢棄的原生 API 增加了越來越多的延遲，在徹底關(guān)閉 API 前，最終達(dá)到了 16 秒的等待。

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

這些漸進(jìn)式的關(guān)閉為那些錯過截止日期的客戶端提供了一些靈活性，并且能幫助那些沒有注意到廢棄時間點的客戶端，從而能在 API 徹底關(guān)閉之前處理一些問題。

4. 謹(jǐn)慎行事

不管采用哪種方式，只要你盡了最大的努力去溝通關(guān)于 API 關(guān)閉的事情，那么現(xiàn)在就可以關(guān)閉端點 / 特性 / 整個服務(wù)，刪除代碼，然后睡個好覺。

像這樣小心謹(jǐn)慎地進(jìn)行廢棄和關(guān)閉，可以讓你的客戶端盡可能清楚地知道他們該如何依賴你的 API，何時需要采取行動，以及他們需要做什么。這種變更可能是一件大事兒，這些信息是很重要的。

這些新的草案頭信息讓我們不僅可以與人類溝通，還能將這些信息暴露給自動化系統(tǒng)。隨著這些頭信息的普及，我很高興地開始看到有更多的工具建立在它們之上。通用的 HTTP 客戶端可以根據(jù)這些數(shù)據(jù)自動記錄有用的警告日志，API 生成器本身也能根據(jù) API 規(guī)范處理越來越多的問題，而 HTTP 調(diào)試器（如 HTTP Toolkit）可以在截獲的實時流量中為你突出顯示廢棄端點的使用。這是一個令人激動的時刻，我們可以開始安全地關(guān)閉 API 了！

https://httptoolkit.tech/

需要注意的是，這些頭信息是 HTTP 規(guī)范的草案。在最終確定前，它們有可能會發(fā)生變化。也就是說，它們經(jīng)歷了幾輪修改，從現(xiàn)在開始，它們不太可能發(fā)生巨大的變化，現(xiàn)在能廣泛測試它們了。

老舊的 API，該如何處理？

老舊的 API，該如何處理？