中興AX5400Pro+上手體驗：再升級 雙2.5G網(wǎng)口+USB 3.0這次全都有
2021年11月的時候，中興先后發(fā)布了兩款路由器產(chǎn)品，中興AX5400和中興AX5400 Pro，從產(chǎn)品命名上就不難看出這是隸屬于同一系列的，但在外觀設(shè)計上這兩款產(chǎn)品可以說是完全沒一點關(guān)系
今天延續(xù)設(shè)計的話題，給大家總結(jié)了接口設(shè)計的18條軍規(guī)，希望對你會有所幫助。
為了防止API接口中的數(shù)據(jù)被篡改，很多時候我們需要對API接口做簽名。
接口請求方將請求參數(shù) + 時間戳 + 密鑰拼接成一個字符串，然后通過md5等hash算法，生成一個前面sign。
然后在請求參數(shù)或者請求頭中，增加sign參數(shù)，傳遞給API接口。
API接口的網(wǎng)關(guān)服務(wù)，獲取到該sign值，然后用相同的請求參數(shù) + 時間戳 + 密鑰拼接成一個字符串，用相同的m5算法生成另外一個sign，對比兩個sign值是否相等。
如果兩個sign相等，則認(rèn)為是有效請求，API接口的網(wǎng)關(guān)服務(wù)會將給請求轉(zhuǎn)發(fā)給相應(yīng)的業(yè)務(wù)系統(tǒng)。
如果兩個sign不相等，則API接口的網(wǎng)關(guān)服務(wù)會直接返回簽名錯誤。
問題來了：簽名中為什么要加時間戳？
答：為了安全性考慮，防止同一次請求被反復(fù)利用，增加了密鑰沒破解的可能性，我們必須要對每次請求都設(shè)置一個合理的過期時間，比如：15分鐘。
這樣一次請求，在15分鐘之內(nèi)是有效的，超過15分鐘，API接口的網(wǎng)關(guān)服務(wù)會返回超過有效期的異常提示。
目前生成簽名中的密鑰有兩種形式：
一種是雙方約定一個固定值privateKey。
另一種是API接口提供方給出AK/SK兩個值，雙方約定用SK作為簽名中的密鑰。AK接口調(diào)用方作為header中的accessKey傳遞給API接口提供方，這樣API接口提供方可以根據(jù)AK獲取到SK，而生成新的sgin。
有些時候，我們的API接口直接傳遞的非常重要的數(shù)據(jù)，比如：用戶的登錄密碼、銀行卡號、轉(zhuǎn)賬金額、用戶身份證等，如果將這些參數(shù)，直接明文，暴露到公網(wǎng)上是非常危險的事情。
由此，我們需要對數(shù)據(jù)進行加密。
比如：用戶注冊接口，用戶輸入了用戶名和密碼之后，需要將密碼加密。
我們可以使用AES對稱加密算法。
在前端使用公鑰對用戶密碼加密。
然后注冊接口中，可以使用密鑰解密，做一些業(yè)務(wù)需求校驗。然后再換成其他的加密方式加密，保存到數(shù)據(jù)庫當(dāng)中。
為了進一步加強API接口的安全性，防止接口的簽名或者加密被破解了，攻擊者可以在自己的服務(wù)器上請求該接口。
需求限制請求ip，增加ip白名單。
只有在白名單中的ip地址，才能成功請求API接口，否則直接返回?zé)o訪問權(quán)限。
ip白名單也可以加在API網(wǎng)關(guān)服務(wù)上。
但也要防止公司的內(nèi)部應(yīng)用服務(wù)器被攻破，這種情況也可以從內(nèi)部服務(wù)器上發(fā)起API接口的請求。
這時候就需要增加web防火墻了，比如：ModSecurity等。
如果你的API接口被第三方平臺調(diào)用了，這就意味著著，調(diào)用頻率是沒法控制的。
第三方平臺調(diào)用你的API接口時，如果并發(fā)量一下子太高，可能會導(dǎo)致你的API服務(wù)不可用，接口直接掛掉。
由此，必須要對API接口做限流。
限流方法有三種：
我們在實際工作中，可以通過nginx，redis或者gateway實現(xiàn)限流的功能。
我們需要對API接口做參數(shù)校驗，比如：校驗必填字段是否為空，校驗字段類型，校驗字段長度，校驗枚舉值等等。
這樣做可以攔截一些無效的請求。
比如在新增數(shù)據(jù)時，字段長度超過了數(shù)據(jù)字段的最大長度，數(shù)據(jù)庫會直接報錯。
但這種異常的請求，我們完全可以在API接口的前期進行識別，沒有必要走到數(shù)據(jù)庫保存數(shù)據(jù)那一步，浪費系統(tǒng)資源。
有些金額字段，本來是正數(shù)，但如果用戶傳入了負(fù)數(shù)，萬一接口沒做校驗，可能會導(dǎo)致一些沒必要的損失。
還有些狀態(tài)字段，如果不做校驗，用戶如果傳入了系統(tǒng)中不存在的枚舉值，就會導(dǎo)致保存的數(shù)據(jù)異常。
由此可見，做參數(shù)校驗是非常有必要的。
在Java中校驗數(shù)據(jù)使用最多的是hiberate的Validator框架，它里面包含了@Null、@NotEmpty、@Size、@Max、@Min等注解。
用它們校驗數(shù)據(jù)非常方便。
當(dāng)然有些日期字段和枚舉字段，可能需要通過自定義注解的方式實現(xiàn)參數(shù)校驗。
我之前調(diào)用過別人的API接口，正常返回數(shù)據(jù)是一種json格式，比如：
{ "code":0, "message":null, "data":[{"id":123,"name":"abc"}]},簽名錯誤返回的json格式：
{ "code":1001, "message":"簽名錯誤", "data":null}沒有數(shù)據(jù)權(quán)限返回的json格式：
{ "rt":10, "errorMgt":"沒有權(quán)限", "result":null}這種是比較坑的做法，返回值中有多種不同格式的返回數(shù)據(jù)，這樣會導(dǎo)致對接方很難理解。
出現(xiàn)這種情況，可能是API網(wǎng)關(guān)定義了一直返回值結(jié)構(gòu)，業(yè)務(wù)系統(tǒng)定義了另外一種返回值結(jié)構(gòu)。如果是網(wǎng)關(guān)異常，則返回網(wǎng)關(guān)定義的返回值結(jié)構(gòu)，如果是業(yè)務(wù)系統(tǒng)異常，則返回業(yè)務(wù)系統(tǒng)的返回值結(jié)構(gòu)。
但這樣會導(dǎo)致API接口出現(xiàn)不同的異常時，返回不同的返回值結(jié)構(gòu)，非常不利于接口的維護。
其實這個問題我們可以在設(shè)計API網(wǎng)關(guān)時解決。
業(yè)務(wù)系統(tǒng)在出現(xiàn)異常時，拋出業(yè)務(wù)異常的RuntimeException，其中有個message字段定義異常信息。
所有的API接口都必須經(jīng)過API網(wǎng)關(guān)，API網(wǎng)關(guān)捕獲該業(yè)務(wù)異常，然后轉(zhuǎn)換成統(tǒng)一的異常結(jié)構(gòu)返回，這樣能統(tǒng)一返回值結(jié)構(gòu)。
我們的API接口需要對異常進行統(tǒng)一處理。
不知道你有沒有遇到過這種場景：有時候在API接口中，需要訪問數(shù)據(jù)庫，但表不存在，或者sql語句異常，就會直接把sql信息在API接口中直接返回。
返回值中包含了異常堆棧信息、數(shù)據(jù)庫信息、錯誤代碼和行數(shù)等信息。
如果直接把這些內(nèi)容暴露給第三方平臺，是很危險的事情。
有些不法分子，利用接口返回值中的這些信息，有可能會進行sql注入或者直接脫庫，而對我們系統(tǒng)造成一定的損失。
因此非常有必要對API接口中的異常做統(tǒng)一處理，把異常轉(zhuǎn)換成這樣：
{ "code":500, "message":"服務(wù)器內(nèi)部錯誤", "data":null}返回碼code是500，返回信息message是服務(wù)器內(nèi)部異常。
這樣第三方平臺就知道是API接口出現(xiàn)了內(nèi)部問題，但不知道具體原因，他們可以找我們排查問題。
我們可以在內(nèi)部的日志文件中，把堆棧信息、數(shù)據(jù)庫信息、錯誤代碼行數(shù)等信息，打印出來。
我們可以在gateway中對異常進行攔截，做統(tǒng)一封裝，然后給第三方平臺的是處理后沒有敏感信息的錯誤信息。
在第三方平臺請求你的API接口時，接口的請求日志非常重要，通過它可以快速的分析和定位問題。
我們需要把API接口的請求url、請求參數(shù)、請求頭、請求方式、響應(yīng)數(shù)據(jù)和響應(yīng)時間等，記錄到日志文件中。
最好有traceId，可以通過它串聯(lián)整個請求的日志，過濾多余的日志。
當(dāng)然有些時候，請求日志不光是你們公司開發(fā)人員需要查看，第三方平臺的用戶也需要能查看接口的請求日志。
這時就需要把日志落地到數(shù)據(jù)庫，比如：mongodb或者elastic search，然后做一個UI頁面，給第三方平臺的用戶開通查看權(quán)限。這樣他們就能在外網(wǎng)查看請求日志了，他們自己也能定位一部分問題。
第三方平臺極有可能在極短的時間內(nèi)，請求我們接口多次，比如：在1秒內(nèi)請求兩次。有可能是他們業(yè)務(wù)系統(tǒng)有bug，或者在做接口調(diào)用失敗重試，因此我們的API接口需要做冪等設(shè)計。
也就是說要支持在極短的時間內(nèi)，第三方平臺用相同的參數(shù)請求API接口多次，第一次請求數(shù)據(jù)庫會新增數(shù)據(jù)，但第二次請求以后就不會新增數(shù)據(jù)，但也會返回成功。
這樣做的目的是不會產(chǎn)生錯誤數(shù)據(jù)。
我們在日常工作中，可以通過在數(shù)據(jù)庫中增加唯一索引，或者在redis保存requestId和請求參來保證接口冪等性。
對于對我提供的批量接口，一定要限制請求的記錄條數(shù)。
如果請求的數(shù)據(jù)太多，很容易造成API接口超時等問題，讓API接口變得不穩(wěn)定。
通常情況下，建議一次請求中的參數(shù)，最多支持傳入500條記錄。
如果用戶傳入多余500條記錄，則接口直接給出提示。
建議這個參數(shù)做成可配置的，并且要事先跟第三方平臺協(xié)商好，避免上線后產(chǎn)生不必要的問題。
對于一次性查詢的數(shù)據(jù)太多的情況，我們需要將接口設(shè)計成分頁查詢返回的。
上線前我們務(wù)必要對API接口做一下壓力測試，知道各個接口的qps情況。
以便于我們能夠更好的預(yù)估，需要部署多少服務(wù)器節(jié)點，對于API接口的穩(wěn)定性至關(guān)重要。
之前雖說對API接口做了限流，但是實際上API接口是否能夠達到限制的閥值，這是一個問號，如果不做壓力測試，是有很大風(fēng)險的。
比如：你API接口限流1秒只允許50次請求，但實際API接口只能處理30次請求，這樣你的API接口也會處理不過來。
我們在工作中可以用jmeter或者apache benc對API接口做壓力測試。
一般的API接口的邏輯都是同步處理的，請求完之后立刻返回結(jié)果。
但有時候，我們的API接口里面的業(yè)務(wù)邏輯非常復(fù)雜，特別是有些批量接口，如果同步處理業(yè)務(wù)，耗時會非常長。
這種情況下，為了提升API接口的性能，我們可以改成異步處理。
在API接口中可以發(fā)送一條mq消息，然后直接返回成功。之后，有個專門的mq消費者去異步消費該消息，做業(yè)務(wù)邏輯處理。
直接異步處理的接口，第三方平臺有兩種方式獲取到。
第一種方式是：我們回調(diào)第三方平臺的接口，告知他們API接口的處理結(jié)果，很多支付接口就是這么玩的。
第二種方式是：第三方平臺通過輪詢調(diào)用我們另外一個查詢狀態(tài)的API接口，每隔一段時間查詢一次狀態(tài)，傳入的參數(shù)是之前的那個API接口中的id集合。
有時候第三方平臺調(diào)用我們API接口時，獲取的數(shù)據(jù)中有一部分是敏感數(shù)據(jù)，比如：用戶手機號、銀行卡號等等。
這樣信息如果通過API接口直接保留到外網(wǎng)，是非常不安全的，很容易造成用戶隱私數(shù)據(jù)泄露的問題。
這就需要對部分?jǐn)?shù)據(jù)做數(shù)據(jù)脫敏了。
我們可以在返回的數(shù)據(jù)中，部分內(nèi)容用星號代替。
已用戶手機號為例：182****887。
這樣即使數(shù)據(jù)被泄露了，也只泄露了一部分，不法分子拿到這份數(shù)據(jù)也沒啥用。
說實話，一份完整的API接口文檔，在雙方做接口對接時，可以減少很多溝通成本，讓對方少走很多彎路。
接口文檔中需要包含如下信息：
接口文檔中最好能夠統(tǒng)一接口和字段名稱的命名風(fēng)格，比如都用駝峰標(biāo)識命名。
統(tǒng)一字段的類型和長度，比如：id字段用Long類型，長度規(guī)定20。status字段用int類型，長度固定2等。
統(tǒng)一時間格式字段，比如：time用String類型，格式為：yyyy-MM-dd HH:mm:ss。
接口文檔中寫明AK/SK和域名，找某某單獨提供等。
接口支持的請求方式有很多，比如：GET、POST、PUT、DELETE等等。
我們在設(shè)計接口的時候，要根據(jù)實際情況選擇使用哪種請求方式。
實際工作中使用最多的是：GET和POST，這兩種請求方式。
如果沒有輸入?yún)?shù)的接口，可以使用GET請求方式，問題不大。
如果有輸入?yún)?shù)的接口，推薦使用POST請求方式，坑更少。
主要原因有下面兩點：
對于一些公共的功能，比如：接口的權(quán)限驗證，或者接口的traceId參數(shù)。
我們在設(shè)計接口的時候，不用把所有的參數(shù)，都放入接口的請求參數(shù)中。
有些參數(shù)可以放到Header請求頭中。
比如：我們需求記錄每個請求的traceId，不用在所有接口中都加traceId字段。
而改成讓用戶在header中傳入traceId，在服務(wù)端使用統(tǒng)一的攔截器解析header，即可獲取該traceId了。
我們在設(shè)計接口的時候，無論是查詢數(shù)據(jù)、添加數(shù)據(jù)、修改數(shù)據(jù)，還是刪除的場景，都應(yīng)該考慮一下能否設(shè)計成批量的。
很多時候，需要通過id查詢數(shù)據(jù)詳情，比如：通過訂單id，查詢訂單詳情。
如果你的接口只支持，通過一個id，查詢一個訂單的詳情。
那么，后面需要通過多個id，查詢多個訂單詳情的時候，就需要額外增加接口了。
如果你添加數(shù)據(jù)的接口，只支持一條數(shù)據(jù)一條數(shù)據(jù)的添加。
后面，有個job需要一次性添加1000條數(shù)據(jù)的時候，這時在代碼中循環(huán)1000次，一個個添加，這種做法效率比較低。
為了讓你的接口設(shè)計的更加通用，滿足更多的業(yè)務(wù)場景，能設(shè)計成批量的，盡量別設(shè)計成單個的。
我之前見過有些小伙伴設(shè)計的接口，在入?yún)⒅懈鞣N條件都支持，在Service層有N多的if...else判斷。
而且返回的實體類中，包含了各種場景下的返回值字段，字段很多很全。
接口上線一年之后，自己可能都忘了，在哪些業(yè)務(wù)場景下，要傳入哪些字段，返回值是哪些字段。
這類接口的維護成本非常高，而且又不敢輕易重構(gòu)，怕改了A業(yè)務(wù)場景，影響B(tài)業(yè)務(wù)場景的功能，這種接口讓人非常痛苦的。
好的接口設(shè)計原則是：職責(zé)單一。
比如用戶下單的場景，有web端和移動端。
而每個端都有普通下單和快速下單，兩種不同的業(yè)務(wù)場景。
我們在設(shè)計接口的時候，可以將web端和移動端的接口在controller層完全分開。
/web/v1/order/mobile/v1/order并且將普通下單和快速下單也分開：
/web/v1/order/create/web/v1/order/fastCreate/mobile/v1/order/create/mobile/v1/order/fastCreate這樣可以設(shè)計成4個接口。
業(yè)務(wù)邏輯更清晰一些，方便后面維護。
本文鏈接：http://m.www897cc.com/showinfo-26-90672-0.html接口設(shè)計的18條軍規(guī)
聲明：本網(wǎng)頁內(nèi)容旨在傳播知識，若有侵權(quán)等問題請及時與本網(wǎng)聯(lián)系，我們將在第一時間刪除處理。郵件：2376512515@qq.com
Copyright ? 2016-2023 天津谷騏科技有限公司 版權(quán)所有 sitemap.xml
違法及侵權(quán)請聯(lián)系：2376512515@qq.com 津ICP備18001702號
津公網(wǎng)安備 12010102000574號