开放平台总体设计文档

概述

背景

在富士行云V2平台中，将有很多的车场，人行项目接入。为了方便车场，人行项目运营方可以在他们自己已有的平台，或者其他第三方平台对接我们的数据,并提供数据服务。

目标

为了实现开放平台的功能，我们需要设计一个开放平台的总体设计文档，包括功能模块、系统架构、数据库设计、接口设计、安全设计、流量监控与分析等。

范围

本文档仅涉及开放平台的总体设计，不涉及具体的功能模块设计。

总体设计

系统架构

系统依赖富士行云V2整体的spring cloud微服务架构。通过gateway在新的路径前缀下路由到开放平台，在通过openfeign、nacos、 load_balance 等组件实现服务间的调用。具体实现就利用我们现有的中台服务（transferService）. 在中台服务上面去建立一个新的目录（openapi）,在openapi目录下建立应用管理、接口管理、开发接口三个模块。

功能模块

开放平台用户管理

对接方需要注册开放平台用户，用户去绑定应用，一个用户可以创建一个或者多个应用。应用去绑定项目，应用也可以绑定一个或者多个项目。

注册用户

接口地址：/openapi/user/register
请求方式：POST
平台：开放平台
请求参数：JSON格式
```
{
"username": "13800000000",
"password": "123456",     //前端传入的应该是rsa加密的后的密码
"phoneNumber": "13800000000",
"nikeName": "admin"
}
```
- 响应参数：JSON格式
- 响应示例： json { "code": 1000000, "msg": "操作成功", "data": { "id": 1, "username": "13800000000", "phoneNumber": "13800000000", "nikeName": "admin", "createTime": "2019-08-30 17:56:40", "updateTime": "2019-08-30 17:56:40" } }

修改密码

接口地址：/openapi/user/updatePassword
请求方式：PUT
平台：开放平台

请求参数：JSON格式

{
"oldPassword": "123456",      //前端传入的应该是rsa加密的后的旧密码
"newPassword": "<PASSWORD>"  //前端传入的应该是rsa加密的后的新密码
}

响应参数：JSON格式
响应示例： json { "code": 1000000, "msg": "操作成功" } ##### 重置密码

接口地址：/openapi/user/resetPassword
请求方式：PUT
平台：开放平台
请求参数：JSON格式
```
{
"userId": 1, 
"newPassword": "123456",  //前端传入的应该是rsa加密的后的新密码  
"smsCode": "1234"   //短信验证码
}
```
用户登录
- 接口地址：/openapi/user/login
- 请求方式：POST
- 平台：开放平台
- 请求参数：JSON格式 json { "username": "13800000000", "password": "123456", //前端传入的应该是rsa加密的后的密码 "verfiyCode": "1234" //验证码 }
响应参数：JSON格式
响应示例：

{
  "code": 1000000,
  "msg": "操作成功",
  "data": {
    "token": ""      //除了登录  其他的开放平台用户操作都需要带上这个token
  }
}

退出登录

接口地址：/openapi/user/logout
请求方式：PUT
平台：开放平台
响应参数：JSON格式
响应示例：
```
{
"code": 1000000,
"msg": "操作成功"
}
```
获取用户信息
- 接口地址：/openapi/user/info/{1}
- 请求方式：GET
- 平台：开放平台
- 响应参数：JSON格式
- 响应示例： json { "code": 1000000, "msg": "操作成功", "data": { "id": 1, "username": "13800000000", "phoneNumber": "13800000000", "nikeName": "admin", "createTime": "2019-08-30 17:56:40", "updateTime": "2019-08-30 17:56:40" } }

获取用户分页列表

接口地址：/openapi/user/page
请求方式：GET
平台：总部端
请求参数：JSON格式 ```json { "current": 1, "size": 10, "username": "13800000000", "nikeName": "admin", "phoneNumber": "13800000000"

}


* 响应参数：JSON格式
* 响应示例：
```json
{
  "code": 1000000,
  "msg": "操作成功",
  "data": [
    {
      "id": 1,
      "username": "13800000000",
      "phoneNumber": "13800000000",
      "nikeName": "admin",
      "createTime": "2019-08-30 17:56:40",
      "updateTime": "2019-08-30 17:56:40"
    }
  ]
}

用户注销

接口地址：/openapi/user/delete/{1}
请求方式：DELETE
平台：总部端
响应参数：JSON格式

响应示例：

{
"code": 1000000,
"msg": "操作成功"
}

开放平台应用管理

开放平台应用管理模块负责对接车场、人行项目的应用，包括应用的注册、认证、授权、管理等。

新增应用

在系统添加一个应用，用于对接车场、人行项目的开放接口。需要输入应用名称、服务行业、应用描述、应用logo、用户名（负责人）、手机号码。

具体参数表格如下：

字段名	参数名称	类型	说明	是否必填
name	应用名称	字符串	应用名称	是
serviceType	服务行业	字符串	服务行业	是
remark	应用描述	字符串	应用描述	否
logo	应用logo	字符串	应用logo 存oss key	否
userId	用户id	字符串	开放平台用户id	是

接口地址：/openapi/app/add
请求方式：POST
平台：开放平台
请求参数：JSON格式 json { "name": "车场应用", "serviceType": "车场", "remark": "车场应用", "logo": "osskey", "userId": 1 }

响应参数：JSON格式响应示例：
```
{
"code": 1000000,
"msg": "操作成功",
"data": {
    "id": 1,
    "name": "车场应用",
    "serviceType": "车场",
    "remark": "车场应用",
    "logo": "osskey",
    "userId": 1,
    "createTime": "2021-01-01 00:00:00",
    "updateTime": "2021-01-01 00:00:00",
    "expirationTime " : "2021-01-01 00:00:00",
    "status" : 1 // 0启用 1禁用
}
}    
```
绑定项目
- 新增的应用是没有绑定项目的，需要绑定项目才能使用接口。
- 通过调用系统服务获取到项目列表，选择需要绑定的项目，点击绑定按钮。
- 可以绑定多个项目
- 接口地址：/openapi/app/bind/{1}
- 请求方式：PUT
- 平台：总部端
- 请求参数：JSON格式 body 体中参数 json { "projectIds": [1,2,3] }
响应参数：JSON格式响应示例：
```
{
"code": 1000000,
"msg": "操作成功",
"data": null
}
```
配置接口
- 新增的应用是没有配置接口的，需要配置授权了接口，才能访问到这些开放接口。
- 通过接口关联查询得到接口列表，选择需要配置的接口，点击配置按钮。
- 可以配置多个接口，可以选择全部配置、部分配置。
- 接口地址：/openapi/app/config/{1}
- 请求方式：PUT
- 平台：总部端
- 请求参数：JSON格式 body 体中参数 json { "interfaceIds": [1,2,3] }
响应参数：JSON格式响应示例：
```
{
"code": 1000000,
"msg": "操作成功",
"data": null
}
```
修改有效期
- 应用的有效期是可以修改的，可以根据需要修改。
- 应用有效期过了，则该应用不能通过开放接口访问
- 接口有效期可以修改比当前有效期以前，也可以修改比当前有效期以后。
- 如果有效期修改在当前时间以前，也是运行的，则等于直接失效了。
- 接口地址：/openapi/app/expiration/{1}
- 请求方式：PUT
- 平台：总部端
- 请求参数：JSON格式 body 体中参数 json { "expirationTime": "2021-01-01 00:00:00" }
响应参数：JSON格式响应示例：
```
{
"code": 1000000,
"msg": "操作成功",
"data": null
}
```
禁用应用
- 平台新创建的应用一开始是禁用状态的。需要平台认为的开启才可以使用。
- 平台也可以在之后禁用应用，禁用后该应用不能通过开放接口访问
- 接口地址：/openapi/app/disable/{1}
- 请求方式：PUT
- 平台：总部端
- 请求参数：路径参数
- 响应参数：JSON格式响应示例： json { "code": 1000000, "msg": "操作成功", "data": null } ##### 启用应用
应用处于禁用状态时，需要平台认为的开启才可以使用。
接口地址：/openapi/app/enable/{1}
请求方式：PUT
平台：总部端
请求参数：路径参数
响应参数：JSON格式响应示例：
```
{
"code": 1000000,
"msg": "操作成功",
"data": null
}
```
删除应用
- 对于已经废弃的应用，平台可以通过接口删除
- 接口地址：/openapi/app
- 请求方式：delete
- 平台：总部端
- 请求参数：路径参数
- 响应参数：JSON格式响应示例： json { "code": 1000000, "msg": "操作成功", "data": null } ##### 重置应用秘钥
新创建的应用的秘钥是随机生成的32位数字跟英文大写字母。
如果用户签名秘钥存在泄露的情况，可以自己重置签名秘钥，平台也可以重置签名秘钥。
重置的签名秘钥也是随机生成的。
接口地址：/openapi/app/resetSignKey/{1}
请求方式：PUT
平台：总部端
请求参数：路径参数
响应参数：JSON格式响应示例：
```
{
"code": 1000000,
"msg": "操作成功",
"data": null
}
```
重置签名密钥
- 应用的签名秘钥用户数据接口的参数加签用的。应用生成的时候，签名秘钥是随机生成的
- 应用有效期过了，则该应用不能通过开放接口访问
- 接口有效期可以修改比当前有效期以前，也可以修改比当前有效期以后。
- 如果有效期修改在当前时间以前，也是运行的，则等于直接失效了。
- 接口地址：/openapi/app/expiration/{1}
- 请求方式：PUT
- 平台：总部端
- 请求参数：JSON格式 body 体中参数 json { "expirationTime": "2021-01-01 00:00:00" }
响应参数：JSON格式响应示例：
```
{
"code": 1000000,
"msg": "操作成功",
"data": null
}
```
重置永久token
- 方便用户调试使用，设置了永久token。
- 如果用户不需要永久token，可以重置永久token。
- 接口地址：/openapi/app/resetToken/{1}
- 请求方式：PUT
- 平台：总部端
- 请求参数：路径参数
- 响应参数：JSON格式响应示例： json { "code": 1000000, "msg": "操作成功", "data": null } ##### 修改通知回调地址
对于一些下行的接口，或者推送的接口，需要应用配置下行的地址。
回调的地址支持到端口后的特定前缀。例如：http://www.baidu.com/callback, 推送的消息会发送到http://www.baidu.com/callback/push/xxx
新创建的应用的通知回调地址为空。没有配置的情况下，平台不会推送消息。
平台对于每个应用只支持推送一个通知回调地址。
接口地址：/openapi/app/callback/{1}
请求方式：PUT
平台：总部端
请求参数：JSON格式 body 体中参数
```
{
"callbackAddress": "2021-01-01 00:00:00"
}
```
- 响应参数：JSON格式响应示例： json { "code": 1000000, "msg": "操作成功", "data": null } ##### 查询详情
接口地址：/openapi/app/{1}
请求方式：GET
平台：总部端，开放平台
请求参数：路径参数
响应参数：JSON格式

响应示例：

{
"code": 1000000,
"msg": "操作成功",
"data": {
    "id": 1,
    "name": "车场应用",
    "serviceType": "车场",
    "remark": "车场应用",
    "logo": "osskey",
    "userName": "admin",
    "phoneNumber": "13800138000",
    "createTime": "2021-01-01 00:00:00",
    "updateTime": "2021-01-01 00:00:00",
    "createUser": "admin",
    "updateUser": "admin",
    "expirationTime " : "2021-01-01 00:00:00",
    "status" : 1, // 0启用 1禁用
}
}

查询应用列表（分页）

接口地址：/openapi/app/page
请求方式：GET
平台：总部端，开放平台
请求参数：分页参数

参数名	类型	说明	是否必填
current	int	页码	是
size	int	每页条数	是
name	string	应用名称	否
serviceType	string	服务行业	否
status	int	状态	否
phoneNumber	string	手机号码	否

响应参数：JSON格式
响应示例： json { "code": 1000000, "msg": "操作成功", "data": { "total": 10, "pages": 20, "current": 1, "size": 10, "records": [ { "id": 1, "name": "车场应用", "serviceType": "车场", "remark": "车场应用", "logo": "osskey", "userName": "admin", "phoneNumber": "13800138000", "createTime": "2021-01-01 00:00:00", "updateTime": "2021-01-01 00:00:00", "createUser": "admin", "updateUser": "admin", "expirationTime " : "2021-01-01 00:00:00", "status" : 1, // 0启用 1禁用 } ] } }

开放平台接口管理

开放平台数据接口管理模块负责对接车场、人行项目的接口，包括接口的注册、认证、授权、管理等。我们将配置两类接口，一个是上行接口，一个是下行接口。上行接口

新增接口

开放平台对外提供的接口，包括车场、人行项目的接口。都是在这里添加。需要的参数有，接口名称，路径，请求方式，接口类型，版本，发布状态，接口展示文档，启用状态，访问限制次数。

具体参数表格如下：

| 字段名 | 参数名称 | 类型 | 说明 | 是否必填 | |--------------|--------|-----|---------------------------|------|

| name         | 接口名称   | 字符串 | 接口名称                      | 是    |
| path         | 路径     | 字符串 | 接口路径                      | 是    |
| method       | 请求方式   | 字符串 | 请求方式  POST PUT GET DELETE | 是    |
| type         | 接口类型   | int | 接口类型  0 上行 1 下行           | 是    |
| serviceType | 业务类型   | int | 1 车位 2 支付 3 月卡 4 车场 5 优惠券 | 是    |
| version      | 版本     | 字符串 | 版本号     v1  v2 ...        | 是    |
| status       | 发布状态   | int | 发布状态      0 未发出 1 已发布     | 是    |
| doc          | 接口展示文档 | 字符串 | 接口展示文档  markdown格式        | 否    |
| enable       | 启用状态   | int | 启用状态     0 启用 1 禁用        | 是    |
| limitCount   | 访问限制次数 | int | 每秒访问限制次数                  | 否    |

接口地址：/openapi/interface/add
请求方式：POST
平台：总部端
请求参数：JSON格式
```
{
"name": "车场接口",
"path": "/api/v1/car/parking",
"method": "GET",
"type": 0,
"serviceType": 1,
"version": "v1",
"doc": "",
"limitCount": 100
}
```
- 响应参数：JSON格式 json { "code": 1000000, "msg": "操作成功", "data": { "id": 1, "name": "车场接口", "path": "/api/v1/car/parking", "method": "GET", "type": 0, "serviceType": 1, "version": "v1", "status": 1, "doc": "", "enable": 1, "limitCount": 100, "createTime": "2021-01-01 00:00:00", "updateTime": "2021-01-01 00:00:00", "createUser": "admin", "updateUser": "admin" } }

编辑接口

对于已经发布的接口，需要修改接口信息。
可以修改的参数有接口名称、路径、请求方式、接口类型、版本、接口展示文档、访问限制次数。参考新增的表格。
修改的时候传入参数如果没有修改，则不传。参数为空的时候等于不修改。
接口地址：/openapi/interface/edit/{1}
请求方式：PUT
平台：总部端
请求参数：JSON格式
```
{
"name": "车场接口",
"path": "/api/v1/car/parking",
"method": "GET",
"type": 0,
"serviceType": 1,
"version": "v1",
"doc": "",
"limitCount": 100
}
```
- 响应参数：JSON格式 json { "code": 1000000, "msg": "操作成功", "data": { "id": 1, "name": "车场接口", "path": "/api/v1/car/parking", "method": "GET", "type": 0, "serviceType": 1, "version": "v1", "status": 1, "doc": "", "enable": 1, "limitCount": 100, "createTime": "2021-01-01 00:00:00", "updateTime": "2021-01-01 00:00:00", "createUser": "admin", "updateUser": "admin" } }

删除接口

对于已经废弃的接口，需要删除接口。或者批量删除接口。
接口地址：/openapi/interface
请求方式：DELETE
平台：总部端
请求参数： ids 多个用逗号隔开
响应参数：JSON格式
响应示例：
```
{
"code": 1000000,
"msg": "操作成功",
"data": null
}
```
配置接口文档
- 接口中需要配置给开放平台展示的接口文档。需要markdown格式。
- 管理员通过前端页面编辑接口文档。
- 接口地址：/openapi/interface/doc/{1}
- 请求方式：PUT
- 平台：总部端
- 请求参数：JSON格式 json { "doc": "接口文档" }
响应参数：JSON格式
```
{
"code": 1000000,
"msg": "操作成功",
"data": null
}
```
发布接口
- 对于已经配置的接口，需要发布接口。
- 接口地址：/openapi/interface/publish/{1}
- 请求方式：PUT
- 平台：总部端
- 请求参数：
- 响应参数：JSON格式 json { "code": 1000000, "msg": "操作成功", "data": null }

禁用接口

对于已经发布的接口，可以通过页面禁用接口。
接口地址：/openapi/interface/disable/{1}
请求方式：PUT
平台：总部端
请求参数：
响应参数：JSON格式
```
{
"code": 1000000,
"msg": "操作成功",
"data": null
}
```
导入接口
- 可以通过excel导入其他环境已经配置好的接口。
- 接口地址：/openapi/interface/import
- 请求方式：POST
- 平台：总部端
- 请求参数：multipart_file //excel文件
- 响应参数：JSON格式
- 响应示例： json { "code": 1000000, "msg": "操作成功", "data": null }

导出接口

可以导出当前环境的接口信息。
接口地址：/openapi/interface/export
请求方式：GET
平台：总部端
请求参数： json
```
{
"ids" : "1,2,3"    //多个接口id用逗号隔开。 不传则导出全部
}
```
- 响应参数：JSON格式
- 响应示例： json { "code": 1000000, "msg": "操作成功", "data": [ { "id": 1, "name": "车场接口", "path": "/api/v1/car/parking", "method": "GET", "type": 0, "serviceType": 1, "version": "v1", "status": 1, "doc": "", "enable": 1, "limitCount": 100, "createTime": "2021-01-01 00:00:00", "updateTime": "2021-01-01 00:00:00", "createUser": "admin", "updateUser": "admin" } ] }

查询详情

接口地址：/openapi/interface/{1}
请求方式：GET
平台：总部端
请求参数：路径参数
响应参数：JSON格式

响应示例：

{
"code": 1000000,
"msg": "操作成功",
"data": {
    "id": 1,
    "name": "车场接口",
    "path": "/api/v1/car/parking",
    "method": "GET",
    "type": 0,
    "serviceType": 1,
    "version": "v1",
    "status": 1,
    "doc": "",
    "enable": 1,
    "limitCount": 100,
    "createTime": "2021-01-01 00:00:00",
    "updateTime": "2021-01-01 00:00:00",
    "createUser": "admin",
    "updateUser": "admin"
}
}

查询接口列表（分页）

接口地址：/openapi/interface/page
请求方式：GET
平台：总部端，开放平台
请求参数：分页参数

参数名	类型	说明	是否必填
current	int	页码	是
size	int	每页条数	是
name	string	应用名称	否
serviceType	string	服务行业	否
status	int	状态	否
path	string	访问路径	否

响应参数：JSON格式
响应示例： json { "code": 1000000, "msg": "操作成功", "data": { "total": 10, "pages": 20, "current": 1, "size": 10, "records": [ { "id": 1, "name": "车场接口", "path": "/api/v1/car/parking", "method": "GET", "type": 0, "serviceType": 1, "version": "v1", "status": 1, "doc": "", "enable": 1, "limitCount": 100, "createTime": "2021-01-01 00:00:00", "updateTime": "2021-01-01 00:00:00", "createUser": "admin", "updateUser": "admin" } ] } }

开放平台安全管理

开放平台安全校验模块负责对接车场、人行项目的安全校验，包括接口的安全校验、数据加密、数据权限校验、数据流量监控等。

token生成

开放平台对外提供的接口，都需要通过token进行访问。
开放平台用户，需要通过appId, appSecret, timestamp, sign生成token。
token具有有效期。有效期时长可以配置。默认为两天。
token是采用jwt生成的。
接口地址：/openapi/token/generate
请求方式：POST
请求参数：JSON格式
```
{
"appId": "123456",
"appSecret": "123456",
"timestamp": 1610123456789,
"sign": "123456"
}
```
- 响应参数：JSON格式
- 响应示例： json { "code": 1000000, "msg": "操作成功", "data": { "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNjEwMTIzNDU2LCJleHAiOjE2MTA1MjM0NTYsInVzZXJuYW1lIjoiYWRtaW4iLCJpYXQiOjE2MTA1MjM0NTYsImV4cCI6MTYxMDUyMzQ1NiwiaWF0IjoxNjEwMTIzNDU2LCJzdWIiOiIxMjM0NTY3ODkwIn0.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c" } }

token校验

开放平台对外提供的接口，都需要通过token进行访问。
开放平台用户，需要通过token校验。
通过jwt解析token。对比jwt中的body数据是否正确。并获取当前应用的一些权限。

签名方式
所有的接口按照接口都需要参数签名。
对所有的加密字段，通过ascii排序后，拼接成字符串，然后用appSecret进行aes加密。
对于post， put请求，加密参数会在body中。
对于get, delete请求，加密参数会在url中。

签名校验

所有的接口都需要校验签名。
对所有的加密字段，通过ascii排序后，拼接成字符串，然后用appSecret进行aes加密。
对比签名是否正确。

接口权限校验

开放平台对外提供的接口，都需要进行权限校验。
查看当前应用的接口绑定关系。
根据当前应用的权限，判断当前接口是否有权限访问。

接口流量监控

开放平台对外提供的接口，都需要进行流量监控。
每个接口都需要记录访问次数。按照秒，分，时，天，月，年进行统计。目前只统计当前值。就是当前秒，当前分，过时的就丢弃。
对于接口都存在一个访问限制数。
限制数目前设置的是当前秒的限制数。
限制数达到后，接口会被禁用。

数据库设计

应用管理表

字段名	参数名称	类型	能否为空	说明
id	主键	int	否	应用id
name	应用名称	varchar(16)	否	应用名称
app_id	应用id	varchar(32)	否	应用id
app_secret	应用密钥	varchar(32)	否	应用密钥
status	应用状态	int	否	应用状态 0 禁用 1 启用
create_time	创建时间	datetime	否	创建时间
update_time	更新时间	datetime	是	更新时间
user_id	创建人	varchar(16)	否	创建人
expiration_time	过期时间	datetime	否	过期时间
is_delete	是否已删除	int	否	0 正常 1 已删除
remark	备注	varchar(255)	是	备注

应用项目关联表

字段名	参数名称	类型	能否为空	说明
id	主键	int	否	主键
app_id	应用id	varchar(32)	否	应用id 应用表的主键
project_id	项目id	int	否	项目id 对应项目表的主键

接口管理表

字段名	参数名称	类型	能否为空	说明
id	主键	int	否	接口id
name	接口名称	varchar(16)	否	接口名称
path	接口路径	varchar(128)	否	接口路径
method	请求方式	varchar(16)	否	请求方式
type	接口类型	int	否	接口类型 0 上行 1下行
service_type	服务类型	int	否	1 车位 2 支付 3 月卡 4 车场 5 优惠券
version	版本号	varchar(16)	否	版本号 v1 v2
doc	接口文档	text	是	接口文档
status	接口状态	int	否	接口状态 0 禁用 1 启用
enable	是否启用	int	否	是否启用 0 禁用 1 启用
limit_count	限制次数	int	否	限制次数
create_time	创建时间	datetime	否	创建时间
update_time	更新时间	datetime	是	更新时间
create_user	创建人	varchar(16)	否	创建人
update_user	更新人	varchar(16)	是	更新人
is_delete	是否已删除	int	否	0 正常 1 已删除
remark	备注	varchar(255)	是	备注

应用接口授权关联表

字段名	参数名称	类型	能否为空	说明
id	主键	int	否	主键
app_id	应用id	varchar(32)	否	应用id 应用表的主键
interface_id	接口id	int	否	接口id 接口表的主键

开放平台总体设计.md 28 KB Permalink History Raw

开放平台总体设计文档

概述

背景

目标

范围

总体设计

系统架构

功能模块

开放平台用户管理

注册用户

修改密码

用户登录

退出登录

获取用户信息

获取用户分页列表

用户注销

开放平台应用管理

新增应用

绑定项目

配置接口

修改有效期

禁用应用

删除应用

重置签名密钥

重置永久token

查询应用列表（分页）

开放平台接口管理

新增接口

编辑接口

删除接口

配置接口文档

发布接口

禁用接口

导入接口

导出接口

查询详情

查询接口列表（分页）

开放平台安全管理

token生成

token校验

签名方式

签名校验

接口权限校验

接口流量监控

数据库设计

应用管理表

应用项目关联表

接口管理表

应用接口授权关联表

数据接口列表

开放平台总体设计.md 28 KB

Permalink History Raw