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 总结

前后端数据传输约定是确保互联网产品顺畅运行的关键环节，它涉及到数据的格式、传输方式、安全性等多个方面。本文主要探讨交互的具体环节。

总之，根据具体业务的不同，以及技术的不断发展完善，我们还需要不断在实践中完善和改进这些规约，以适应新的需求和挑战。

欢迎兄弟们共同交流探讨👏🏻