开放平台总体设计文档

概述

背景

在富士行云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格式

响应示例：

{
    "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/bind/{1}

请求方式：PUT

请求参数：JSON格式

body 体中参数

{
    "projectIds": [1,2,3]
}

响应参数：JSON格式

响应示例：

{
    "code": 1000000,
    "msg": "操作成功",
    "data": null
}
配置接口

新增的应用是没有配置接口的，需要配置授权了接口，才能访问到这些开放接口。

通过接口关联查询得到接口列表，选择需要配置的接口，点击配置按钮。

可以配置多个接口，可以选择全部配置、部分配置。

接口地址：/openapi/app/config/{1}

请求方式：PUT

请求参数：JSON格式

body 体中参数

{
    "interfaceIds": [1,2,3]
}

响应参数：JSON格式

响应示例：

{
    "code": 1000000,
    "msg": "操作成功",
    "data": null
}
修改有效期

应用的有效期是可以修改的，可以根据需要修改。

应用有效期过了，则该应用不能通过开放接口访问

接口有效期可以修改比当前有效期以前，也可以修改比当前有效期以后。

如果有效期修改在当前时间以前，也是运行的，则等于直接失效了。

接口地址：/openapi/app/expiration/{1}

请求方式：PUT

请求参数：JSON格式

body 体中参数

{
    "expirationTime": "2021-01-01 00:00:00"
}

响应参数：JSON格式

响应示例：

{
    "code": 1000000,
    "msg": "操作成功",
    "data": null
}
禁用应用

平台新创建的应用一开始是禁用状态的。需要平台认为的开启才可以使用。

平台也可以在之后禁用应用，禁用后该应用不能通过开放接口访问

接口地址：/openapi/app/disable/{1}

请求方式：PUT

请求参数：路径参数

响应参数：JSON格式

响应示例：

{
    "code": 1000000,
    "msg": "操作成功",
    "data": null
}
启用应用

应用处于禁用状态时，需要平台认为的开启才可以使用。

接口地址：/openapi/app/enable/{1}

请求方式：PUT

请求参数：路径参数

响应参数：JSON格式

响应示例：

{
  "code": 1000000,
  "msg": "操作成功",
  "data": null
}
删除应用

对于已经废弃的应用，平台可以通过接口删除

接口地址：/openapi/app

请求方式：DELETE

请求参数：路径参数

响应参数：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 体中参数

{
    "expirationTime": "2021-01-01 00:00:00"
}

响应参数：JSON格式

响应示例：

{
    "code": 1000000,
    "msg": "操作成功",
    "data": null
}
重置永久token

方便用户调试使用，设置了永久token。

如果用户不需要永久token，可以重置永久token。

接口地址：/openapi/app/resetToken/{1}

请求方式：PUT

请求参数：路径参数

响应参数：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格式

响应示例：

{
    "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格式

响应示例：

{
    "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格式

{
"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格式

{
"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格式

{
"doc": "接口文档"
}

响应参数：JSON格式

{
"code": 1000000,
"msg": "操作成功",
"data": null
}
发布接口

对于已经配置的接口，需要发布接口。

接口地址：/openapi/interface/publish/{1}

请求方式：PUT

请求参数：

响应参数：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格式

响应示例：

{
"code": 1000000,
"msg": "操作成功",
"data": null
}
导出接口

可以导出当前环境的接口信息。

接口地址：/openapi/interface/export

请求方式：GET

请求参数： json

{
"ids" : "1,2,3"    //多个接口id用逗号隔开。 不传则导出全部
}

响应参数：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格式

响应示例：

{
"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生成
{
    "appId": "123456",
    "appSecret": "123456",
    "timestamp": 1610123456789,
    "sign": "123456"
}

响应参数：JSON格式

响应示例：

{
    "code": 1000000,
    "msg": "操作成功",
    "data": {
        "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNjEwMTIzNDU2LCJleHAiOjE2MTA1MjM0NTYsInVzZXJuYW1lIjoiYWRtaW4iLCJpYXQiOjE2MTA1MjM0NTYsImV4cCI6MTYxMDUyMzQ1NiwiaWF0IjoxNjEwMTIzNDU2LCJzdWIiOiIxMjM0NTY3ODkwIn0.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
    }
}
token校验
签名方式
签名校验
接口权限校验
接口流量监控

数据库设计

应用管理表

字段名 参数名称 类型 能否为空 说明
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 是 更新时间
create_user 创建人 varchar(16) 否 创建人
update_user 更新人 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 接口表的主键

安全管理redis数据结构设计