Marmot
一个Java平台的Mock Server
模板引擎
- Velocity
- Freemarker
Install
Mac/Linux
$ sudo npm install -g marmot
Windows
windows中您需要在管理员模式下安装
$ npm install -g marmot
依赖环境
- Node.js 4.0+
- JDK 7+
Usage
init sub-command
进入项目目录下执行
$ marmot init
项目下如果存在
.marmotrc
配置文件,那么会根据文件中的配置进行初始化,如果不存在.marmotrc
配置文件,执行后会出现问答式的初始化设置,并会生成一个.marmotrc
配置文件。
marmot init
主要生成了项目的WEB-INF
目录所需要的jar包及模板引擎的配置。- 由于
WEB-INF
目录是根据.marmotrc
配置文件生成的,所以您在提交代码的时候,无需提交此目录。
参数:
-f, --force
强制初始化当前项目。
server sub-command
进入项目目录下执行
$ marmot server <command>
server 目前一共有五个命令,分别为:
- 启动应用
marmot server start
- 停止应用
marmot server stop
- 重启应用
marmot server restart
- 从应用列表中移除应用
marmot server remove
- 显示所有应用列表
marmot server list
接下来针对每个命令进行详细说明。
启动应用
$ marmot server start
参数:
-p, --port
应用端口
初次启动时如果没有指定端口号,则默认为 8080
,若指定了端口号则以指定的端口号启动。
当第二次启动的时候,如果没有指定端口号则默认为上次启动时使用的端口号。
示例
# 启动服务并指定端口为8090 $ marmot server start -p 8090
停止应用
$ marmot server stop
参数:
-p, --port
应用端口-i, --id
应用ID,该ID是由初次启动应用时生成的ID。可使用list
命令查看
示例
# 通过端口停止应用 $ marmot server stop -p 8090 # 通过id停止应用 $ marmot server stop -i 1
重启应用
$ marmot server restart
移除应用
$ marmot server remove
参数:
-p, --port
应用端口-i, --id
应用ID,该ID是由初次启动应用时生成的ID。可使用list
命令查看
remove
的别名为rm
注意:移除应用时,至少需要指定任意一个参数
示例
# 通过端口停止应用 $ marmot server rm -p 8090 # 通过ID停止应用 $ marmot server rm -i 1
显示所有应用列表
$ marmot server list
list
的别名为ls
以上命令将输出如下列表。
┌──────┬─────────────────────────┬────────┬────────┬──────────┬────────────────────────────────┐
│ id │ domain │ port │ pid │ status │ pathname │
├──────┼─────────────────────────┼────────┼────────┼──────────┼────────────────────────────────┤
│ 12 │ http://127.0.0.1:8080 │ 8080 │ 9088 │ online │ /Users/evan/projects/cashier │
└──────┴─────────────────────────┴────────┴────────┴──────────┴────────────────────────────────┘
路由配置
在初始化项目时,会提示您输入路由文件入口的生成位置,默认是在当前项目目录下生成
router/main.xml
,如果您需要自定义文件名,请务必使用后缀为.xml
的文件名。
以下是一个简单的路由示例。
<!-- router/main.xml --> <!-- ... --> <!-- router/product.xml -->
在路由的配置中有 router
、 import
、cookies
、cookie
、routes
、route
6种标签(不包括 xml
声明),接下来将逐一介绍其功能
router
标签
router
标签是路由入口文件的根元素,使用 import
标签引入的其他路由文件则不需要使用此标签。
proxy
属性
原为provider属性,该属性仍然可用,但推荐使用proxy
该属性作用于整个路由文件中,proxy
指向一个可访问的IP/域名,其作用为当规则被命中后,当前请求将被转发到该IP/域名,此属性的值必须是一个有效的IP/域名,如果不写协议类型,那么将以当前启动的 Marmot
应用的协议作为缺省值。
由 Marmot
通过 proxy
转发的请求,Request Headers中会包含 X-Requested-With: MarmotHttpRequest
字段。
有效的HTTP地址:
http://xxx.xxx.xxx
//xxx.xxx.xxx
xxx.xxx.xxx
值得注意的是被命中的路由规则中,route
中的 location
属性将会被忽略。
示例:
结果如下:
本地访问地址
http://127.0.0.1:8080
访问以下地址
http://127.0.0.1:8080/user/info.json
实际上将从以下url中获取数据
http://x.x.x.x:3000/user/info.json
cookies
标签
此标签用于包含所有的 cookie
设置,该标签应放在 router
标签下的第一个位置,如此才会应用于所有路由规则中。
示例:
<!-- main.xml -->
cookie
标签
设置一条cookie
属性:
name
cookie名称value
cookie值domain
cookie适用的域名,通常没必要设置path
在指定的访问路径下发起请求,cookie才会被携带max-age
cookie最大存活期,单位: 秒http-only
默认false,当设置为true时,该cookie在浏览器端不可被JS读取
示例:
import
标签
引入一个新的路由文件,该文件的路径是相对于主入口文件的,建议所有路由文件统一放到同一目录下。
目录结构:
router/
main.xml
product.xml
路由引入方式:
<!-- main.xml --> <!-- 等同如下方式 -->
routes
route-map
标签
route-map
此标签用于包含一组路由规则,路由规则的匹配仅处理 routes
标签包含的元素,写在其他位置的路由规则将不会被匹配到。
原为 route-map
标签,目前不建议使用,0.7.0 版本中将被移除。
proxy
属性
原为provider属性,该属性仍然可用,但推荐使用proxy
该属性与 router
标签上的 proxy
是一样的,不同的是只作用于 routes
下的路由规则。若 router
和 routes
同时指定 proxy
,则优先使用 routes
的 proxy
。
示例:
结果如下:
本地访问地址
http://127.0.0.1:8080
访问以下地址
http://127.0.0.1:8080/user/info.json
实际上将从以下url中获取数据
http://x.x.x.x:3002/user/info.json
访问以下地址
http://127.0.0.1:8080/movie/list.json
实际上将从以下url中获取数据
http://x.x.x.x:8888/movie/list.json
route
标签
该标签用于配置路由规则,以下为 route
标签所支持的属性。
rule
uri
属性
uri
rule
属性表示路由的匹配规则,其值可以是普通的字符串也可以是一个正则表达式,并且规则仅对URL中的路径部分进行匹配,其余部分(query string,anchor name)不会参与匹配。
原为 uri
属性,目前不建议使用,0.7.0 版本中将被移除。
<!-- 推荐 --><!-- 不推荐 -->
我们可以通过正则中的**捕获组()
来实现在location
属性中使用 $1, $2, $n
的方式来获取捕获组的值,如果要跳过某些分组不匹配则使用非捕获组(?:)
**来进行匹配,其中 $0
表示整个匹配的字符串,$1
表示第一个捕获组,$2
表示第二个捕获组,以此类推。
如下示例:
请求地址:
http://127.0.0.0:8080/foo/bar/baz.html
实际访问模版:
/baz/foo.vm
redirect
属性
针对命中的路由进行重定向,会忽略其他属性如:location, proxy, content-type
location
target
属性
target
location
属性表示该规则命中后,指向的本地访问的文件,通常是一个模板文件或者JSON文件,当然也可以是一个JSP文件。
原为 target
属性,目前不建议使用,0.7.0 版本中将被移除。
<!-- 推荐 --><!-- 不推荐 -->
proxy
属性
原为provider属性,该属性仍然可用,但推荐使用proxy
与 router/routes
中的 proxy
功能一样,都是将当前命中规则的请求转发到指定的地址,唯一不同的是改属性存在于route
标签中的话,其作用仅针对于当前规则。
示例:
<!-- 最终的转发地址将会是: http://www.b.com/test.json -->
content-type
属性
该属性用于指定当前规则命中后的响应内容类型。
值得注意的是如果你在使用 proxy
提供的数据渲染本地模板的时候,content-type
必须设置为 text/html
或 text/htm
,否则将会直接显示 proxy
响应的内容
示例:
路由规则配置:
本地 Marmot
启动端口为 8080
访问地址:
http://127.0.0.1:8080/index
规则命中,使用proxy转发后的地址
http://127.0.0.1:3000/index
velocity模板如下:
<!-- views/index.vm --> $!{title}
http://127.0.0.1:3000/index
返回结果
此时 http://127.0.0.1:8080/index
响应结果为
Hello World
数据模拟
数据模拟主要分两类:
- 本地数据模拟
- 使用proxy来访问其他服务提供的模拟数据,如:本地启动的express模拟数据或者测试服务器提供的数据
本地数据模拟
模板数据模拟
当路由规则被命中后,会渲染 location
指定的模板文件,而模板绑定的数据会从先前指定的模拟数据目录中以相同路径的方式先匹配JSP文件,其次匹配JSON文件。
参考自 jello
示例:
目录结构:
app/
views/
xxx/
index.vm
mock/
xxx/
index.jsp
index.json
index.vm 内容:
$!{title} Hello, $!{username}
本地环境模拟数据支持JSP与JSON两种格式
JSON:
JSP:
<%@page pageEncoding="UTF-8"%><% request.setAttribute("title", "foo"); request.setAttribute("username", "evan2x");%>
REST API 数据模拟
当路由规则被命中后,会返回 location
所指定文件的内容,支持静态的JSON文件或者动态JSP文件
示例:
/mock/api/users.json
若指定为JSP文件,那么该JSP需要输出JSON字符串
/mock/api/users.jsp
<%@ page trimDirectiveWhitespaces="true" %><%@ page contentType="application/json; charset=utf-8" %><%@ page import="com.alibaba.fastjson.*" %><% class Person { private String name; private int age; public void setName(String name) { this.name = name; } public String getName() { return name; } public void setAge(int age) { this.age = age; } public int getAge() { return age; } }%><% Person p = new Person(); p.setName("evan2x"); p.setAge(24); out.print(JSON.toJSONString(p));%>
以上代码输出结果与之前的 /mock/api/users.json
内容一致。
在Marmot中解析JSON用的jar包就是 fastjson,所以你可以直接导入 fastjson 来将POJO、Map、List、Collection、Enum等类型序列化为JSON字符串。
远程数据模拟
上面说了Marmot本身提供的模拟数据,接下来要说下关于远程服务/本地其他服务提供模拟数据。
模板数据模拟
之前介绍过 proxy
属性的作用,其作用就是将命中的路由转发给proxy
指定的IP/域名。
以下为使用Marmot及express来演示一个由Node.js提供数据模拟服务的栗子:
Marmot路由配置:
Node.js服务的入口 app.js
var express = ;var router = express;var app = ; router; app; app;
velocity模板 /index.vm
$!{title} $!{title} $!{description}
输出:
Hello World Hello World This is an example
注意:
- 如果路由中没有指定
content-type
属性,则不会渲染模板,而是将proxy
(以上例子中即express服务)响应的结果提供给客户端。 - express中的
/index.html
路由返回了一个JSON格式的数据,Marmot会将其绑定到模板上。
REST API 模拟数据
当路由命中后,Marmot直接将请求转发给 proxy
,返回结果由 proxy
决定。当用于REST API的时候,通常是返回JSON字符串。