Skip to content

Latest commit

 

History

History
118 lines (65 loc) · 7.46 KB

nei.md

File metadata and controls

118 lines (65 loc) · 7.46 KB

NEI 简介

接口管理平台(Netease Easy Interface),简称 NEI

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)等。本地模拟容器 Puer 也会调用模板引擎来解析模板。

创建页面的时候,也可以填写多个模板,此时每个模板作为页面的某个状态,比如 成功失败 等状态,服务端根据业务逻辑返回相应的模板。Puer 通过参数配置也可以达到相应的效果。

页面接口

页面可以包含异步接口,和模板类似,异步接口是项目的资源,不属于页面。

资源库

在 NEI 中的项目,除了页面之外,其他的都是资源,可以说页面是由各种资源组成的。

一共有 4 种资源,分别是数据类型异步接口模板API,下面一一介绍。

数据类型

数据类型是 NEI 中最重要的概念之一,在使用 NEI 系统之前应该需要研究一下它的具体使用方法。在创建其他资源的时候,也要思考是不是可以将一些经常出现的输入或输出作为数据类型呢?

数据类型是基础资源,其他资源几乎都会用到。拿 NEI 项目本身来说,它有 UserUserGroupProjectProjectGroupPageParameter 等等可以抽象出来的对象。这些对象和程序的编写以及数据的持久化都是息息相关的。创建数据类型的时候,可以指定字段的默认值,默认值的优先级会高于 Mock 出来的随机数据。

比如 User 对象,它的结构一般如下所示:

{
  "id": "[number]",
  "name": "[string]",
  "email": "[string]"
}

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

创建了 User 数据类型后,整个系统就变得规范了,如果各个环节的代码都是严格按照 NEI 上的定义来实现的话,那么所有地方的 User 都是一致的,不会出现这里的 id 的类型和那里的不一致的情形,这固然有点理想主义,但也不是不能做到。这么做的好处是显而易见的,自动化测试方便了,甚至整个架构都可能更加严谨和正确了。

然后就可以在其他地方使用这个 User 对象。比如某个异步接口,输入参数是用户 id,要求返回的是 User 对象。接口开发者一看 NEI 上的定义就知道要返回什么样的数据,省去了很多沟通成本。

刚才说的 User 对象,在 NEI 中称为 哈希表,其实就是大家常说的 Map 对象。另外还有 2 种类型:枚举数组,也很好理解。

注意,在创建某个数据类型时,如果某个字段的类型是未知的,则选择 Variable 即可,表示可变类型,在具体使用的时候再指定它的类型。

数据类型 一般对应服务端的 Model

异步接口

异步接口大家都不陌生了,也是 NEI 用户最常使用的功能。

创建异步接口的时候,可以选择是否为 RESTful,选 的时候表示是数据按普通的 form 表单格式提交。在接口测试工具 Phosphorus 中,如果是 RESTful 接口,会将 Content-Type 的值设置为 application/json,否则它的值是 x-www-form-urlencoded

请求头 即在发送请求的时候添加到 Request Headers 中的参数。

输入参数即要发送的数据。NEI 默认的输入参数类型是一个 哈希表 对象。我们知道 JSON 可以表示 4 种基本类型 (string, number, booleannull) 和 2 种结构化类型 (objectarray)。除了 null 之外,其他类型 NEI 都支持。可以点击 修改类型 按钮更改输入参数的类型。

注意,如果想修改为 array 类型,则需事先定义一个 数组 类型的数据类型。

输出参数即异步接口返回的数据,格式同 输入参数

一般我们希望输出参数具有某种固定格式,这样客户端就可以统一处理一些逻辑,比如 404500 等异常。比如,可以先定义一个叫 ResultData 的数据类型,它的结构如下所示:

{
  "code": "[number]",
  "msg": "[string]",
  "result": "[Variable]"
}

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

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

模板

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

API 接口

API 接口是系统(应用程序、模块、组件等)对外暴露的公开方法。

比如使用 Node.js 中 path 模块的 extname 方法时,我们会去查看它的 API 文档,需要知道传入参数的类型以及返回值是什么。

因此在创建 API 接口时,一般需要指定它的参数和返回值等信息。