Permalink
ff4297f Nov 23, 2016
1 contributor

Users who have contributed to this file

145 lines (74 sloc) 7.14 KB

NEI 基本概念介绍

接口管理平台(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 工程规范介绍