1 目的

穩定可靠，降本增效

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

2 數據傳輸約定

2.1 數據向后端傳遞，及在前端流轉

1.前端URL傳參：原則上只允許傳id參數，盡量不要在URL中傳入中文參數及有關狀態判斷參數。

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

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

2.2 數據從后端返回到前端

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

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

3.性能要求：接口的響應時間、并發處理能力、健壯性、穩定性、故障恢復、安全性等性能指標。

【措施】

?腳手架統一，建項目等。

?錯誤碼標準：與http code對應建立統一標準的code碼表示，標識錯誤碼內容（規則，位數默認規則）和格式。

3 文檔溝通規范

前后端服務接口應文檔化，確保接口與文檔先于前端開發，以便開發人員能夠準確理解和使用接口。文檔應包含接口地址、請求方式、請求參數、返回結果等詳細信息；其中請求方式和返回結果需依據產品邏輯確定。

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

2.URL規范：接口的URL結構，包括基礎路徑、接口名以及參數傳遞方式（如查詢參數、表單數據、JSON格式的請求體等）。

3.接口版本控制：為了保證接口的兼容性和可維護性，必要時可對接口進行版本控制?？梢栽赨RI中加入版本號或使用請求參數來區分版本信息。

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

5.返回結果格式：接口返回結果應使用統一的格式，包括狀態碼、錯誤信息、數據等。建議使用JSON格式，以方便表示復雜的數據結構。

【措施】

?接口文檔工具統一和推廣：可確定選用Japi或藏經閣

4 架構設計和數據結構

4.1 前端規則

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

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

3.防抖節流：前端請求防抖策略，函數節流策略。

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

【措施】

?行云代碼合并檢測。

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

4.2 架構方案設計

1.架構設計和代碼實現解耦：架構設計根據產品邏輯設計系統功能的架構方案、數據傳輸交互、技術選型、邏輯方案；代碼實現則主要側重于具體程序編碼、規范、具體數據處理。

1.前端邏輯擴展性：前端設計依據產品交互邏輯，需考慮交互邏輯擴展性；數據處理中需注意深拷貝問題。

1.后端接口易用性：后端設計可根據自身要求定制，但給到前端接口的數據結構需要依據產品業務邏輯。

2.前后端分離：提前約定數據結構，并按數據結構進行開發。

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

【措施】

?前后端耦合系統做分離（開發分離，發布分離）

?重點類型規則：金額、時間等重點核心數據枚舉類型。

4.3數據結構設計

1.數據結構恒定性：前后端約定好的字段和類型不應輕易改動，若有改動需及時提前告知對方。

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

3.數據結構簡潔：數據接口字段應遵循盡明確，盡簡單，盡少量，盡少層，盡可能都用，可擴展。

4.數據類型一致性：前后端數據類型一致性。

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

4.4 安全與健壯

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

2.請求頭約定：前后端應約定請求頭，而不是只用系統默認（jdk不同版本接受數據的默認請求頭可能不一樣）。

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

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

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

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

4.5 DSL規約

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

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

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

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

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

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

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

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

{ code:'',或數字約定 data:{}, msg:'' }

思路

5 實踐方式

新項目迭代

對于新項目可直接根據具體需求依照本規范執行即可。執行過程中可根據需求的實際情況得到具體產品線的細則。

老項目升級

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

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

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

6 總結

前后端數據傳輸約定是確?；ヂ摼W產品順暢運行的關鍵環節，它涉及到數據的格式、傳輸方式、安全性等多個方面。本文主要探討交互的具體環節。

總之，根據具體業務的不同，以及技術的不斷發展完善，我們還需要不斷在實踐中完善和改進這些規約，以適應新的需求和挑戰。

歡迎兄弟們共同交流探討

審核編輯 黃宇