一、背景介绍
前后端分离是目前主流的开发模式，在分工上，前端负责数据展示和用户交互，而后端更关注于数据处理和数据存储。两者之间通过HTTP API进行数据交互，在写代码之前双方需要约定好交互时序和接口定义，包括请求方式、报文格式、接口字段、错误码等等。我们把实际开发中遇到的问题记录下来，进行归纳总结并形成前后端协作规范，希望能进一步提升前后端协作效率。
二、开发流程规范
为了保证项目能够顺利推进，每个公司都有一套成熟的开发流程，一般包括需求分析、方案设计和编码实现。
- 需求分析阶段，首先是产品做需求澄清，然后由开发评估可行性。前端需要重点关注产品的用户体验（用户交互是否合理？会不会存在性能隐患？），开发依赖项（客户端API是否支持？UI资源什么时候就位？）。
- 方案设计阶段，这是前后端协作的重要环节。双方需要约定前后端交互时序和接口定义。
- 编码实现阶段，前端根据UI开发页面样式和交互逻辑，可通过mock模拟HTTP API获取数据，等后端接口就位之后进行前后联通。
三、前后端接口规范
在编码之前，前后端需要对接口定义达成一致，一般要考虑以下内容：
- 画出前后端交互时序图，梳理出所有接口信息。
- HTTP通信基础信息：加解密方式、报文结构。
- 接口基本信息：请求方法、路径、入参/出参。
- 接口补充信息：字段是否必填、是否为null、枚举值。
- 字段命名要统一，建议使用领域词汇，保持前后端一致。
- 重要逻辑和复杂逻辑不要放在前端处理。
- 前端不要直接对接第三方系统。
- 文档更新时要及时通知对方。
请求
- 请求方法：查询使用get，修改使用post。
- post接口统一用body传参，报文格式为application/json。
响应
- 约定好错误码和错误信息。
- 响应字段要与当前页面匹配，不要为了复用接口而返回无用字段。
- 响应数据为空时，不要直接返回null，而是有意义数据，例如空数组[]、空字符串""等。
- 响应信息要对用户友好，不要直接返回系统信息，例如：”服务器内部异常"、"数据库异常：xxx”。
四、典型错误示例
类型一：复杂逻辑放在前端处理
发现问题：前端根据用户角色和场景判断按钮是否展示。当判断逻辑有变更时，需要保证前后端逻辑一致，不方便维护。
{((user.role === 'admin') ||(user.role === 'reviewer' && record.state === 'submit')) &&
<Button>确认</Button>}
{((user.role === 'operator' && record.state !== 'submit')) &&
<Button>修改</Button>}
解决方法：把判断逻辑放到后端并返回一个是否展示的字段给前端，前端根据该字段进行展示。
[
{ name:'确认'，isShow: true },
{ name:'修改'，isShow: false },
]
类型二：重要逻辑放在前端处理
发现问题：用户选择购物车商品，以前端计算的总金额下单。由于前端数据的不可靠性，并且计算过程没有日志记录，出现异常时无法追踪。
解决方法：前端计算的总金额仅作为展示用，实际下单金额由后台计算，最好把前端计算的金额也传到后台进行校验，保证一致性。
类型三：前端直接调用第三方系统
发现问题：页面展示的数据来源于第三方系统，由前端直接与第三方系统交互。首先，前端代码是在互联网客户端运行的，无法进行有效的加签验签，不安全；另外，前端与第三方系统的交互没有日志记录，无法追踪；最后，每个业务系统都有自己的接口规范，前端因此要处理多种接口报文格式，逻辑太复杂。
解决方法：由后端与第三方系统对接，并提供接口给前端调用。
总结
一套完善的前后端协作规范不仅可以降低沟通成本，还可以避免踩坑，从而大大地提升开发效率和代码质量。当然，这也是需要在开发过程中不断地沉淀，最终形成一套适合自己团队的协议规范。
