# 开放平台总体设计文档 ## 概述 ### 背景 在富士行云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格式 ```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 体中参数 ```json { "projectIds": [1,2,3] } ``` * 响应参数：JSON格式 响应示例： ```json { "code": 200, "msg": "success", "data": null } ``` ##### 配置接口 * 新增的应用是没有配置接口的，需要配置授权了接口，才能访问到这些开放接口。 * 通过接口关联查询得到接口列表，选择需要配置的接口，点击配置按钮。 * 可以配置多个接口，可以选择全部配置、部分配置。 * 接口地址：/openapi/app/config/{1} * 请求方式：PUT * 请求参数：JSON格式 body 体中参数 ```json { "interfaceIds": [1,2,3] } ``` * 响应参数：JSON格式 响应示例： ```json { "code": 200, "msg": "success", "data": null } ``` ##### 修改有效期 * 应用的有效期是可以修改的，可以根据需要修改。 * 应用有效期过了，则该应用不能通过开放接口访问 * 接口有效期可以修改比当前有效期以前，也可以修改比当前有效期以后。 * 如果有效期修改在当前时间以前，也是运行的，则等于直接失效了。 * 接口地址：/openapi/app/expiration/{1} * 请求方式：PUT * 请求参数：JSON格式 body 体中参数 ```json { "expirationTime": "2021-01-01 00:00:00" } ``` * 响应参数：JSON格式 响应示例： ```json { "code": 200, "msg": "success", "data": null } ``` ##### 禁用应用 * 平台新创建的应用一开始是禁用状态的。需要平台认为的开启才可以使用。 * 平台也可以在之后禁用应用，禁用后该应用不能通过开放接口访问 * 接口地址：/openapi/app/disable/{1} * 请求方式：PUT * 请求参数：路径参数 * 响应参数：JSON格式 响应示例： ```json { "code": 200, "msg": "success", "data": null } ``` ##### 启用应用 * 应用处于禁用状态时，需要平台认为的开启才可以使用。 * 接口地址：/openapi/app/enable/{1} * 请求方式：PUT * 请求参数：路径参数 * 响应参数：JSON格式 响应示例： ```json { "code": 200, "msg": "success", "data": null } ``` ##### 删除应用 * 对于已经废弃的应用，平台可以通过接口删除 * 接口地址：/openapi/app * 请求方式：delete * 请求参数：路径参数 * 响应参数：JSON格式 响应示例： ```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 体中参数 ```json { "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格式 响应示例： ```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格式 响应示例： ```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格式 * 响应示例： ```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格式 ```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格式 ```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 } ``` ##### 配置接口文档 接口中需要配置给开放平台 ##### 发布接口 ##### 禁用接口 ##### 导入接口 ##### 导出接口 ##### 查询详情 ##### 查询接口列表（分页） #### 开放平台安全管理 开放平台安全校验模块负责对接车场、人行项目的安全校验，包括接口的安全校验、数据加密、数据权限校验、数据流量监控等。 ##### token生成 ##### token校验 ##### 签名方式 ##### 签名校验 ##### 接口权限校验 ##### 接口流量监控 ### 数据库设计 #### 应用管理表 #### 应用项目关联表 #### 接口管理表 #### 应用接口授权关联表 #### 安全管理redis数据结构设计 ### 数据接口列表