前端是Web的一个细分领域，往往不能脱离后端而存在。所以和后端协作的时间是最长的.

10.1 协作流程规范

前后端团队经过长期的合作，一般可以总结出一条对于双方开发效率最优的协作流程. 将这个落实为规范，后面的团队成员都遵循这个步调进行协作。
一个典型的前后端协作流程如下:
前后端协作规范 - 图1



  1. 需求分析。参与者一般有前后端、测试、以及产品. 由产品主持，对需求进行宣贯，接受开发和测试的反馈，确保大家对需求有一致的认知
  2. 前后端开发讨论。讨论应用的一些开发设计，沟通技术点、难点、以及分工问题.
  3. 设计接口文档。可以由前后端一起设计；或者由后端设计、前端确认是否符合要求
  4. 并行开发。前后端并行开发，在这个阶段，前端可以先实现静态页面; 或者根据接口文档对接口进行Mock, 来模拟对接后端接口
  5. 在联调之前，要求后端做好接口测试
  6. 真实环境联调。前端将接口请求代理到后端服务，进行真实环境联调。

⬆️回到顶部

10.2 接口规范

首先应该确定下来的是接口规范。其实使用哪种接口标准是其次，重要的是统一，且要满足前后端的开发效率要求.
笔者不建议后端去定义自己的接口标准，而应该去选择一些通用的、有标准定义接口形式, 例如:

  • RESTful: RESTful是目前使用最为广泛的API设计规范, 基于HTTP本身的机制来实现.笔者个人是比较喜欢这个API规范，但是我发现很多开发者并不能真正(或者说没心思)理解它，设计出来的接口，跟我想象的相差甚远。换句话说，对于RESTful，开发者之间很难达成一致的理解，容易产生分歧。因为是使用最广泛的API形式，所以社区上有很多工具来对RESTful接口进行文档化、测试和模拟.
  • JSONRPC 这是一种非常简单、容易理解的接口规范。相对于RESTful我更推荐这个，简单则不容易产生分歧，新手也可以很快接受.
  • GraphQL 🔥更为先进、更有前景的API规范。但是你要说服后端配合你使用这种标准可能很有难度

接口设计需要注意的点:

  • 明确区分是正常还是异常, 严格遵循接口的异常原语. 上述接口形式都有明确的异常原语，比如JSONRPC，当出现异常时应该返回错误对象响应，而不是在正常的响应体中返回错误代码. 另外要规范化的错误码, HTTP响应码就是一个不错的学习对象
  • 明确数据类型。很多后端写的接口都是string和number不分的，如果妥协的话、前端就需要针对这个属性做特殊处理，这也可能是潜在的bug
  • 明确空值的意义。比如在做更新操作是，空值是表示重置，还是忽略更新？
  • 响应避免冗余的嵌套。
  • 接口版本化，保持向下兼容。就像我们上文的‘语义化版本规范’说的，对于后端来说，API就是公共的接口. 公共暴露的接口应该有一个版本号，来说明当前描述的接口做了什么变动，是否向下兼容。 现在前端代码可能会在客户端被缓存，例如小程序。如果后端做了break change，就会影响这部分用户。

⬆️回到顶部

10.3 接口文档规范

后端通过接口文档向前端暴露接口相关的信息。通常需要包含这些信息：

  • 版本号
  • 文档描述
  • 服务的入口. 例如基本路径
  • 测试服务器. 可选
  • 简单使用示例
  • 安全和认证
  • 具体接口定义
    • 方法名称或者URL
    • 方法描述
    • 请求参数及其描述，必须说明类型(数据类型、是否可选等)
    • 响应参数及其描述, 必须说明类型(数据类型、是否可选等)
    • 可能的异常情况、错误代码、以及描述
    • 请求示例，可选

人工维护导致的问题:
上文‘代码即文档’就提到了人工维护接口文档可能导致代码和文档不同步问题。
如果可以从代码或者规范文档(例如OpenAPI这类API描述规范)中生成接口文档，可以解决实现和文档不一致问题, 同时也可以减少文档编写和维护的投入.
⬆️回到顶部

10.4 接口测试与模拟

为了做到高效率的前后端并行开发，接口的测试与模拟是必要的。

  • 前端要求后端在联调之前，需要测试验证好自己的接口是否可以正常工作。而不是在联调期间，把前端当‘接口测试员’，阻塞接口联调进度
  • 另外前端需要在后端接口未准备好之前，通过接口模拟的方式，来编写业务逻辑代码。

针对接口测试与模拟，存在下图这样一个理想的模型:
前后端协作规范 - 图2
一切从定义良好的接口文档出发，生成Mock Server和Mock Client, Mock Server给前端提供模拟数据，而Mock Client则辅助后端对它们的接口进行测试.
资源: