1 目的

穩(wěn)定可靠，降本增效

前后端數(shù)據(jù)傳輸約定旨在提升系統(tǒng)穩(wěn)定性、可靠性，降低線上線下bug率；并提升研發(fā)效率、降低溝通成本、降低延期率。是確保項目前端和后端開發(fā)順利進行的重要規(guī)約之一，定義了前端與后端交互的規(guī)則和標準。

2 數(shù)據(jù)傳輸約定

2.1 數(shù)據(jù)向后端傳遞，及在前端流轉(zhuǎn)

1.前端URL傳參：原則上只允許傳id參數(shù)，盡量不要在URL中傳入中文參數(shù)及有關(guān)狀態(tài)判斷參數(shù)。

2.數(shù)據(jù)提交：明確表單數(shù)據(jù)類型，包括是否必填校驗、multipart數(shù)據(jù)以及其他復(fù)雜類型數(shù)據(jù)。

3.參數(shù)規(guī)范：詳細描述接口所需的參數(shù)，包括參數(shù)名稱、類型、是否必填、默認值、示例等。

2.2 數(shù)據(jù)從后端返回到前端

1.正常數(shù)據(jù)格式：需定義單個數(shù)據(jù)、復(fù)雜數(shù)據(jù)、可能有的數(shù)據(jù)、無數(shù)據(jù)、分頁數(shù)據(jù)、校驗數(shù)據(jù)、特殊數(shù)據(jù)以及認證加密數(shù)據(jù)的格式。

2.異常數(shù)據(jù)格式：需包含異常狀態(tài)碼、異常名稱、數(shù)據(jù)格式、錯誤類型碼、異常發(fā)生位置以及異常描述，以便于前端正確處理和顯示錯誤信息。

3.性能要求：接口的響應(yīng)時間、并發(fā)處理能力、健壯性、穩(wěn)定性、故障恢復(fù)、安全性等性能指標。

【措施】

?腳手架統(tǒng)一，建項目等。

?錯誤碼標準：與http code對應(yīng)建立統(tǒng)一標準的code碼表示，標識錯誤碼內(nèi)容（規(guī)則，位數(shù)默認規(guī)則）和格式。

3 文檔溝通規(guī)范

前后端服務(wù)接口應(yīng)文檔化，確保接口與文檔先于前端開發(fā)，以便開發(fā)人員能夠準確理解和使用接口。文檔應(yīng)包含接口地址、請求方式、請求參數(shù)、返回結(jié)果等詳細信息；其中請求方式和返回結(jié)果需依據(jù)產(chǎn)品邏輯確定。

1.RESTful API設(shè)計風格：這是一種基于HTTP協(xié)議的API設(shè)計風格，通過使用HTTP動詞、URI和HTTP狀態(tài)碼來表示對資源的操作和請求結(jié)果，使接口設(shè)計更加簡潔明了。

2.URL規(guī)范：接口的URL結(jié)構(gòu)，包括基礎(chǔ)路徑、接口名以及參數(shù)傳遞方式（如查詢參數(shù)、表單數(shù)據(jù)、JSON格式的請求體等）。

3.接口版本控制：為了保證接口的兼容性和可維護性，必要時可對接口進行版本控制。可以在URI中加入版本號或使用請求參數(shù)來區(qū)分版本信息。

4.參數(shù)傳遞方式：明確參數(shù)的傳遞方式，包括GET、POST、PUT、DELETE等方式以及參數(shù)的格式（如JSON、表單等）。

5.返回結(jié)果格式：接口返回結(jié)果應(yīng)使用統(tǒng)一的格式，包括狀態(tài)碼、錯誤信息、數(shù)據(jù)等。建議使用JSON格式，以方便表示復(fù)雜的數(shù)據(jù)結(jié)構(gòu)。

【措施】

?接口文檔工具統(tǒng)一和推廣：可確定選用Japi或藏經(jīng)閣

4 架構(gòu)設(shè)計和數(shù)據(jù)結(jié)構(gòu)

4.1 前端規(guī)則

1.體驗優(yōu)先：盡可能優(yōu)化用戶體驗操作步驟，滿足產(chǎn)品要求，并及時提出交互建議。

2.SDK版本維護：多個系統(tǒng)調(diào)用前端地址或sdk時，需做好版本維護，特殊場景最好固定特殊版本，嚴格控制通用版本的升級。

3.防抖節(jié)流：前端請求防抖策略，函數(shù)節(jié)流策略。

4.代碼合并：代碼合并至main分支時，務(wù)必保證自己的代碼是基于main分支的最新提交拉取的代碼（可以先從main再拉出個hotfix分支，先和并至hotfix分支后，再合并至main分支）。

【措施】

?行云代碼合并檢測。

?加版本號，嚴格版本管理。

4.2 架構(gòu)方案設(shè)計

1.架構(gòu)設(shè)計和代碼實現(xiàn)解耦：架構(gòu)設(shè)計根據(jù)產(chǎn)品邏輯設(shè)計系統(tǒng)功能的架構(gòu)方案、數(shù)據(jù)傳輸交互、技術(shù)選型、邏輯方案；代碼實現(xiàn)則主要側(cè)重于具體程序編碼、規(guī)范、具體數(shù)據(jù)處理。

1.前端邏輯擴展性：前端設(shè)計依據(jù)產(chǎn)品交互邏輯，需考慮交互邏輯擴展性；數(shù)據(jù)處理中需注意深拷貝問題。

1.后端接口易用性：后端設(shè)計可根據(jù)自身要求定制，但給到前端接口的數(shù)據(jù)結(jié)構(gòu)需要依據(jù)產(chǎn)品業(yè)務(wù)邏輯。

2.前后端分離：提前約定數(shù)據(jù)結(jié)構(gòu)，并按數(shù)據(jù)結(jié)構(gòu)進行開發(fā)。

3.前端直接暴露公網(wǎng)的，要做好安全防范，防止XSS，CSRF等攻擊，涉及數(shù)據(jù)隱私、傳輸、攻擊的續(xù)作加密解密處理。后端接口則需做SSRF攻擊防范。

【措施】

?前后端耦合系統(tǒng)做分離（開發(fā)分離，發(fā)布分離）

?重點類型規(guī)則：金額、時間等重點核心數(shù)據(jù)枚舉類型。

4.3數(shù)據(jù)結(jié)構(gòu)設(shè)計

1.數(shù)據(jù)結(jié)構(gòu)恒定性：前后端約定好的字段和類型不應(yīng)輕易改動，若有改動需及時提前告知對方。

2.魯棒邊緣性設(shè)計：接口需考慮極端情況下的限定，定義必須清楚（如不同類型字段為空時，為null時，為無窮大時，為負時等）。

3.數(shù)據(jù)結(jié)構(gòu)簡潔：數(shù)據(jù)接口字段應(yīng)遵循盡明確，盡簡單，盡少量，盡少層，盡可能都用，可擴展。

4.數(shù)據(jù)類型一致性：前后端數(shù)據(jù)類型一致性。

5.【特別約定】：后端不能用int類型接受前端傳值（int默認值為0）；若用Int類型接收，則務(wù)必進行包裝處理異常。

4.4 安全與健壯

1.前后端接口數(shù)據(jù)校驗：重要數(shù)據(jù)傳輸（如費用資金等），后端須做接口兜底校驗，同時前端需要做邏輯校驗（甚至加解密機制）；還包括三方接口使用的兜底處理和預(yù)警。

2.請求頭約定：前后端應(yīng)約定請求頭，而不是只用系統(tǒng)默認（jdk不同版本接受數(shù)據(jù)的默認請求頭可能不一樣）。

3.接口一致性：同一功能的增加和修改等應(yīng)盡量為同一接口；若否，則需說明理由。

4.日志記錄：接口邏輯需要清晰必要的日志進行記錄，方便查詢。

5.接口防抖，冪等：必要時后端服務(wù)也需做防抖（如用戶點錯某一邏輯，又快速點擊另一邏輯等）。。

6.混沌實驗：必要時，需要做混沌工程實驗，演練最小化“爆炸半徑”。

4.5 DSL規(guī)約

根據(jù)對DSL（Domain Specific Language）的使用情況，選擇sdl規(guī)約的分級策略；即根據(jù)具體業(yè)務(wù)邏輯的復(fù)雜度來考慮遵循規(guī)約的量級。

?對于只展示不修改類場景，前端可直接做好dsl存給服務(wù)端即可。如cdp的圖狀邏輯展示。

?對于前后端都需要使用的dsl數(shù)據(jù)，盡可能把數(shù)據(jù)分成實體數(shù)據(jù)和展示數(shù)據(jù)兩部分，前后端需共同維護實體數(shù)據(jù)；尤其單線流程場景。如領(lǐng)航者的流程編排。

?對于前后端都需要用到的更復(fù)雜流程邏輯判斷類的產(chǎn)品，則需要維護dsl的不同版本。如摹略的畫布邏輯。

1.一套：前后端共同維護并解析使用同一套數(shù)據(jù)。兩部分：數(shù)據(jù)最好能區(qū)分前端自用字段和前后端公用字段。

2.約定好前端自用字段增加的規(guī)則和限制（長度等）。

3.共同約定公用字段的增減規(guī)則（類型和層級等）。

4.更復(fù)雜場景里，可用不同版本，或協(xié)議版本；也可以只存1部分數(shù)據(jù)，前后端分別解析，維護不同版本。

{ code:'',或數(shù)字約定 data:{}, msg:'' }

思路

5 實踐方式

新項目迭代

對于新項目可直接根據(jù)具體需求依照本規(guī)范執(zhí)行即可。執(zhí)行過程中可根據(jù)需求的實際情況得到具體產(chǎn)品線的細則。

老項目升級

1.對于老項目，前后端需經(jīng)過階段性自查，尤其針對這些可能直接影響系統(tǒng)穩(wěn)定性的核心條款，必須嚴格自查。

2.自查后，記錄系統(tǒng)存在的相應(yīng)隱患問題，再做出更新計劃，最好在接下來的迭代中就能完成；必要時，也可按Q或H維度計劃完成。

3.其他規(guī)約條款，盡可能的形成本系統(tǒng)的實際規(guī)范約定，前后端共同遵守，提高溝通效率，降低bug率。

6 總結(jié)

前后端數(shù)據(jù)傳輸約定是確保互聯(lián)網(wǎng)產(chǎn)品順暢運行的關(guān)鍵環(huán)節(jié)，它涉及到數(shù)據(jù)的格式、傳輸方式、安全性等多個方面。本文主要探討交互的具體環(huán)節(jié)。

總之，根據(jù)具體業(yè)務(wù)的不同，以及技術(shù)的不斷發(fā)展完善，我們還需要不斷在實踐中完善和改進這些規(guī)約，以適應(yīng)新的需求和挑戰(zhàn)。

歡迎兄弟們共同交流探討

審核編輯 黃宇