看操逼网站,国产灬性灬淫…乱…视频…,一区二区三区免费观看,亚洲AV无码精品,小h片免费观看,插美女网站,大鸡巴精品视频在线看,综合激情网五月

點(diǎn)擊“開(kāi)發(fā)者技術(shù)前線”，選擇“星標(biāo)??”
讓一部分開(kāi)發(fā)者看到未來(lái)

作者 | Tim Perry 譯者 | 張衛(wèi)濱策劃 | 萬(wàn)佳

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

萬(wàn)物都會(huì)有終結(jié)，HTTP API 也不例外。不論你的 API 今天看上去多么偉大，遲早有一天你會(huì)想發(fā)布一個(gè)全新的版本，新版本能更好地解決相同問(wèn)題，在各方面可能都會(huì)有所改善，但是它因?yàn)橛辛诵聟?shù)，與舊版本也無(wú)法兼容，或者你只是想徹底關(guān)閉舊的 API。總而言之，你現(xiàn)在的 API 不會(huì)永遠(yuǎn)存在。

但是，這并非輕而易舉就能完成的，因?yàn)槟愕?API 有客戶端。如果你關(guān)閉端點(diǎn)、參數(shù)或整個(gè) API 而沒(méi)有做出恰當(dāng)?shù)木娴脑挘撬麄兛隙〞?huì)非常不爽。

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

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

1. 制定計(jì)劃

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

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

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

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

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

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

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

要實(shí)現(xiàn)這一點(diǎn)，我們就要有一個(gè)計(jì)劃。我們首先要問(wèn)自己三個(gè)關(guān)鍵的問(wèn)題：

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

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

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

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

2. 溝通

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

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

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

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

Deprecation 頭信息

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

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

通過(guò)一個(gè)簡(jiǎn)單的 HTTP 頭信息，我們就可以聲明這一點(diǎn)：

Deprecation: true

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

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

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

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

Deprecation 鏈接

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

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

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

Latest-Version 鏈接

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

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

Latest-Version 鏈接

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

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

Successor-Version 鏈接

如果該 API 沒(méi)有新的等價(jià)版本，用戶最好遷移到一個(gè)完全不同的資源，它可能是一個(gè)很好的替代方案，那么我們使用 alternate 鏈接來(lái)指明這一點(diǎn)，如下所示：

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

Sunset 頭信息

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

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

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

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

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

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

Sunset 鏈接

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

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

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

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

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

組合到一起

按照設(shè)計(jì)，這些組成部分能很好地協(xié)作。例如，為了表明某個(gè)最近廢棄的 API，該 API 會(huì)在 6 個(gè)月內(nèi)徹底關(guān)閉，我們要鏈接至文檔并提供下一個(gè)版本的直接鏈接，那么我們應(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 截止時(shí)間已過(guò)，那么我們就可以將 API 關(guān)閉了。

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

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

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

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

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

4. 謹(jǐn)慎行事

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

像這樣小心謹(jǐn)慎地進(jìn)行廢棄和關(guān)閉，可以讓你的客戶端盡可能清楚地知道他們?cè)撊绾我蕾嚹愕?API，何時(shí)需要采取行動(dòng)，以及他們需要做什么。這種變更可能是一件大事兒，這些信息是很重要的。

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

https://httptoolkit.tech/

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

不過(guò)這也意味著還有時(shí)間進(jìn)行反饋! 如果你對(duì)它們的工作方式和如何更好地運(yùn)行有想法的話，請(qǐng)與“Building Blocks for HTTP APIs”工作組聯(lián)系。你可以給郵件列表發(fā)郵件：[email protected]。

老舊的API，你應(yīng)該如何處理？