开放平台总体设计文档

概述

背景

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

目标

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

范围

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

总体设计

系统架构

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

功能模块

开放平台用户管理

开放平台应用管理

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

新增应用

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

具体参数表格如下：

字段名	参数名称	类型	说明	是否必填
name	应用名称	字符串	应用名称	是
serviceType	服务行业	字符串	服务行业	是
remark	应用描述	字符串	应用描述	否
logo	应用logo	字符串	应用logo 存oss key	否
userName	用户名	字符串	负责人用户名	是
phoneNumber	手机号码	字符串	负责人手机号码	是

接口地址：/openapi/app/add
请求方式：POST
请求参数：JSON格式
```
{
"name": "车场应用",
"serviceType": "车场",
"remark": "车场应用",
"logo": "osskey",
"userName": "admin",
"phoneNumber": "13800138000"
}
```
- 响应参数：JSON格式响应示例： json { "code": 200, "msg": "success", "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/bind/{1}
请求方式：PUT
请求参数：JSON格式 body 体中参数
```
{
"projectIds": [1,2,3]
}
```
- 响应参数：JSON格式响应示例： json { "code": 200, "msg": "success", "data": null }

配置接口

新增的应用是没有配置接口的，需要配置授权了接口，才能访问到这些开放接口。
通过接口关联查询得到接口列表，选择需要配置的接口，点击配置按钮。
可以配置多个接口，可以选择全部配置、部分配置。
接口地址：/openapi/app/config/{1}
请求方式：PUT
请求参数：JSON格式 body 体中参数
```
{
"interfaceIds": [1,2,3]
}
```
- 响应参数：JSON格式响应示例： json { "code": 200, "msg": "success", "data": null }

修改有效期

应用的有效期是可以修改的，可以根据需要修改。
应用有效期过了，则该应用不能通过开放接口访问
接口有效期可以修改比当前有效期以前，也可以修改比当前有效期以后。
如果有效期修改在当前时间以前，也是运行的，则等于直接失效了。
接口地址：/openapi/app/expiration/{1}
请求方式：PUT
请求参数：JSON格式 body 体中参数
```
{
"expirationTime": "2021-01-01 00:00:00"
}
```
- 响应参数：JSON格式响应示例： json { "code": 200, "msg": "success", "data": null } ##### 禁用应用
平台新创建的应用一开始是禁用状态的。需要平台认为的开启才可以使用。
平台也可以在之后禁用应用，禁用后该应用不能通过开放接口访问
接口地址：/openapi/app/disable/{1}
请求方式：PUT
请求参数：路径参数
响应参数：JSON格式响应示例：
```
{
"code": 200,
"msg": "success",
"data": null
}
```
启用应用
- 应用处于禁用状态时，需要平台认为的开启才可以使用。
- 接口地址：/openapi/app/enable/{1}
- 请求方式：PUT
- 请求参数：路径参数
- 响应参数：JSON格式响应示例： json { "code": 200, "msg": "success", "data": null } ##### 删除应用
对于已经废弃的应用，平台可以通过接口删除
接口地址：/openapi/app
请求方式：delete
请求参数：路径参数
响应参数：JSON格式响应示例：
```
{
"code": 200,
"msg": "success",
"data": null
}
```
重置应用秘钥
- 新创建的应用的秘钥是随机生成的32位数字跟英文大写字母。
- 如果用户签名秘钥存在泄露的情况，可以自己重置签名秘钥，平台也可以重置签名秘钥。
- 重置的签名秘钥也是随机生成的。
- 接口地址：/openapi/app/resetSignKey/{1}
- 请求方式：PUT
- 请求参数：路径参数
- 响应参数：JSON格式响应示例： json { "code": 200, "msg": "success", "data": null } ##### 重置签名密钥
应用的签名秘钥用户数据接口的参数加签用的。应用生成的时候，签名秘钥是随机生成的
应用有效期过了，则该应用不能通过开放接口访问
接口有效期可以修改比当前有效期以前，也可以修改比当前有效期以后。
如果有效期修改在当前时间以前，也是运行的，则等于直接失效了。
接口地址：/openapi/app/expiration/{1}
请求方式：PUT
请求参数：JSON格式 body 体中参数
```
{
"expirationTime": "2021-01-01 00:00:00"
}
```
- 响应参数：JSON格式响应示例： json { "code": 200, "msg": "success", "data": null } ##### 重置永久token
方便用户调试使用，设置了永久token。
如果用户不需要永久token，可以重置永久token。
接口地址：/openapi/app/resetToken/{1}
请求方式：PUT
请求参数：路径参数
响应参数：JSON格式响应示例：
```
{
"code": 200,
"msg": "success",
"data": null
}
```
修改通知回调地址
- 对于一些下行的接口，或者推送的接口，需要应用配置下行的地址。
- 回调的地址支持到端口后的特定前缀。例如：http://www.baidu.com/callback, 推送的消息会发送到http://www.baidu.com/callback/push/xxx
- 新创建的应用的通知回调地址为空。没有配置的情况下，平台不会推送消息。
- 平台对于每个应用只支持推送一个通知回调地址。
- 接口地址：/openapi/app/callback/{1}
- 请求方式：PUT
- 请求参数：JSON格式 body 体中参数 json { "callbackAddress": "2021-01-01 00:00:00" }
响应参数：JSON格式响应示例：
```
{
"code": 200,
"msg": "success",
"data": null
}
```
查询详情
- 接口地址：/openapi/app/{1}
- 请求方式：GET
- 请求参数：路径参数
- 响应参数：JSON格式
- 响应示例： json { "code": 200, "msg": "success", "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格式

响应示例：

{
"code": 200,
"msg": "success",
"data": {
    "total": 10,
    "list": [
        {
            "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格式 json { "name": "车场接口", "path": "/api/v1/car/parking", "method": "GET", "type": 0, "serviceType": 1, "version": "v1", "doc": "", "limitCount": 100 }

响应参数：JSON格式
```
{
"code": 200,
"msg": "success",
"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格式 json { "name": "车场接口", "path": "/api/v1/car/parking", "method": "GET", "type": 0, "serviceType": 1, "version": "v1", "doc": "", "limitCount": 100 }

响应参数：JSON格式

{
"code": 200,
"msg": "success",
"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格式
响应示例： json { "code": 200, "msg": "success", "data": null }

配置接口文档

接口中需要配置给开放平台

发布接口

禁用接口

导入接口

导出接口

查询详情

查询接口列表（分页）

开放平台安全管理

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

开放平台总体设计.md 14 KB 履歴 Raw

开放平台总体设计文档

概述

背景

目标

范围

总体设计

系统架构

功能模块

开放平台用户管理

开放平台应用管理

新增应用

绑定项目

配置接口

修改有效期

启用应用

重置应用秘钥

修改通知回调地址

查询详情

查询应用列表（分页）

开放平台接口管理

新增接口

编辑接口

删除接口

配置接口文档

发布接口

禁用接口

导入接口

导出接口

查询详情

查询接口列表（分页）

开放平台安全管理

token生成

token校验

签名方式

签名校验

接口权限校验

接口流量监控

数据库设计

应用管理表

应用项目关联表

接口管理表

应用接口授权关联表

安全管理redis数据结构设计

数据接口列表

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

履歴 Raw