前后端數(shù)據(jù)傳輸約定探討

1 目的

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

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

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ù)類型，包括是否必填校驗(yàn)、multipart數(shù)據(jù)以及其他復(fù)雜類型數(shù)據(jù)。

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

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

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

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

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

【措施】

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

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

3 文檔溝通規(guī)范

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

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

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

3.接口版本控制：為了保證接口的兼容性和可維護(hù)性，必要時(shí)可對(duì)接口進(jìn)行版本控制?？梢栽赨RI中加入版本號(hào)或使用請(qǐng)求參數(shù)來(lái)區(qū)分版本信息。

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

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

【措施】

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

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

4.1 前端規(guī)則

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

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

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

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

【措施】

?行云代碼合并檢測(cè)。

?加版本號(hào)，嚴(yán)格版本管理。

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

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

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

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

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

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

【措施】

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

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

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

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

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

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

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

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

4.4 安全與健壯

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

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

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

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

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

6.混沌實(shí)驗(yàn)：必要時(shí)，需要做混沌工程實(shí)驗(yàn)，演練最小化“爆炸半徑”。

4.5 DSL規(guī)約

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

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

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

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

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

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

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

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

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

思路

5 實(shí)踐方式

新項(xiàng)目迭代

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

老項(xiàng)目升級(jí)

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

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

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

6 總結(jié)

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

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

歡迎兄弟們共同交流探討

審核編輯 黃宇