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 总结
前后端数据传输约定是保证互联网制品顺畅运行的关键环节，它触及到数据的格式、传输方式、安全性等多个方面。本文重点探讨交互的详细环节。
总之，按照详细业务的区别，以及技术的持续发展完善，咱们还需要持续在实践中完善和改进这些规约，以适应新的需要和挑战。
欢迎兄弟们一起交流探讨 | 
发表于 2024-10-10 03:59:56
