接口( API )设计
API( Application Programming Interface,应用程序编程接口 ),俗称:接口。
接口设计,在前后端分离的开发模式中,可以这样理解:
在熟悉 web 系统的体系架构和前后端交互流程的情况下,对前后端协作流程进行相应的规则约定的工程实践方法。
规则约定
首先,具体哪些地方( 规则 )需要进行约定呢?
让我们回顾( 熟悉 )一下,web 系统的体系结构以及前后端交互的整个流程:
客户端向服务器端发送一个请求,服务器端 web 系统收到请求后,通过分析来进行一系列操作,包括收集所有的数据模型( 通常会伴随数据库的操作 ),数据收集完成后,web 系统根据请求信息,选择合适的模板来相应客户端。
- 用户的请求地址通过什么样的约束规则,映射到视图模板上呢?
- 有了合适的视图模板后,web 系统需要将收集的数据模型,交给视图模版进行页面结构的组装
- 不同的视图模板,通过什么样的约束规则,与数据模型进行匹配呢?
- 有了视图模板和数据类型后,web 系统可以组装出客户端所需要的页面结构并返回给客户端;
- 实际上,页面上可能只包含一部分数据,还有一部分数据,需要通过另外的接口( 异步请求 )来载入
- 一个页面中,哪些数据是需要通过异步请求的方式载入的呢?
- 一个数据请求,又需要什么样的约束规则与数据模型进行匹配呢?
- 收集到异步数据后,web 系统按照约定规则组装出数据模型,并返回给客户端( 按一定结构展现给用户 )
在上述的前后端交互流程中,可以提取出以下 4 个关键元素:
- URL:页面访问的地址
- Template:一个页面对应的分离了数据模型之后的页面模板,后续可以根据不同的数据模型展示不同的信息
- API:页面用于载入数据的异步请求的接口
- Model:数据模型,可以细分为:
- 组装页面结构的数据模型
- 异步请求返回的数据模型
So,在前后端分离的开发模式中,为了便于前后端更好的协调,通常需要对这 4 个关键元素分别进行约定:
- 页面入口
- URL - Template:约定 URL( 页面 )要映射到哪些 Template( 页面模板 )上去
- 同步数据
- Template - Model:约定 Template( 页面模板 )与什么样的 Model( 组装页面结构的数据模型 )相对应;以及数据模型的格式、类型等信息
- 异步接口
- URL - API:约定 URL( 页面 )中哪些数据是需要通过 API( 异步接口 )载入进来的
- API - Model:约定了 API( 异步接口 )的输入输入信息( Model,数据模型 )
接口规范
其次,如何制定约定规则呢?
在系统设计阶段,通过定制页面入口规范、同步数据规范和异步接口规范可以有效的指导前后端工程师后续的具体实施:
[1] 页面入口规范
前后端工程师,需要根据交互原型对页面进行拆分( 主要是根据前后端功能的实现方式,如单页 / 多页来权衡 )。
- 基本信息( 对页面进行说明 )
- 访问地址:可以不携带参数
- 页面描述:描述了页面的功能或用途
- 输入参数:用于说明页面访问地址( URL )在请求时可以携带的参数,包括参数名称、参数类型和参数描述
- 异常跳转:用于系统全局异常的处理,这部分不是必须的
- 模板列表:需要列出当前页面涉及到的相关视图模板,其中,必须包含一个默认的视图模板。
如果正常显示和异常显示的差异较大时,还需要包含异常模版或其他模板
- 接口列表:需要定义出页面用到的所有接口列表,要根据交互原型以及后端数据的操作开销来进行权衡。
一般来说,对于 SEO 的要求较低,或页面的相关性不高,或已经存在数据载入接口,或数据收集时需要长时间的开销,可以考虑用异步的方式来载入数据。
[2] 同步数据规范
- 模板基本信息
- 模板文件:模板文件的物理位置
- 模板描述:模板文件的描述信息
- 预填数据:注入到模板中的数据模型。
包括模板所用到的所有数据的详细信息,不仅包括全局数据,也包含当前页面的数据模型;
其中,对数据的说明,需要包含数据名称、数据类型和数据描述等信息
对于复杂的数据类型,还需要展开介绍其内部的数据模型的结构
- 注入接口:主要定义接口的输入输出信息,但注入接口并不是每个模板都必须的( 大部分模板不需要注入接口 )
[3] 异步接口规范
- 接口基本信息
- 接口的请求方式
- 接口地址
- 接口描述
- 输入数据( REST 和查询参数 ):需要包含数据名称、数据类型和数据描述等
- 输出结果( 通用部分和结果集 ):主要定义的是返回给客户端的数据模型的结构
需要说明每个字段的名称、类型和描述等
对于复杂的数据类型,还需要展开介绍其内部的数据模型的接口
规范应用
最后,制定了约定规则之后,如何使用呢?
「 接口管理平台 」进入开发阶段,前后端工程师如何应用这些规范来完成系统的设计、开发及测试等工作呢 ?
[1] 根据页面入口规范,来构建项目结构
页面入口规范,定义了每个页面对应的模板文件,可以导出配置信息,用来构建项目目录结构,
包括:前端的目录结构和后端的模板文件。
根据配置文件生成目录的过程,可以使用自动化工具来完成:
[2] 根据同步数据规范,模拟同步数据
同步数据规范,定义了每个模板的同步数据信息,可以导出模拟数据的配置文件,然后生成同步模拟数据的文件。
根据配置文件生成模拟数据的过程,可以使用自动化工具来完成:
[3] 根据异步接口规范,模拟异步数据
异步接口规范,定义了每个接口的输入输出,可以导出接口与返回结果的模拟数据相匹配的配置信息,
然后生成接口对应的模拟数据的配置文件。
根据配置文件生成模拟数据的过程,可以使用自动化工具来完成: