接口管理平台(Netease Easy Interface),简称 NEI。
NEI 虽然叫接口管理平台,但其实不只是管理接口,它可以管理整个产品,也具备项目脚手架的功能。本文介绍 NEI 的设计理念和一些名词的含义。
一个产品可能有多个子产品,比如 PC 端、Android 端、iOS 端、后台管理系统等等。NEI 中有项目组的概念,在项目组中可以创建多个项目。所以,可以把项目组当作产品,其中的项目分别对应产品的各个子产品。
创建好项目组后,在项目组的“团队管理”选项卡中,可以把其他人加到项目组里面来。
注意: 人是加到项目组上的,而不是加在项目上。
页面,就是项目中的普通页面。下面介绍页面中的一些概念。
在创建页面的时候,可以指定页面的路径,比如 /index,那么它的访问地址是: {host}/index。
注意,在填写路径的时候,只要写相对地址即可,host 的值由环境决定,比如在本地开发时,它的值就是
http://127.0.0.1
。
页面参数指的是在访问页面时,传给服务端的参数,它可以通过 url 参数传入,此时页面的访问方式一般是 GET;也可以放在请求体中,此时页面的访问方式一般是 POST(比如页面作为 form 表单的提交地址)。
比如定义了参数 userId,它的类型是 string,这个时候页面的开发人员就知道,访问该页面的时候将会传入 userId 参数,即访问地址是:http://127.0.0.1?userId={userId}
,根据这个 userId 参数就可以做一些相应的业务逻辑了。
每张页面都至少有一个模板。模板是项目的资源,不属于页面。创建页面时填写的模板,只是声明页面会用到哪些模板资源。
模板一般需要模板引擎来解析生成最终的 html 内容,常见的模板引擎有 freemarker(模板扩展名是 .ftl)、velocity(模板扩展名是 .vm)、EJS(模板扩展名是 .ejs)等。
创建页面的时候,也可以填写多个模板,此时每个模板作为页面的某个状态,比如 成功、失败 等状态,服务端根据业务逻辑返回相应的模板。
页面可以包含异步接口,和模板类似,异步接口是项目的资源,不属于页面。
数据模型是 NEI 中最重要的概念之一,在使用 NEI 系统之前应该需要研究一下它的具体使用方法。在创建其他资源的时候,也要思考是不是可以将一些经常出现的输入或输出作为数据模型呢?
数据模型是基础资源,其他资源几乎都会用到。拿 NEI 项目本身来说,它有 User、UserGroup、Project、ProjectGroup、Page、Parameter 等等可以抽象出来的对象。这些对象和程序的编写以及数据的持久化都是息息相关的。创建数据模型的时候,可以指定字段的默认值,默认值的优先级会高于 Mock 出来的随机数据。也可以定义生成规则,根据自己的逻辑生成 Mock 数据。
比如 User 对象,它的结构一般如下所示:
{
"id": "[number]",
"name": "[string]",
"email": "[string]"
}
其中,中括号里面的值表示该字段的类型。
创建了 User 数据模型后,整个系统就变得规范了,如果各个环节的代码都是严格按照 NEI 上的定义来实现的话,那么所有地方的 User 都是一致的,不会出现这里的 id 的类型和那里的不一致的情形,这固然有点理想主义,但也不是不能做到。这么做的好处是显而易见的,自动化测试方便了,甚至整个系统都可能更加严谨和正确了。
然后就可以在其他地方使用这个 User 对象。比如某个异步接口,输入参数是用户 id,要求返回的是 User 对象。接口开发者一看 NEI 上的定义就知道要返回什么样的数据,省去了很多沟通成本。
刚才说的 User 对象,在 NEI 中称为哈希
类型,其实就是大家常说的 Map 对象。另外还有 6 种类型:枚举、数组、字符、数值、布尔、文件,也很好理解。
注意,在创建某个数据模型时,如果某个字段的类型是未知的,则选择 Variable 即可,表示可变类型,在具体使用的时候再指定它的类型。
数据模型 一般对应服务端的 Model。
异步接口大家都不陌生了,也是 NEI 用户最常使用的功能。
请求头即在发送请求的时候添加到 Request Headers 中的参数。
请求数据即要发送的数据。NEI 默认的输入参数类型是一个哈希对象。我们知道 JSON 可以表示 4 种基本类型 (string,number,boolean 和 null) 和 2 种结构化类型 (object 和 array)。除了 null 之外,其他类型 NEI 都支持。
响应头即服务器需要返回的头信息。
返回结果即异步接口返回的数据,格式同输入参数。
一般我们希望输出参数具有某种固定格式,这样客户端就可以统一处理一些逻辑,比如 404、500 等异常。比如,可以先定义一个叫 ResultData 的数据模型,它的结构如下所示:
{
"code": "[number]",
"msg": "[string]",
"result": "[Variable]"
}
code 是请求返回的状态码,msg 是返回的信息(比如一些异常信息),result 是真正的数据部分,定义数据模型的时候它是可变的。
然后点击 导入 按钮,选择 ResultData,然后再选择 result 的具体类型,比如它是一个数组,数组的每一项都是一个 User 对象。
发送规则:在发送数据之前,对数据进行一些特殊处理,比如对密码进行加密等
接收规则:在服务器返回数据后,对数据进行一些特殊处理,比如将树形结构的数据打平等操作
模板就是服务端的模板。一般模板里面会有很多变量需要使用真实数据来替换,在创建模板时,数据 选项一栏指的就是这些真实的数据。数据一般就对应服务端的 Model,通过 Controller 提供给模板。
顾名思义,它们都是函数。在创建数据模型的属性或者异步接口的参数时,可以指定它们的生成规则,如果它们没有默认值,则会调用生成规则函数并将它的返回值作为最终的 mock 数据。
注意,虽然数据模型的生成规则、异步接口的发送和接收规则都可以编写 JavaScript 脚本,但我们还是建议它们都是调用规则函数的代码,以达到复用的目的,管理和维护也更加方便
业务分组可以用来更好地组织资源,它是唯一的。
业务分组和标签有所不同,例如,资源可以有多个标签,但只能属于一个分组
请查看 NEI 工程规范介绍