通用接口標準規(guī)范

--本頁僅作為文檔封面，使用時請直接刪除即可--

--內(nèi)頁可以根據(jù)需求調(diào)整合適字體及大小本頁僅作為文檔封面，使用時請直接刪除即可--

--內(nèi)頁可以根據(jù)需求調(diào)整合適字體及大小--通用接口標準規(guī)范v1(總10頁)PAGE接口標準規(guī)范NO.修改后版本號修改的頁碼及條款修改類型、原因及說明修改人修改時間1全文創(chuàng)建2019/1/1目錄接口標準規(guī)范 1第1章 概述 3第2章 基本要求 4信息通訊安全 4安全評估 4訪問控制 4防惡意代碼 4加密 5支持高并發(fā) 6可監(jiān)控 6日志全覆蓋 6系統(tǒng)資源的動態(tài)擴展 6異常處理機制 7業(yè)務擴展 7第3章 接口通訊方式 7同步請求/應答方式 7異步請求/應答方式 7會話方式 7廣播通知方式 7事件訂閱方式 7文件傳輸 8可靠消息傳輸 8第4章 傳輸控制要求 8負載均衡 8伸縮性與動態(tài)配置管理 8網(wǎng)絡調(diào)度 9充分理由 9單一職責 9高內(nèi)聚低耦合 9狀態(tài)及消息 10控制數(shù)據(jù)量 10禁止隨意拓展參數(shù) 10第5章 接口技術(shù) 10第6章 接口規(guī)范 11域名規(guī)范 11http接口 11webservice接口 11API路徑規(guī)范 11http接口 11webservice接口 11版本控制規(guī)范 12http接口 12webservice接口 12API命名規(guī)范 12新增方法 13刪除方法 13修改方法 13獲取方法 13獲取列表方法 13請求參數(shù)規(guī)范 14參數(shù)需要命名規(guī)則 14請求參數(shù)加密方法 14列表請求特殊規(guī)范 15返回數(shù)據(jù)規(guī)范 15第7章 接口文檔規(guī)范 16第8章 接口管理 16對接口分類、編碼排序。 16在線文檔。 16概述本文主要為了明確標準和規(guī)范，為服務使用方和服務提供方提供開發(fā)參考?；疽鬄榱吮ＷC系統(tǒng)的完整性和健壯性，系統(tǒng)接口應滿足下列基本要求：信息通訊安全安全評估保證接口的自身安全，通過接口實現(xiàn)技術(shù)上的安全控制，做到對安全事件的“可知、可控、可預測”，是實現(xiàn)系統(tǒng)安全的一個重要基礎(chǔ)。訪問控制如果客戶端很頻繁的請求服務器，會給給服務器造成很大的壓力，需要對客戶端對API的請求做一些限制。比如單位時間內(nèi)同一IP只能請求多少次。防惡意代碼用戶名sql注入例如：用戶名sql注入登錄名輸入：lilei'#select*fromstudentwhereuser='lilei'andpsd='123456'sql語句就變成了select*fromstudentwhereuser='lilei'#'andpsd='123456'(#/--后面的內(nèi)容都會被注釋掉)跨站腳本例如腳本攻擊測試：<script>alter(123456)</script>命令注入：PHP提供部分函數(shù)用來執(zhí)行外部應用程序異常字符測試：結(jié)束符、換行符，針對字符串，在中間插入特殊字符，比如結(jié)束符等，服務端沒有進行驗證1、調(diào)用可執(zhí)行的系統(tǒng)命令函數(shù)。2、函數(shù)活著函數(shù)的參數(shù)控制。3、拼接注入命令<script>alter(123456)</script>。命令注入：PHP提供部分函數(shù)用來執(zhí)行外部應用程序異常字符測試：結(jié)束符、換行符，針對字符串，在中間插入特殊字符，比如結(jié)束符等，服務端沒有進行驗證1、調(diào)用可執(zhí)行的系統(tǒng)命令函數(shù)。2、函數(shù)活著函數(shù)的參數(shù)控制。3、拼接注入命令。加密接口調(diào)用方和接口提供方約定好統(tǒng)一的參數(shù)加密算法。（加密方法參照接口規(guī)范的請求參數(shù)規(guī)范）接口調(diào)用方在調(diào)用時把加密后的_sign放在參數(shù)中去請求接口。接口提供方接到響應后，判斷時間戳是不是在有效時間內(nèi)（這個時間間隔根據(jù)你的安全范圍可以是10分鐘，5分鐘，20秒等，過期失效，前提是需要保證接口提供方和調(diào)用方的服務器時間為準確的網(wǎng)絡同步時間）。把參數(shù)中除了_sign以外的參數(shù)進行加密，然后把加密結(jié)果和傳過來的_sign比較，相同則執(zhí)行調(diào)用請求。如果服務器和客戶端的時間沒有同步，可以返回錯誤的同時候在返回一個服務器的當前時間，客戶端接收到該錯誤后再請求上一個接口，時間則傳服務器剛剛返回的時間。涉及到比較重要的信息，可以用AES對value進行加密，防止抓包拉取到上傳的數(shù)據(jù)。支持高并發(fā)根據(jù)實際情況選擇合適的方式方法來實現(xiàn)，可動態(tài)通過集群節(jié)點進行擴展。例如：Java的并發(fā)包提供了三個常用的并發(fā)隊列實現(xiàn)，分別是：ArrayBlockingQueue、ConcurrentLinkedQueue和LinkedBlockingQueue可監(jiān)控日志全覆蓋正常運行信息異常捕獲信息日志打印規(guī)范滿足運維需求、日志格式統(tǒng)一規(guī)范。系統(tǒng)資源的動態(tài)擴展保證在充分利用系統(tǒng)資源的前提下，實現(xiàn)系統(tǒng)平滑的移植和擴展，同時在系統(tǒng)并發(fā)增加時提供系統(tǒng)資源的動態(tài)擴展，以保證系統(tǒng)的穩(wěn)定性。異常處理機制表單驗證、唯一性檢查、或其他可預期的錯誤。我們需要編寫特定代碼來捕獲這類錯誤，并拋出一個包含提示信息的全局異常，捕獲并返回給客戶端。業(yè)務擴展在進行新業(yè)務擴展時，應能提供快速、方便和準確的實現(xiàn)方式。接口通訊方式同步請求/應答方式客戶端向服務器端發(fā)送服務請求，客戶端阻塞等待服務器端返回處理結(jié)果。異步請求/應答方式客戶端向服務器端發(fā)送服務請求，與同步方式不同的是，在此方式下，服務器端處理請求時，客戶端繼續(xù)運行；當服務器端處理結(jié)束時返回處理結(jié)果。會話方式客戶端與服務器端建立連接后，可以多次發(fā)送或接收數(shù)據(jù)，同時存儲信息的上下文關(guān)系廣播通知方式由服務器端主動向客戶端以單個或批量方式發(fā)出未經(jīng)客戶端請求的廣播或通知消息，客戶端可在適當?shù)臅r候檢查是否收到消息并定義收到消息后所采取的動作事件訂閱方式客戶端可事先向服務器端訂閱自定義的事件，當這些事件發(fā)生時，服務器端通知客戶端事件發(fā)生，客戶端可采取相應處理。事件訂閱方式使客戶端擁有了個性化的事件觸發(fā)功能，極大方便了客戶端及時響應所訂閱的事件文件傳輸客戶端和服務器端通過文件的方式來傳輸消息，并采取相應處理可靠消息傳輸在接口通訊中，基于消息的傳輸處理方式，除了可采用以上幾種通訊方式外，還可采用可靠消息傳輸方式，即通過存儲隊列方式，客戶端和服務器端來傳輸消息，采取相應處理傳輸控制要求傳輸控制利用高速數(shù)據(jù)通道技術(shù)實現(xiàn)把前端的大數(shù)據(jù)量并發(fā)請求分發(fā)到后端，從而保證應用系統(tǒng)在大量客戶端同時請求服務時，能夠保持快速、穩(wěn)定的工作狀態(tài)。系統(tǒng)應采用傳輸控制手段降低接口網(wǎng)絡負擔，提高接口吞吐能力，保證系統(tǒng)的整體處理能力。具體手段包括負載均衡、伸縮性與動態(tài)配置管理、網(wǎng)絡調(diào)度等功能：負載均衡有必要時為了確保接口服務吞吐量最大，接口應自動地在系統(tǒng)中完成動態(tài)負載均衡調(diào)度。伸縮性與動態(tài)配置管理由系統(tǒng)自動伸縮管理方式或動態(tài)配置管理方式實現(xiàn)隊列管理、存取資源管理，以及接口應用的恢復處理等。網(wǎng)絡調(diào)度當對接口有較高通訊保障要求時可能會在在雙方接口之間設(shè)置多個網(wǎng)絡通道，需要實現(xiàn)接口的多數(shù)據(jù)通道和容錯性，保證當有一網(wǎng)絡通道通訊失敗時，進行自動的切換，實現(xiàn)接口連接的自動恢復。接口設(shè)計原則充分理由不是隨便一個功能、需求就要加個接口。每新建一個接口，就要有充分的理由和考慮，即這個接口的存在是十分有意義額價值的，無意義的接口不僅增加了維護的難度，更重要是對于程序的可控性的大大降低，接口也會十分臃腫。單一職責一個接口只負責一個業(yè)務功能。 高內(nèi)聚低耦合一個接口要包含完整的業(yè)務功能，而不同接口之間的業(yè)務關(guān)聯(lián)要盡可能的小。還是查詢會員的例子，有時查詢會員的同時，可能該會員的相關(guān)信息要隨之發(fā)生變化(如狀態(tài))，如果這時一條完整的業(yè)務流水線，那么就應該在一個接口里完成，而不應再單獨設(shè)立接口去操作完成。就是說一個接口不應該隨著另一個變化而變化或以某幾個接口為前提而存在。狀態(tài)及消息提供必要的接口調(diào)用狀態(tài)信息。調(diào)用是否成功如果失敗，那么失敗的原因是什么。這些必要的信息必須要告訴給客戶端。提供必要的接口調(diào)用狀態(tài)信息。調(diào)用是否成功如果失敗，那么失敗的原因是什么。這些必要的信息必須要告訴給客戶端?？刂茢?shù)據(jù)量一個接口返回不應該包含過多的數(shù)據(jù)量，過多的數(shù)據(jù)量不僅處理復雜，對數(shù)據(jù)傳輸?shù)膲毫σ卜浅４螅瑫е驴蛻舳朔磻徛?。過多的數(shù)據(jù)量很多時候都是接口劃分不明確。禁止隨意拓展參數(shù)拓展接口可能是難以避免的，但是不要隨意就加參數(shù)，加參數(shù)一定是必要且有意義的，需求改變前首先應考慮現(xiàn)有接口內(nèi)部維護是否能滿足需求，而不要通過加個參數(shù)來方便自己實現(xiàn)需求的難度，因為參數(shù)的更變會直接導致客戶端調(diào)用的變化，容易產(chǎn)生版本兼容性問題。接口技術(shù)主要使用的接口技術(shù)的有webService和http。接口規(guī)范域名規(guī)范每個項目要有且僅有一個自己唯一的域名（或ip地址）+端口。如果一個域名（或ip地址）滿足不了要求，那么就需要再添加一個。http接口格式規(guī)范如下：“;“;webservice接口格式規(guī)范如下：，必須在路徑中添加api目錄格式規(guī)范如下：“;必須以字母開頭，并以“/”結(jié)尾。webservice接口因為webservice本身就是專門做接口用的技術(shù)所以接口路徑可以不用添加【api/】用來區(qū)分接口路徑。例如：，正式版本要確定接口版本、并備份接口代碼。為方便管理，需要在接口路徑中加入版本號信息。http接口格式規(guī)范如下：”;必須以字母開頭，并以“/”結(jié)尾。更新版本后可以使用v2v3等、依次遞加。webservice接口Webservice的接口對應函數(shù)命名格式采用小駝峰式方式命名，在函數(shù)名的最后加上版本V1。更新版本后可以用V2、V3等、依次遞加。API命名規(guī)范根據(jù)域名規(guī)范、API路徑規(guī)范和版本控制規(guī)范。Api地址值等于三個相加。格式規(guī)范如下：“接口方法必須要有自己的規(guī)范，命名必須統(tǒng)一使用小駝峰命名法。比如：（upperCamelCase）。所有接口命名方式，必須遵循如下規(guī)范。新增方法如新增一個地址、新增一個聯(lián)系人。命名規(guī)范：必須以“add”為前綴。例如addAddress事例地址：如獲取一個地址。命名規(guī)范：必須以“get”為前綴。例如getAddress事例地址：，指明數(shù)據(jù)類型。參數(shù)中文名英文名數(shù)據(jù)類型是否必填調(diào)用方idappKeySting例如（wuzheng）時間戳timeStamplong時間戳xxxloginIdString不可為空請求參數(shù)加密方法1）對除簽名外的所有請求參數(shù)按key做的升序排列,value無需編碼。（假設(shè)當前時間的時間戳是）例如：有c=3,b=2,a=1三個參，另加上時間戳后，按key排序后為：a=1，b=2，c=3，_timestamp=。2）把參數(shù)名和參數(shù)值連接成字符串，得到拼裝字符：a1b2c3_timestamp3）用申請到的appkey連接到接拼裝字符串尾部，然后進行32位MD5加密，最后將到得MD5加密摘要轉(zhuǎn)化成大寫。（如果沒有appkey則不需要拼接，需要加密鹽時另行約定告知）示例：假設(shè)appkey=test，md5(a1b2c3_timestamptest)，取得MD5摘要值C5F3EB5D7DC2748AED89E90AF00081E6。最后訪問連接參照C5F3EB5D7DC2748AED89E90AF00081E6列表請求特殊規(guī)范列表請求，請求參數(shù)規(guī)范，必須傳參：頁數(shù)和每頁個數(shù)的字段。并可包含查詢等信息。1.列表接口必傳字段（分頁、使用小寫字母）。page：頁數(shù)，從1開始。例如：{“page”:1}subnumber:每頁數(shù)量。2.列表接口選傳字段。只要是列表接口、一般情況下都會存在檢索條件，例如淘寶商品檢索。檢索條件為選填。后臺需進行非空非null判斷，選傳字段為空為null默認查詢?nèi)?。有值則需要接收，并進行sql查詢。規(guī)范事例：普通列表接口：，不傳就不檢索，只進行分頁查詢）（如果有時間、價格等檢索條件，不傳就不檢索，傳了就進行條件查詢，并返回相應數(shù)據(jù)）返回數(shù)據(jù)規(guī)范注：列表數(shù)據(jù)返回，沒有特殊情況的條件下，必須最新數(shù)據(jù)在上面，依次排序。返回事例：{"list":[],"object":{},."page":1,"subnumber":10,}必選-命名規(guī)范：小駝峰命名法。必選-新增鍵值規(guī)則：名字對應固定的格式（list就是數(shù)組[]）。比如：比如一個"list":[]滿足不了需求，那么可以新增一個"map":[]。比如如一個"object":{