前端接口设计

前面的话

　　先后端开发要分离。可是，具体哪些地方须要约定呢？如何制定约定规则呢？制定后如何应用呢？本文将详细介绍这些问题相关的工程实践方法——接口设计

 

概述

　　在协做流程的博文中，咱们了解了一个Web系统的体系架构，以及前端与后端交互的整个流程，接下来简单回顾，并进行相应的规则约定

　　当客户端向服务器端发送一个请求时，服务器端的Web系统收到该请求，经过分析来进行一系列的操做，包括搜集全部的数据模型，一般这个过程会伴随有数据库操做；数据搜集完成后，Web系统根据请求信息，选择合适的模板来响应Web客户端

　　这时，问题来了，用户请求的地址须要经过什么样的约定规则映射到视图模板上呢？

　　Web系统选择了合适的模板以后，将搜集的数据模型按照必定的约定规则，交给模板引擎进行页面结构的组装

　　这时，问题又来了，不一样的模板须要经过什么样的约定规则与数据模型进行匹配呢？

　　有了视图模板和数据模型后，Web系统就能够组装出客户端所须要的页面结构，而后再将这个页面结构返回给客户端。客户端拿到返回的数据模型后，根据必定的规则绘制页面，同时展现给用户

　　实际上，页面只包含了一部分数据，还有一部分数据须要经过另外的接口来载入。接下来，客户端根据一系列的约定规则发起数据请求

　　问题来了，一个页面须要包含哪些数据载入的请求呢？换句话说，一个页面中，哪些数据须要经过异步请求载入进来的呢？

　　Web系统收到数据请求以后，根据一系列的数据操做，筛选出约定的数据模型

　　最后的问题，一个数据请求须要什么样的约定规则来与数据模型进行匹配呢？

　　Web系统搜集到数据以后，按照约定规则组装出数据模型，返回给客户端。客户端将数据模型按照必定的结构展现给用户

　　在以上的交互流程中，咱们能够提取出4个关键的元素：URL、TEMPLATE、API、MODEL

　　URL：页面访问地址或者称为页面标识

　　Template：一个页面对应的分离了数据模型以后的页面结构，后续能够根据不一样的数据模型展示不一样的信息

　　API：页面用于载入数据的异步请求的接口

　　Model：数据模型(包含组装页面模板的模型和异步请求返回的数据模型)

　　若是要对先后端进行分离，须要进行如下一些规则约定

　　一、URL与模板的约定，约定了页面须要映射到哪些视图模板上去

　　二、URL与异步接口的约定，约定了页面有哪些数据是经过异步接口载入进来的

　　三、模板和数据模型的约定，约定了视图模板与什么样的数据模型相对应，以及数据模型的格式和类型等信息

　　四、异步接口和数据模型的约定，约定了异步接口的输入输出信息

　　页面入口规范用来处理URL与模板，及URL与接口之间的约定

　　同步数据规范用来处理模板和数据模型的约定

　　异步接口规范用来处理异步接口和数据模型的约定

 

接口规范

　　经过前面的内容，咱们大体地了解了页面入口规范、同步数据规范和异步接口规范这三个基础规范，其中每一个规范也会定义出若干规则约定来指导先后端工程师的具体实施

　　接下来，详细介绍每一个规范包含哪些约定规则，以及这些约定规则是如何制定的，以网易云音乐的下面这个页面为例进行说明

【页面入口规范】

　　页面入口规范首先要对页面进行说明，包含一些用来描述页面基本信息、URL携带参数说明、页面可能会用到的视图模板的对应关系、页面可能会发出的异步请求的异步载入数据的接口的详细信息。简而言之，能够总结为如下四点

一、基本信息
二、输入参数
三、模板列表
四、接口列表

　　下图是页面入口规范中，某个页面所定义的规则约定的范例

　　首先，前、后端工程师须要根据交互原型对系统进行页面拆分。页面拆分的原则主要根据先后端功能实现的方式(好比单页或多页)来权衡

　　基本信息包括访问地址和页面描述，访问地址能够不携带参数，页面描述说明了页面的用途或功能

　　输入参数主要用来讲明访问地址在请求时能够携带的参数，包括参数名称、参数类型和参数描述

　　异常跳转用于系统全局异常处理，该部分并非必须的

　　模板列表须要列举出当前页面涉及到的相关视图模板，其中必须包含一个默认的视图模板。若是正常显示和异常显示的页面差别较大值时，还须要包含异常模板，或其余模板

　　接口列表须要定义出页面用到的全部异步接口列表，要根据交互原型及后端数据的操做开销来进行权衡。通常来讲，对于SEO的要求较低，或页面的相关性不高，或者已经存在数据载入接口，或者数据收集时须要长时间的开销，能够考虑用异步的方式来载入数据。图片的接口列表包括歌曲列表、相关节目、收藏节目和评论列表

【同步数据规范】

　　同步数据规范包含用于对模板的详细说明的基本信息、对数据模型的说明(名称、类型等信息)，若是视图模板须要后端注入接口，也须要包含注入接口的信息。简而言之，能够总结为如下三点

一、基本信息
二、预填数据
三、注入接口

　　下图是同步数据规范中，某个模板所定义的规则约定的范例

　　首先，是模板基本信息部分，描述了模板文件的物理位置，及模板文件的功能等

　　预填数据的信息就是注入到模板中的数据模型，包括模板所用到的全部数据的详细信息，不只包含全局数据，也包含当前页面的数据模型。其中，对数据的说明要包含数据名称、数据类型和数据描述等信息。对于复杂的数据类型，还需展开介绍其内部的数据模型的结构

　　注入接口主要定义接口的输入输出信息，但注入接口并非每一个模板都必须的，大部分模板不须要注入接口

【异步接口规范】

　　异步接口规范包含如下三点

一、基本信息
二、输入数据
三、输出结果

　　下图是异步接口规范中，某个接口所定义的规则约定的范例

　　首先，异步接口基本信息部分，包括接口的请求方式、接口地址、接口描述等，图中的接口地址不须要携带查询参数

　　输入数据(REST和查询参数)须要包含数据名称、数据类型和数据描述等信息

　　输出结果(通用部分和结果集)主要定义的是返回给客户端的数据模型的结构，须要说明每一个字段的名称、类型和描述等信息。对于复杂的数据类型，还需展开介绍其内部的数据模型的结构

 

规范应用

　　在系统设计阶段，定制了三个规则约定规范。在进入开发阶段，前、后端工程师如何应用这些规范来完成系统中的设计、开发、测试等工做呢？

　　一、根据页面入口规范来构建项目结构

　　页面入口规范定义了每一个页面对应的模板文件，能够导出配置信息，而后构建项目的目录结构(包含前端的目录结构和后端的模板结构)

　　根据配置文件生成目录的过程可使用自动化工具来完成

　　二、根据同步数据规范模拟同步数据

　　同步数据规范定义了每一个模板定义的同步数据信息，能够导出模拟数据的配置文件，而后生成同步的模拟数据的文件

　　根据配置文件生成模拟数据的过程可使用自动化工具来完成

　　三、根据异步接口规范模拟异步数据

　　异步接口规范定义了每一个接口的输入输出，能够导出接口与返回结果的模拟数据的匹配的配置信息，而后生成接口对应的模拟数据的文件

　　根据配置文件生成模拟数据的过程可使用自动化工具来完成

　　在本地开发时，经过模拟数据的形式将前端相关的内容与后端独立出来，接下来前端工程师就能够独立开发

 

本地开发

　　进入开发阶段，通常要怎样来搭建前端开发环境呢？前端开发环境主要包含两部分：一部分是本地模拟服务器、另外一部分是本地代理

　　客户端发出的请求首先会被本地模拟服务器拦截，本地模拟服务器根据必定的配置规则，直接将请求返回给Web客户端。若是页面存在某些数据须要异步载入，这个请求会被本地代理拦截，本地代理根据模拟数据的映射规则，直接将生成的模拟数据返回给Web客户端

　　前端本地开发环境搭建完成以后，全部的客户端与服务器端的交互都会被本地模拟服务器或本地代理拦截，这样就将先后端开发作了完全的分离

【本地模拟服务器】

　　本地环境中的本地模拟服务器在接收到Web客户端发来的请求时，首先会根据处理规则进行匹配，若是匹配，则请求被拦截

　　根据规范导出的配置信息一样会被本地模拟服务器所使用。经过配置信息，本地模拟服务器能够识别出这些请求所对应的模板文件和模拟数据所在的位置，从而整合模板文件和模拟数据，生成一个HTML页面结构代码，返回给Web客户端

【本地代理】

　　本地环境中的本地代理在接收到Web客户端发来的异步请求时，会拦截该请求。根据规范导出的配置信息一样会被本地代理所使用，经过配置信息，本地代理找出请求对应的模拟数据，把数据转换成JSON数据格式或其余定义好的数据格式，返回给Web客户端

　　若是请求未匹配，则该异步请求可能会访问远程服务器

【联调】

　　经过本地环境的搭建独立了先后端开发的过程。先后端开发工做完成以后，须要进行联调

　　先后端联调须要去除本地环境，这时Web客户端发出的请求就能够顺利到达服务器端

　　在实际开发中只须要对配置文件进行调整既可，以控制哪些请求须要被本地服务器或代理拦截，哪些须要使用远程服务器

 

最后

　　本文是蔡剑飞、郑海波老师的《产品前端架构》课程中《接口设计》章节的学习记录