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 对象，它的结构一般如下所示：

  1. {
  2.     "id": "[number]",
  3.     "name": "[string]",
  4.     "email": "[string]"
  5. }

其中，中括号里面的值表示该字段的类型。

创建了 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 的数据模型，它的结构如下所示：

  1. {
  2.     "code": "[number]",
  3.     "msg": "[string]",
  4.     "result": "[Variable]"
  5. }

code 是请求返回的状态码，msg 是返回的信息（比如一些异常信息），result 是真正的数据部分，定义数据模型的时候它是可变的。

然后点击 导入 按钮，选择 ResultData，然后再选择 result 的具体类型，比如它是一个数组，数组的每一项都是一个 User 对象。

发送规则：在发送数据之前，对数据进行一些特殊处理，比如对密码进行加密等

接收规则：在服务器返回数据后，对数据进行一些特殊处理，比如将树形结构的数据打平等操作

页面模板

模板就是服务端的模板。一般模板里面会有很多变量需要使用真实数据来替换，在创建模板时，数据 选项一栏指的就是这些真实的数据。数据一般就对应服务端的 Model，通过 Controller 提供给模板。

规则函数

顾名思义，它们都是函数。在创建数据模型的属性或者异步接口的参数时，可以指定它们的生成规则，如果它们没有默认值，则会调用生成规则函数并将它的返回值作为最终的 mock 数据。

注意,虽然数据模型的生成规则、异步接口的发送和接收规则都可以编写 JavaScript 脚本，但我们还是建议它们都是调用规则函数的代码，以达到复用的目的，管理和维护也更加方便

业务分组

业务分组可以用来更好地组织资源，它是唯一的。

业务分组和标签有所不同，例如，资源可以有多个标签，但只能属于一个分组

工程规范

请查看 NEI 工程规范介绍