Rap2接口管理工具接入

一. Rap介绍

rap是阿里妈妈前端团队出品的一款API 文档管理工具，目前是第二版。

好处

• 在 rap 中，可以定义接口的 URL、请求 & 响应格式细节, 同时支持mockjs数据 。
• 强大的 GUI 界面工具 ，完全可视化可编辑的管理工具。
• 通过Rapper对接口进行转码、Hooks适配、数据缓存,帮助开发团队高效开发。

Rap系统包含两套代码

RAP2是在RAP1基础上重做的新项目，它包含两个组件(对应两个Github Repository)。

• rap2-delos: 后端数据API服务器，基于Koa + MySQLlink
  • https://github.com/thx/rap2-dolores
• rap2-dolores: 前端静态资源，基于React link
  • https://github.com/thx/rap2-delos

Rap 官方服务站点，无需安装直接体验: rap2.taobao.org

二. 安装Rap2

rap2有两种安装方式:手动部署or使用Docker部署

1. Docker 快速部署(推荐使用)

快速上手Docker

Docker官方文档 https://docs.docker.com/
Docker入门可以看阮一峰的这篇文章 http://www.ruanyifeng.com/blog/2018/02/docker-tutorial.html

安装 Docker

国内用户可参考 https://get.daocloud.io/ 安装 Docker 以及 Docker Compose (Linux 用户需要单独安装)，建议按照链接指引配置 Docker Hub 的国内镜像提高加载速度。

配置项目

在任意地方建立目录 rap

把本仓库中的 docker-compose.yml 放到 rap 目录中

Rap 前端服务的端口号默认为 3000，你可以在 docker-compose.yml 中按照注释自定义

在 rap 目录下执行下面的命令：

# 拉取镜像并启动
docker-compose up -d

# 启动后，第一次运行需要手动初始化mysql数据库
# ⚠️注意: 只有第一次该这样做
docker-compose exec delos node scripts/init

# 部署成功后 访问
http://localhost:3000 # 前端（可自定义端口号）
http://localhost:38080 # 后端

# 如果访问不了可能是数据库没有链接上，关闭 rap 服务
docker-compose down
# 再重新运行
docker-compose up -d
# 如果 Sequelize 报错可能是数据库表发生了变化，运行下面命令同步
docker-compose exec delos node scripts/updateSchema

⚠️注意：第一次运行后 rap 目录下会被自动创建一个 docker 目录，里面存有 rap 的数据库数据，可千万不要删除。

补充

docker-compose 是基于docker的容器编排工具，能够更方便定义，管理容器，这个工具可以使用yml格式来定义，通过一条命令就可以根据编写的yml文件来创建，管理容器。
官方文档 https://docs.docker.com/compose/features-uses/

镜像升级

Rap 经常会进行 bugfix 和功能升级，用 Docker 可以很方便地跟随主项目升级

# 拉取一下最新的镜像
docker-compose pull
# 暂停当前应用
docker-compose down
# 重新构建并启动
docker-compose up -d --build
# 有时表结构会发生变化，执行下面命令同步
docker-compose exec delos node scripts/updateSchema
# 清空不被使用的虚悬镜像
docker image prune -f

2. 手动部署

环境要求

• Node.js 8.9.4+
• MySQL 5.7+
• Redis 4.0+
• pandoc 2.73 (供文档生成使用)

开发模式

安装 MySQL 和 Redis 服务器

请自行查找搭建方法，mysql/redis 配置在 config.*.ts 文件中，在不修改任何配置的情况下，
redis 会通过默认端口 + 本机即可正常访问，确保 redis-server 打开即可。

注意：修改 cofig 文件后需要重新 npm run build 才能生效

安装 pandoc

我们使用 pandoc 来生成 Rap 的离线文档，安装 Pandoc 最通用的办法是在 pandoc 的 release 页面下载对应平台的二进制文件安装即可。

其中 linux 版本最好放在/usr/local/bin/pandoc 让终端能直接找到，并执行 chmod +x /usr/local/bin/pandoc 给调用权限。

测试在命令行执行命令 pandoc -h 有响应即可。

启动redis-server

redis-server

后台执行可以使用 nohup 或 pm2，这里推荐使用 pm2，下面命令会安装 pm2，并通过 pm2 来启动 redis 缓存服务

npm install -g pm2
npm run start:redis

先创建创建数据库

mysql -e 'CREATE DATABASE IF NOT EXISTS RAP2_DELOS_APP DEFAULT CHARSET utf8 COLLATE utf8_general_ci'

初始化

npm install

confirm configurations in /config/config.dev.js (used in development mode)，确认/config/config.dev.js 中的配置(.dev.js 后缀表示用于开发模式)。

安装 && TypeScript 编译

npm install -g typescript
npm run build

初始化数据库表

npm run create-db

执行 mocha 测试用例和 js 代码规范检查

npm run check

启动开发模式的服务器 监视并在发生代码变更时自动重启

npm run dev

生产模式

# 1. 修改/config/config.prod.js中的服务器配置
# 2. 启动生产模式服务器
npm start

三. 在本地集成&使用

1. 大开docker控制面板,在容器中可以看到rap容器组,将它运行起来

运行起来之后如下:

我们访问本地Rap系统 http://localhost:8888/account/login .
注册好账号登录使用

数据mock规则,可以参考官方文档
http://mockjs.com/examples.html

按照提示尝试使用Rapper生成代码

Rapper是什么?

Rapper 是 TypeScript 的最佳拍档，它可以帮你生成具有类型定义的请求方案。Rapper 在Rap的基础上更进一步，利用这些已经录入的接口数据为你生成 TypeScript 类型定义以及配套的数据请求方案，让你在代码开发中省去重复的劳动。

• 无需自行书写请求代码，把 HTTP 接口当做函数调用
• 请求参数/返回数据类型化，静态校验、自动补全快到飞起
• 对 React/Redux 特别优化，提供全局数据方案，hooks 轻松使用

Rapper官方文档 https://www.yuque.com/rap/rapper/readme

四. 集成到admin项目&演示(参考)

首先集成到项目

因为rap用的是fetch,而我们的admin项目用的是umi的request,request内置了很多拦截和鉴权逻辑,所以需要将fetch改写成request.
参考这https://www.yuque.com/rap/rapper/overridefetch

通过cross-env设置环境变量,然后判断是否需要走rap到mock

在代理这里配置一下就可以了

五. 部署(参考)

由于是基础设施，并且rap2的更新非常频繁，所以可以考虑有灰度发布，滚动升级的方式，否则其他人会找我们的麻烦。

Nginx

入口可以采用一台nginx，也可以采用一台VirtualIP+多ng的部署方式。对外暴露ng地址（或者VIP）。Ng物理机防护墙开80和38080。80端口为前端页面访问，38080为后端访问。配置相应的访问方式（nginx配置）

Dolores（BE)

Dolores是rap2的静态资源，主要是html，css，js，等。随便找两台配置很差的机器即可。内网只需保持高可用，在性能上没问题。毕竟开发者就是前端大神。

Delos（FE）

Delos是rap2的接口，需要node运行环境。为了简化部署，采用docker进行部署，用k8s编排服务。另外。delos还需要redis和mysql。由于不是我们自己开发的，不敢把redis接入到我们现有的redis环境中，害怕影响其他业务。所以也采用了docker部署redis。mysql采用了物理机，当然你也可以采用docker部署。由于目前rap2的接口请求都是无状态的，K8S采用了LoadBalance的方式接入服务。编排可以参考这个Yaml

参考文献

• https://www.yuque.com/rap/rapper/use
• https://blog.csdn.net/qq_42157883/article/details/124783441
• https://github.com/thx/rap2-delos
• https://developer.aliyun.com/article/674736
• http://mockjs.com/examples.html
• https://github.com/thx/rap2-delos/wiki/docker