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

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

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

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