## 一、概述 wbase uniframework平臺提供了一套獨立運行的開放服務子平臺。它是基于oauth2的開放接口平臺；  >[danger] 開放接口平臺，實質上，就是wbase提供的微服務內核，它不僅可用于對外充當API網關的作用，對于基于平臺的應用來說，無論是外部業務、內部應用，還是APP，也都可以通過開放服務體系，獲取授權資源； ## 二、接入流程 對于系統廠商來說，流程如下： 1、創建微服務賬號，也就是創建一個用戶，該用戶必須擁有微服務角色，這將自動的為該賬戶創建一個未啟用的開放服務應用，包含對應的appId及appSecret（在應用設置中可以看到這兩個參數） ；  >[danger] 微服務角色是平臺內置的專用于定義微服務客戶的角色； > 2、在應用設置中，設置該賬戶訪微服務的服務器ip地址，可以有多個，設置完畢，就可以啟用該賬戶開放服務應用了；  3、設置該客戶可以使用的api，默認的，剛開通的用戶除了正式測試用的API之外，沒有任何api授權，需要根據實際業務，給客戶授權它應用擁有的api；  4，將該appId及appSecret提供給客戶，就完成了微服務開戶完整流程； 對于微服務客戶來說，流程如下： 1）、申請接口，提供調用ip地址給廠商，獲取自己的appId和appSecret； 2）、閱讀接口文檔（定義具體api及其語義的），編寫測試代碼，提交測試ip； 3）、測試完畢，上線； ## 三、開通服務 api服務地址：http://ip:port/oauth/service， >[danger] > 1、api服務地址+api的url組合，構成了客戶端api請求的完整地址； > 2、比如平臺內置提供了一個用于測試驗證的api，其url是/test/validation，那么實際完整的請求地址應當為：http://ip:port/oauth/service/test/validation ## 四、技術要求 1.所有接口的請求，采用httpPost方式提交，發出http請求的時候，請求content-type需設定為：application/x-www-form-urlencoded;charset=UTF-8 ，參數按照普通表單參數傳值，不必包裹成一個json字符串； 2.所有接口的響應，采用json格式，編碼為UTF-8，響應的content-type為：application/json;charset=UTF-8； 3.提供ip白名單功能，僅供授權的ip調用； 4.每個對外提供服務的api，都必須包含的參數為appId及timeStamp； 5.每個對外提供服務的api，都必須包含一個sign參數，該參數是通過算法計算出來的值； 6.考慮服務器承載量，目前限制每個ip訪問接口頻率，程序中不得做高頻率輪詢； 7.接口服務自身的設計與開發是基于BASE理論。因此，也強烈建議代碼編寫者遵循該理論；程序開發者必需考慮接口服務器因機房網絡故障、域名解析故障、例行檢修、程序升級、依賴服務中斷等因素導致當前服務不可用。因此，業務邏輯的編寫必須嚴格的核對響應碼，并且必須編寫消費接口服務的異常分支邏輯； >[danger] 只有responseCode為1，才說明您的api執行成功，其他的任何數字都是失敗的，只是失敗的原因不同； ## 五、時間戳格式 1.獲取從1970, 00:00:00開始到當前的毫秒數(13位) 2.每個api請求的有效時間為3分鐘,所以,務必確保當前服務請求的時間是準確的； ## 六、簽名算法 假設：paramstrings = 當前api的所有參數(除sign自身外)，根據參數名升序排序，以“參數名=值&”的方式連接起來； 結果：sign = md5(md5(paramstrings)+appSecret) >[danger] 注意： > 1、是雙層md5加密，中間那個"+"僅表示兩段字符相連,組合的結果并不包括該符號本身； > 2、簽名計算放到參數傳值的最后，因為要用到接口所有參數（除sign自身外）參與加密計算； ## 七、接口限流 對外服務的每個API接口當訪問頻率或者并發量超過其承受范圍時候,我們就必須考慮限流來保證接口的可用性或者降級可用性.以防止非預期的請求對系統壓力過大而引起的系統癱瘓； ### (1) 算法 平臺采用令牌桶算法進行限流，針對每個appId（客戶端），都限制其每秒鐘可以接收的請求數，確保整個對外服務正常有序； 令牌桶算法的原理是系統會以一個恒定的速度往桶里放入令牌，而如果請求需要被處理，則需要先從桶里獲取一個令牌，當桶里沒有令牌可取時，則拒絕服務；  ### (2) 設置 系統參數配置中，可以設定每個appId每秒請求數限制：  ### (3) 注意 >[danger]正常的訪問平臺是通過接口限流策略，實現了業務可用性保障；對應非正常的訪問，平臺則通過DDOS防御設施，實現業務可用性保障； ## 八、同步服務接口與異步服務接口 微服務的服務類型包括兩種： >[danger] > 1、同步服務，請求該服務的時候，立即實時返回結果； > 2、異步服務，請求該服務的時候，微服務只是將該請求記錄下來，后續通過調度服務平臺來執行一系列的動作或命令。適合比較耗時的業務，優點是提高客戶端的體驗，讓它無須長時間等待即可返回； ## 九、典型接口說明 ~~~[api] post:/test/validation *string:appId=s123#聯系我們獲取 *string:timeStamp=1584362438966#當前時間戳，13位數字，該時間戳在30分鐘內會失效，30分鐘后訪問該地址，會返回請求時間戳不合法； *paramLong#參數1 *paramFloat#參數2 *string:sign=xxrreedfasdfsafsfs231999999oo#簽名，按照約定規則 <<< success { "responseMessage": "成功", "responseCode": 1, "requestStartTime": 1584837900324, "requestEndTime": 1584837901513, "responseCostTime": "1189毫秒", "feedback": { "isBusinessSuccess": true, "executionMessage": "實時接口,直接顯示查詢結果", "data": "data" } } <<< error { "responseCode": -99, "responseMessage": "失敗", "requestStartTime": 1584837900324, "requestEndTime": 1584837901513, "responseCostTime": "1189毫秒" } ~~~ >[danger] 只有responseCode為1，才能說明這個api執行成功了，否則，都是失敗，只是失敗原因各不相同，具體可以參照下表； > | 錯誤碼 | 錯誤原因 | | --- | --- | | -1 | 當前ip地址不在訪問白名單,請聯系管理員. | | -2 | 不支持當前http請求模式 | | -3 | 當前請求的url不符合約定的組成語法，一般是您的url請求地址沒按照約定提供 | | -4 | 當前請求參數沒有包含appId. | | -5 | 當前請求參數沒有包含時間戳. | | -6 | 當前請求參數沒有包含簽名. | | -7 | 當前請求appId無效. | | -8 | 當前請求簽名不合法. | | -9 | 當前請求時間已經超時. | | -10 | 當前請求的api不存在. | | -11 | 當前appId請求數超過允許的限制 | | -12 | 當前請求的api沒有獲得授權 | | -99 | 業務自身錯誤信息 | ## 十、平臺功能 平臺提供了相關的功能，具體可以參考：[系統平臺/開放服務](系統平臺/開放服務.md)