1. <dl id='4yaswx'><dl dropzone='zch8zdq2'></dl></dl>
                    <u dropzone='uqndzorc'></u>

                      文章熱詞:api,接口設計

                      日期:2019-07-23 09:57 by 楊國偉 1300 1 收藏
                      我要分享

                      摘要:設計接口是一件容易的事,也是件困難的事。設計接口每個人都會,每個人都能設計,也由此産生了各種各樣的理念的接口。工作這麽多年,我也很有感悟。很多人會說,設計接口多麽簡單,隻要命名好,然後聯調通了,上線可以調用就行了。特别是非互聯網行業的人,這裏沒有歧視的意思。因爲互聯網行業和傳統行業太多不一緻性決定了這種思想的産生。

                      u=1624135530,3530612429&fm=11&gp=0.jpg

                      接口是項目裏面的最小粒度的單元,接口設計需要注意點很多,需要的考慮方方面面,很多人也不重視,而且設計接口需要的技術棧也需要很多,能充分考察到技術人的知識的廣度以及深度。下面介紹的是在工作中的一些總結,希望能與諸位共同交流,探讨。

                      一、接口版本化

                          生産環境中,如果沒有版本控制的程序變更會導緻調用接口的相關方頻繁的跟着變更,假設相關方沒有及時的跟着變更,那麽系統就會報錯,從而影響到用戶的使用及體驗,使其對整個系統的運營都是不利的,接口對接的難度也會不斷的加大。

                          如果接口能夠有版本的控制,則升級系統的主動權就掌握在相關方,這樣當有新版本的程序發布時舊版本的業務邏輯不會受到影響,從用戶感知上也受到的影響就比較小,相關方也可以根據自身的條件是否要升級版本。

                      二、接口面向的應用場景

                          在對接口進行設計時,我們還要考慮接口是面向web前端開發還是手機app開發,或者服務端開發。不同的應用場景接口總體規劃是不同的(例如:當我們的接口是提供給web前端或APP端使用時,接口安全驗證我們可以采用jwt、oauth2.0等,如果我們的接口是提供給後端服務使用時,那麽我可以采用token機制)。

                      三、請求參數的規範性及處理的統一性

                          請求參數的規範性意思就是說,接口要以什麽樣的方式來接收參數。是統一使用json的方式接收呢還是xml或者form表單方式接收。

                          在開發接口應該統一在一個地方進行對參數的接收、校驗等操作。爲了保證參數的完整性,我們可以考慮新增簽名驗證等處理。

                      四、返回數據類型、返回碼及信息提示的規範性

                          返回給客戶端的數據類型應該要統一化(例如:我們統一以json的形式進行返回,或者是統一以xml的形式返回)。

                          不同的接口設計模式返回碼也會不同,如果使用現在非常火也比較流行的restfull風格那麽就應該要準許restfull風格的返回碼規定。如果是統一采用自定返回碼的話在設計返回碼時,應該要學會針對不同的業務處理模塊對返回碼進行分段處理(例如:系統基礎管理我們使用10000-10050,用戶管理則就應該要從10051到10100,……),針對不同業務模塊我們要預留足夠的返回碼,因爲後期針對該模塊的開發可能還會有其它業務的擴展或者調整等問題。返回碼分段處理的一個好處就是方便調用接口的相關方能夠很快的定位到錯誤是屬于哪一個部分,同時也方便接口開發人員定位接口錯誤在哪個地方。

                          除了返回碼,我們對接口返回的錯誤提示信息和接口調用成功的提示信息都應該明确,提示到點上。當然有些錯誤信息可能是自身API的bug或者服務器的問題等因素,這樣的話我們就應該要轉化一下提示不能把API自身問題暴露給接口調用相關方,這樣會導緻接口的安全性等問題。

                      五、接口安全驗證及權限的控制

                          接口并不是每個操作者都能請求訪問的,所以我們要爲接口提供一個安全驗證,就像用戶登錄系統一樣,沒有在我們系統注冊的合法用戶我們是不允許請求訪問的。那麽我們要如何對接口進行安全驗證呢?其實針對不同的應用場景我們的接口安全驗證也不一樣(例如:當我們的接口是提供給web前端或APP端使用時,接口安全驗證我們可以采用jwt、oauth2.0等,如果我們的接口是提供給後端服務使用時,那麽我可以采用token機制)。

                          權限的控制是指針對不同的用戶群體,我們要分配不同的權限(例如:超級管理員可以操作所有接口,普通用戶隻允許操作部分接口),這裏除了針對用戶群體我們可以針對不同的調用接口的相關方(這裏的相關方是指調用接口的應用)進行權限控制。

                      六、接口調用頻率的控制

                          對接口的調用頻率進行控制從另一方面來講也是爲了接口的安全性及接口的可維護性,當然這裏是否要對接口訪問次數進行控制還是取決于接口針對不同的應用場景,有些接口的設計是不需要限制調用頻率的,而有些接口則對接口調用是要進行嚴格控制的(例如:大家熟知的微信公衆号的開發就是對接口的調用頻率進行限制,并且針對不同的場景及用戶群體限制的頻率也不一樣)。

                      七、請求接口日志的記錄

                          我們應該要爲接口請求做一下日志的記錄,這樣我們後期維護接口時則會大大降低維護成本。而且還可以針對日志進行相關的統計處理。

                      八、接口文檔的可讀性

                          接口文檔的可讀性非常重要,一個接口開發出來并不是真正的完成,如果别人不會使用你的接口,那麽你的接口開發出來也是沒有用的,好多程序員非常的不重視接口文檔撰寫及接口文檔可讀性,寫出來的文檔就像一本天書看着就頭大。好的文檔應該讓人一看就知道如何調用,如何規避一些坑,簡單明了等等。這裏我介紹兩個比較好的接口管理可視化工具給大家參考一下,swagger和阿裏巴巴的rap。有空可以去搜索一下。

                      上一篇:PHP實現頁面靜态化

                      下一篇:塗磊-用心說話


                      評論