接口管理平台(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 项目本身来说,它有 User
、UserGroup
、Project
、ProjectGroup
、Page
、Parameter
等等可以抽象出来的对象。这些对象和程序的编写以及数据的持久化都是息息相关的。创建数据类型的时候,可以指定字段的默认值,默认值的优先级会高于 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
, boolean
和 null
) 和 2 种结构化类型 (object
和 array
)。除了 null
之外,其他类型 NEI 都支持。可以点击 修改类型
按钮更改输入参数
的类型。
注意,如果想修改为
array
类型,则需事先定义一个数组
类型的数据类型。
输出参数
即异步接口返回的数据,格式同 输入参数
。
一般我们希望输出参数具有某种固定格式,这样客户端就可以统一处理一些逻辑,比如 404
、500
等异常。比如,可以先定义一个叫 ResultData
的数据类型,它的结构如下所示:
{
"code": "[number]",
"msg": "[string]",
"result": "[Variable]"
}
code
是请求返回的状态码,msg
是返回的信息(比如一些异常信息),result
是真正的数据部分,定义数据类型的时候它是可变
的。
然后点击 导入
按钮,选择 ResultData
,然后再选择 result
的具体类型,比如它是一个数组,数组的每一项都是一个 User
对象。
模板
就是服务端的模板。一般模板里面会有很多变量需要使用真实数据来替换,在创建模板时,数据
选项一栏指的就是这些真实的数据。数据一般就对应服务端的 Model
,通过 Controller
提供给模板。
API 接口
是系统(应用程序、模块、组件等)对外暴露的公开方法。
比如使用 Node.js 中 path
模块的 extname
方法时,我们会去查看它的 API 文档,需要知道传入参数的类型以及返回值是什么。
因此在创建 API 接口时,一般需要指定它的参数和返回值等信息。