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.接口版本控制：為了保證接口的相容性和可維護性，必要時可對接口進行版本控制。可以在URI中加入版本号或使用請求參數來區分版本資訊。
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 總結
前後端資料傳輸約定是確定網際網路産品順暢運作的關鍵環節，它涉及到資料的格式、傳輸方式、安全性等多個方面。本文主要探讨互動的具體環節。
總之，根據具體業務的不同，以及技術的不斷發展完善，我們還需要不斷在實踐中完善和改進這些規約，以适應新的需求和挑戰。
歡迎兄弟們共同交流探讨