通用接口標(biāo)準(zhǔn)規(guī)范

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

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

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