学习目标：

理解RESTful架构

运用Swagger编写API文档

掌握Mock.js基本语法

运用easyMock实现模拟接口的编写

1RESTful

1.1什么是RESTful架构

RESTful架构，就是目前最流行的一种互联网软件架构。它结构清晰、符合标准、易于理解、扩展方便，所以正得到越来越多网站的采用。REST这个词，是Roy Thomas Fielding在他2000年的博士论文中提出的

Fielding是一个非常重要的人，他是HTTP协议（1.0版和1.1版）的主要设计者、Apache服务器软件的作者之一、Apache基金会的第一任主席。所以，他的这篇论文一经 发表，就引起了关注，并且立即对互联网开发产生了深远的影响。

Fielding将他对互联网软件的架构原则，定名为REST，即Representational State Transfer的缩写。我对这个词组的翻译是"表现层状态转化"。如果一个架构符合REST原 则，就称它为RESTful架构。

1.2理解RESTful架构

要理解RESTful架构，最好的方法就是去理解Representational State Transfer这个词组到底是什么意思，它的每一个词代表了什么涵义。

（1）资源（Resources）

REST的名称"表现层状态转化"中，省略了主语。“表现层"其实指的是"资 源”（Resources）的"表现层"。

所谓"资源"，就是网络上的一个实体，或者说是网络上的一个具体信息。它可以是一段 文本、一张图片、一首歌曲、一种服务，总之就是一个具体的实在。你可以用一个 URI（统一资源定位符）指向它，每种资源对应一个特定的URI。要获取这个资源，访问它的URI就可以，因此URI就成了每一个资源的地址或独一无二的识别符。

所谓"上网"，就是与互联网上一系列的"资源"互动，调用它的URI。

（2）表现层（Representation）

“资源"是一种信息实体，它可以有多种外在表现形式。我们把"资源"具体呈现出来的形式，叫做它的"表现层”（Representation）。

比如，文本可以用txt格式表现，也可以用HTML格式、XML格式、JSON格式表现，甚至可以采用二进制格式；图片可以用JPG格式表现，也可以用PNG格式表现。

URI只代表资源的实体，不代表它的形式。严格地说，有些网址最后的".html"后缀名是不必要的，因为这个后缀名表示格式，属于"表现层"范畴，而URI应该只代表"资源"的位

置。它的具体表现形式，应该在HTTP请求的头信息中用Accept和Content-Type字段指定，这两个字段才是对"表现层"的描述。

（3）状态转化（State Transfer）

访问一个网站，就代表了客户端和服务器的一个互动过程。在这个过程中，势必涉及到 数据和状态的变化。

互联网通信协议HTTP协议，是一个无状态协议。这意味着，所有的状态都保存在服务器端。因此，如果客户端想要操作服务器，必须通过某种手段，让服务器端发生"状态转 化"（State Transfer）。而这种转化是建立在表现层之上的，所以就是"表现层状态转化"。

客户端用到的手段，只能是HTTP协议。具体来说，就是HTTP协议里面，四个表示操作方 式的动词：GET、POST、PUT、DELETE。它们分别对应四种基本操作：GET用来获取资源，POST用来新建资源（也可以用于更新资源），PUT用来更新资源，DELETE用来删除资源。

综合上面的解释，我们总结一下什么是RESTful架构：

（1）每一个URI代表一种资源；

（2）客户端和服务器之间，传递这种资源的某种表现层；

（3）客户端通过四个HTTP动词，对服务器端资源进行操作，实现"表现层状态转化"。

1.3常见错误

（1）URI包含动词

POST /accounts/1/transfer/500/to/2

正确的写法是把动词transfer改成名词transaction

（2）URI包含版本

http://www.example.com/app/1.0/foo
http://www.example.com/app/1.1/foo
http://www.example.com/app/2.0/foo

因为不同的版本，可以理解成同一种资源的不同表现形式，所以应该采用同一个URI。版本号可以在HTTP请求头信息的Accept字段中进行区分

Accept: vnd.example‐com.foo+json; version=1.0
Accept: vnd.example‐com.foo+json; version=1.1
Accept: vnd.example‐com.foo+json; version=2.0

2运用Swagger编写API文档

2.1Swagger

2.1.1什么是Swagger

随着互联网技术的发展，现在的网站架构基本都由原来的后端渲染，变成了：前端渲染、先后端分离的形态，而且前端技术和后端技术在各自的道路上越走越远。

前端和后端的唯一联系，变成了API接口；API文档变成了前后端开发人员联系的纽

带，变得越来越重要，

就是一款让你更好的书写API文档的框架。

2.1.2SwaggerEditor安装与启动

（1）下 载 https://github.com/swagger-api/swagger- editor/releases/download/v2.10.4/swagger-editor.zip。我在资源中已经提供。

（2）解压swagger-editor,

（3）全局安装http-server(http-server是一个简单的零配置命令行http服务器)

npm install ‐g http‐server

（4）启动swagger-editor

http‐server swagger‐editor

（5）浏览器打开： http://localhost:8080

2.1.3语法规则

（1）固定字段

（2）字段类型与格式定义

2.2基础模块-城市API文档

2.2.1新增城市

编写新增城市的API , post提交城市实体

URL： /city

Method: post

编写后的文档内容如下：

代码如下：

swagger: '2.0' info:
version: "1.0.0" title: 基础模块‐城市API
basePath: /base
host: api.tensquare.com paths:
/city:
post:
summary: 新增城市 

parameters:
‐ name: "body" in: "body"
description: 城市实体类
required: true schema:
$ref: '#/definitions/City' responses:
200:
description: 成功
schema:
$ref: '#/definitions/ApiResponse'
definitions: City:
type: object properties:
id:
type: string description: "ID"
name:
type: string description: "名称"
ishot:
type: string description: 是否热门
ApiResponse: type: object properties:
flag:
type: boolean
description: 是否成功
code:
type: integer 
format: int32 d
escription: 返回码
message: type: string
description: 返回信息

2.2.2修改城市

URL： /city/{cityId}

Method: put

编写后的文档内容如下：

代码如下：

/city/{cityId}: put:
summary: 修改城市
parameters:
‐name: cityId in: path
description: 城市ID
required: true type: string
‐name: body in: body
description: 城市
schema:
$ref: '#/definitions/City' responses:
200:
description: 成功响应
schema:
$ref: '#/definitions/ApiResponse'

2.2.3删除城市

删除城市地址为/city/{cityId} ，与修改城市的地址相同，区别在于使用delete方法提交请求

代码如下： （/city/{cityId} 下增加delete）

delete:
summary: 根据ID删除d
escription: 返回是否成功
parameters:
‐ name: cityId in: path
description: 城市ID
required: true type: string
responses: '200':
description: 成功
schema:
$ref: '#/definitions/ApiResponse'

2.2.4根据ID查询城市

URL: /city/{cityId}

Method: get

返回的内容结构为： {flag:true,code:20000, message:“查询成功”,data: {} }

data属性返回的是city的实体类型、

代码实现如下：

（1）在definitions下定义城市对象的响应对象

ApiCityResponse: type: "object" properties:
code:
type: "integer" format: "int32"
flag:
type: "boolean" message:
type: "string" data:
$ref: '#/definitions/City'

（2）/city/{cityId} 下新增get方法API

get:
summary: 根据ID查询description: 返回一个城市parameters:
‐ name: cityId in: path
description: 城市ID
required: true type: string
responses: '200':
description: 操作成功
schema:
$ref: '#/definitions/ApiCityResponse'

2.2.5城市列表

URL: /city Method: get

返回的内容结构为： {flag:true,code:20000, message:“查询成功”,data:[{…},{…},{}]

}

data属性返回的是city的实体数组

实现步骤如下：

（1）在definitions下定义城市列表对象以及相应对象

CityList:
type: "array" items:
$ref: '#/definitions/City' ApiCityListResponse:
type: "object" properties:
code:
type: "integer" format: "int32"
flag:
type: "boolean" message:
type: "string" data:
$ref: '#/definitions/CityList'

（2）在/city增加get

get:
summary: " 城 市 全 部 列 表 " 
description: "返回城市全部列表" 
responses:
200:
description: "成功查询到数据" 
schema:
$ref: '#/definitions/ApiCityListResponse'

2.2.6根据条件查询城市列表

实现API效果如下:

代码如下：

/city/search: post:
summary: 城市列表(条件查询)
parameters:
‐ name: body in: body
description: 查询条件
required: true schema:
$ref: "#/definitions/City" 
responses:
200:
description: 查询成功
schema:
$ref: '#/definitions/ApiCityListResponse'

2.2.7城市分页列表

实现API效果如下：

实现如下：

（1）在definitions下定义城市分页列表响应对象

ApiCityPageResponse:
 type: "object" 
 properties:
code:
type: "integer" format: "int32"
flag:
type: "boolean" message:
type: "string" data:
properties: total:
type: "integer" format: "int32"
rows:
$ref: '#/definitions/CityList'

（2）新增节点

/city/search/{page}/{size}: post:
summary: 城市分页列表
parameters:
‐name: page in: path
description: 页码
required: true type: integer format: int32
‐name: size in: path
description: 页大小
required: true type: integer format: int32
‐name: body in: body
description: 查询条件
required: true schema:
$ref: "#/definitions/City" responses:
200:
description: 查询成功
schema:
$ref: '#/definitions/ApiCityPageResponse'

2.3批量生成API文档

我们使用《黑马程序员代码生成器》自动生成所有表的yml文档

自动生成的文档中类型均为string ，我们这里需要再对类型进行修改即可。步骤：

（1）执行建表脚本

（2）使用《黑马程序员代码生成器》生成脚本

2.4其它模块API

请学员参见本章的扩展文档来实现部分功能。

2.5SwaggerUI

SwaggerUI是用来展示Swagger文档的界面，以下为安装步骤

（1）在本地安装nginx

（2）下载SwaggerUI源码 https://swagger.io/download-swagger-ui/

（3）解压，将dist文件夹下的全部文件拷贝至 nginx的html目录

（4）启动nginx

（5）浏览器打开页面 http://localhost即可看到文档页面

（6）我们将编写好的yml文件也拷贝至nginx的html目录，这样我们就可以加载我们的

swagger文档了

3Mock.js

3.1什么是Mock.js

Mock.js （官网http://mockjs.com/）是一款模拟数据生成器，旨在帮助前端攻城师独立于后端进行开发，帮助编写单元测试。提供了以下模拟功能：

根据数据模板生成模拟数据

模拟 Ajax 请求，生成并返回模拟数据基于 HTML 模板生成模拟数据Mock.js具有以下特点：

前后端分离

让前端攻城师独立于后端进行开发。增加单元测试的真实性

通过随机数据，模拟各种场景。开发无侵入

不需要修改既有代码，就可以拦截 Ajax 请求，返回模拟的响应数据。用法简单

符合直觉的接口。

数据类型丰富

支持生成随机的文本、数字、布尔值、日期、邮箱、链接、图片、颜色等。方便扩展

支持支持扩展更多数据类型，支持自定义函数和正则。

3.2Mock.js安装

在命令提示符下用npm安装mockjs

cnpm install mockjs

3.3快速入门

需求：生成列表数据，数据条数为5条。显示效果如下：

{
"list": [
{
"id": 1,
"name": "测试"
},
{
"id": 1,
"name": "测试"
},
{
"id": 1,
"name": "测试"
},
{
"id": 1,
"name": "测试"
},
{
"id": 1,
"name": "测试"
}
]
}
 

新建demo1.js 代码如下

let Mock=require('mockjs') let data=Mock.mock({
'list|5':[
{
'id':1,
'name':'测试'
}
]
})
console.log(JSON.stringify(data,null,2 ))

执行node demo1命令查看运行效果。

我们在本例中产生了5条相同的数据，这些数据都是相同的，如果我们需要让这些数据是按照一定规律随机生成的，需要按照Mock.js的语法规范来定义。

Mock.js 的语法规范包括两部分：

1.数据模板定义规范（Data Template Definition，DTD）

2.数据占位符定义规范（Data Placeholder Definition，DPD）

3.4数据模板定义规范DTD

数据模板中的每个属性由 3 部分构成：属性名、生成规则、属性值

// 属性名\tname
// 生成规则 rule
// 属性值\tvalue 'name|rule': value
 

属性名 和 生成规则 之间用竖线 | 分隔。

生成规则 是可选的。

生成规则 有 7 种格式：

‘name|min-max’: value

‘name|count’: value

‘name|min-max.dmin-dmax’: value

‘name|min-max.dcount’: value

‘name|count.dmin-dmax’: value

‘name|count.dcount’: value

‘name|+step’: value

生成规则的含义需要依赖属性值的类型才能确定。

属性值 中可以含有 @占位符。

属性值 还指定了最终值的初始值和类型

3.4.1属性值是字符串

（1）‘name|count’: string

通过重复 string 生成一个字符串，重复次数等于 count

// 使用 Mock
let Mock = require('mockjs') let data = Mock.mock({
'list|5': [{
'id': 1, 

'name':'测试',
'phone|11':'1'
}]
})
// 输出结果
console.log(JSON.stringify(data,null,2))

（2）‘name|min-max’: string

通过重复 string 生成一个字符串，重复次数大于等于 min，小于等于 max

// 使用 Mock
let Mock = require('mockjs') let data = Mock.mock({
'list|5': [{
'id': 1,
'name|2‐4':'测试',
'phone|11':'1'
}]
})
// 输出结果
console.log(JSON.stringify(data,null,2))

3.4.2属性值是数字number

（1）‘name|+1’: number

属性值自动加 1，初始值为 number。

// 使用 Mock
let Mock = require('mockjs') 
let data = Mock.mock({
'list|5': [{
'id|+1': 1, 'name|2‐3':'测试',
'phone|11':'1'
}]
})
// 输出结果
console.log(JSON.stringify(data,null,2))

（2）‘name|min-max’: number

生成一个大于等于 min、小于等于 max 的整数，属性值 number 只是用来确定类型

// 使用 Mock
let Mock = require('mockjs')
 let data = Mock.mock({
'list|5': [{
'id|+1': 1, 'name|2‐3':'测试',
'phone|11':'1', 'point|122‐500':0
}]
})
// 输出结果
console.log(JSON.stringify(data,null,2))

（3）‘name|min-max.dcount’: value生成一个浮点数，整数部分大于等于 min、小于等于 max，小数部分为dcount位

// 使用 Mock
let Mock = require('mockjs') 
let data = Mock.mock({
'list|5': [{
'id|+1': 1, 'name|2‐3':'测试',
'phone|11':'1', 'point|122‐500':0, 'money|3000‐8000.2':0
}]
})
// 输出结果
console.log(JSON.stringify(data,null,2))

（4）‘name|min-max.dmin-dmax’: number

生成一个浮点数，整数部分大于等于 min、小于等于 max，小数部分保留 dmin 到dmax 位。

// 使用 Mock
let Mock = require('mockjs')
 let data = Mock.mock({
'list|5': [{
'id|+1': 1, 'name|2‐3':'测试', 

'phone|11':'1', 'point|122‐500':0, 'money|3000‐8000.2':0, 'money2|1000‐5000.2‐4':0,
}]
})
// 输出结果
console.log(JSON.stringify(data,null,2))

3.4.3属性值是布尔

（1）‘name|1’: boolean

随机生成一个布尔值，值为 true 的概率是 1/2，值为 false 的概率同样是 1/2

// 使用 Mock
let Mock = require('mockjs')
 let data = Mock.mock({
'list|5': [{
'id|+1': 1, 'name|2‐3':'测试',
'phone|11':'1', 'point|122‐500':0, 'money|3000‐8000.2':0, 'status|1':true
}]
})
// 输出结果
console.log(JSON.stringify(data,null,2))

（2）‘name|min-max’: value

随机生成一个布尔值，值为 value 的概率是 min / (min + max)

// 使用 Mock
let Mock = require('mockjs')
 let data = Mock.mock({
'list|5': [{
'id|+1': 1, 'name|2‐3':'测试',
'phone|11':'1', 'point|122‐500':0, 'money|3000‐8000.2':0, 'status|1':true, 'default|1‐3':true
}]
})
// 输出结果
console.log(JSON.stringify(data,null,2))

3.4.4属性值是Object

（1）‘name|count’: object

从属性值 object 中随机选取 count 个属性。

// 使用 Mock
let Mock = require('mockjs')
 let data = Mock.mock({
'list|5': [{
'id|+1': 1, 'name|2‐3':'测试',
'phone|11':'1', 'point|122‐500':0, 'money|3000‐8000.2':0, 'status|1':true, 'default|1‐3':true,
'detail|2':{'id':1,'date':'2005‐01‐01','content':'记录'}
}]
})
// 输出结果
console.log(JSON.stringify(data,null,2))

（2）‘name|min-max’: object

从属性值 object 中随机选取 min 到 max 个属性

// 使用 Mock
let Mock = require('mockjs') 
let data = Mock.mock({
'list|5': [{
'id|+1': 1, 'name|2‐3':'测试',
'phone|11':'1', 'point|122‐500':0, 'money|3000‐8000.2':0, 'status|1':true, 'default|1‐3':true,
'detail|2‐3':{'id':1,'date':'2005‐01‐01','content':'记录'}
}]
})
// 输出结果
console.log(JSON.stringify(data,null,2))

3.4.5属性值是数组

（1）‘name|count’: array

通过重复属性值 array 生成一个新数组，重复次数为 count

（2）‘name|min-max’: array

通过重复属性值 array 生成一个新数组，重复次数大于等于 min，小于等于 max。

// 使用 Mock
let Mock = require('mockjs') 
let data = Mock.mock({
'list|5‐10': [{
'id|+1': 1, 'name|2‐3':'测试',
'phone|11':'1', 'point|122‐500':0, 'money|3000‐8000.2':0, 'status|1':true, 'default|1‐3':true,
'detail|2‐3':{'id':1,'date':'2005‐01‐01','content':'记录'}
}]
})
// 输出结果
console.log(JSON.stringify(data,null,2))

3.5数据占位符定义规范DPD

Mock.Random 是一个工具类，用于生成各种随机数据。

Mock.Random 的方法在数据模板中称为『占位符』，书写格式为 @占位符(参数 [, 参数]) 。

内置方法列表：

下面我们讲解每种内置方法的使用：

3.5.1基本方法

可以生成随机的基本数据类型

string 字符串integer 整数date 日期

// 使用 Mock
let Mock = require('mockjs')
 let data = Mock.mock({
'list|10': [{
'id|+1': 1, 'name':'@string',
'point':'@integer', 'birthday':'@date'
}]
})
// 输出结果
console.log(JSON.stringify(data,null,2))

3.5.2图像方法

image 随机生成图片地址

// 使用 Mock
let Mock = require('mockjs') 
let data = Mock.mock({
'list|10': [{
'id|+1': 1, 'name':'@string',
'point':'@integer',
'birthday':'@date',
'pic':'@image'
}]
})
// 输出结果
console.log(JSON.stringify(data,null,2))

3.5.3文本方法

@title: 标题

@cword(100) :文本内容 参数为字数

// 使用 Mock
let Mock = require('mockjs')
 let data = Mock.mock({
'list|10': [{
'id|+1': 1, 'name':'@string',
'point':'@integer',
'birthday':'@date',
'pic':'@image',
'title':'@title',
'content':'@cword(100)'
}]
})
// 输出结果
console.log(JSON.stringify(data,null,2))

3.5.4名称方法

cname :中文名称

cfirst:中文姓氏

Last:英文姓氏

// 使用 Mock
let Mock = require('mockjs') let data = Mock.mock({
'list|10': [{
// 属性 id 是一个自增数，起始值为 1，每次增 1 'id|+1': 1,
'name':'@cname',
'ename':'@last',
'cfirst':'@cfirst',
'point':'@integer',
'birthday':'@date',
'pic':'@image',
'title':'@title', 

'content':'@cword(100)'
}]
})
// 输出结果
console.log(JSON.stringify(data,null,2))

3.5.5网络方法

可以生成url ip email等网络相关信息

// 使用 Mock
let Mock = require('mockjs') 
let data = Mock.mock({
'list|10': [{
'id|+1': 1, 'name':'@cname',
'ename':'@last',
'cfirst':'@cfirst',
'point':'@integer',
'birthday':'@date',
'pic':'@image',
'title':'@title',
'content':'@cword(100)',
'url':"@url",
'ip':"@ip",
'email':"@email"
}]
})
// 输出结果
console.log(JSON.stringify(data,null,2))

3.5.6地址方法

@region 区域

@county 省市县

// 使用 Mock
let Mock = require('mockjs') 
let data = Mock.mock({
'list|10': [{
'id|+1': 1, 'name':'@cname', 

'ename':'@last',
'cfirst':'@cfirst',
'point':'@integer',
'birthday':'@date',
'pic':'@image',
'title':'@title',
'content':'@cword(100)',
'url':"@url",
'ip':"@ip",
'email':"@email",
'area':'@region', 'address':'@county(true)'
}]
})
// 输出结果
console.log(JSON.stringify(data,null,2))

4EasyMock

4.1什么是EasyMock

Easy Mock 是杭州大搜车无线团队出品的一个极其简单、高效、可视化、并且能快

速生成模拟数据的 的管理 Mock 数据。

。以项目管理的方式组织 Mock List，能帮助我们更好

地址：https://www.easy-mock.com

在线文档：https://www.easy-mock.com/docs

4.2EasyMock基本入门

4.2.1初始设置

（1）登录或注册。

浏览器打开https://www.easy-mock.com 输出用户名和密码，如果不存在会自动注册。注意：请牢记密码，系统没有找回密码功能！

登录后进入主界面

（2）创建项目：点击右下角的加号

填写项目名称，点击创建按钮

创建完成后可以在列表中看到刚刚创建的项目

4.2.2接口操作

（1）创建接口。点击列表中的项目

进入项目工作台页面

点击“创建接口” ,左侧区域输出mock数据，右侧定义Method 、 Url 、描述等信息。

我们可以将我们在Mock.js入门案例中的对象放入左侧的编辑窗口

{
'list|10': [{
"id|+1": 1, "name": "@cname",
"cfirst": "@cfirst",
"Last": "@Last",
"point": "@integer",
"birthday": "@date",
"pic": "@image", 

"content": "@cword(30,200)", "url": "@url",
"ip": "@ip",
"email": "@email",
"region": "@region", "county": "@county"
}]
}

填写url Method 和描述 ，点击创建按钮

（2）克隆接口和修改接口

（3）预览接口和复制接口地址

（4）删除接口

4.3本地部署EasyMock

4.3.1Centos部署node.js

（1）将node官网下载的node-v8.11.1-linux-x64.tar.xz 上传至服务器

（2）解压xz文件

xz ‐d node‐v8.11.1‐linux‐x64.tar.xz

（3）解压tar文件

tar ‐xvf node‐v8.11.1‐linux‐x64.tar

（4）目录重命名

mv node‐v8.11.1‐linux‐x64 node

（5）移动目录到/usr/local下

mv node /usr/local/

（6）配置环境变量

vi /etc/profile

填写以下内容

#set for nodejs
export NODE_HOME=/usr/local/node
 export PATH=$NODE_HOME/bin:$PATH

执行命令让环境变量生效

source /etc/profile

查看node版本看是否安装成功

node ‐v

4.3.2MongoDB安装与启动

我们使用yum方式安装mongoDb

（1）配置yum

vi /etc/yum.repos.d/mongodb‐org‐3.2.repo

[mongodb‐org‐3.2] name=MongoDB Repository
baseurl=https://repo.mongodb.org/yum/redhat/$releasever/mongodb‐ org/3.2/x86_64/
gpgcheck=1 enabled=1
gpgkey=https://www.mongodb.org/static/pgp/server‐3.2.asc

（2）安装MongoDB

yum install ‐y mongodb‐org

（3）启动MongoD

systemctl start mongod

4.3.3Redis安装与启动

（1）下载fedora的epel仓库

yum install epel‐release

（2）下载安装redis

yum install redis

（3）启动redis服务

systemctl start redis

4.3.4本地部署easy-mock

（1）项目下载地址： https://github.com/easy-mock/easy-mock

（2）将easy-mock-dev.zip上传至服务器

（3）安装zip 和unzip

yum install zip unzip

（4）解压

unzip easy‐mock‐dev.zip

（3）进入其目录，安装依赖

npm install

（4）执行构建

npm run build

（5）启动

npm run start

6）打开浏览器 http://192.168.184.131:7300

4.4导入SwaggerAPI文档

（1）将我们的SwaggerAPI文档扩展名改为yml

（2）在easyMock中点击“设置”选项卡

（3）SwaggerDocs API 选择Upload

（4）将SwaggerAPI文档拖动到上图的虚线区域，点击保存

（5）回到主界面后点击“同步Swagger”