6.4 KiB
6.4 KiB
福建水务业务系统接口设计
目录
1. 接口概述
福建水务业务系统提供丰富的接口，用于与外部系统集成以及系统内部各模块间的数据交换。接口设计遵循标准化、安全性、可扩展性的原则，基于RuoYi-Vue-Pro框架采用RESTful风格设计，支持JSON数据格式。
1.1 接口设计原则
- 统一性：所有接口遵循统一的设计规范和数据格式
- 安全性：接口通过认证授权、参数校验等机制保障安全
- 可维护性：接口文档完善，便于维护和升级
- 兼容性：接口设计考虑版本兼容，支持平滑升级
- 性能优化：接口设计考虑性能，支持缓存、分页等机制
1.2 RESTful API规范
系统API接口采用RESTful风格设计，主要规范如下：
1.2.1 资源命名
- 使用名词复数表示资源集合，如
/users、/meters - 使用资源ID标识特定资源，如
/users/1、/meters/123 - 资源层级关系通过路径嵌套表示，如
/users/1/meters
1.2.2 HTTP方法
- GET：获取资源
- POST：创建资源
- PUT：更新资源（全量更新）
- PATCH：部分更新资源
- DELETE：删除资源
1.2.3 状态码
- 200 OK：请求成功
- 201 Created：资源创建成功
- 400 Bad Request：请求参数错误
- 401 Unauthorized：未授权
- 403 Forbidden：权限不足
- 404 Not Found：资源不存在
- 500 Internal Server Error：服务器内部错误
1.2.4 响应格式
系统统一采用以下JSON格式响应：
{
"code": 0, // 业务状态码，0表示成功，非0表示失败
"data": {}, // 响应数据
"msg": "success" // 响应消息
}
分页查询响应格式：
{
"code": 0,
"data": {
"list": [], // 数据列表
"total": 100, // 总记录数
"pageNum": 1, // 当前页码
"pageSize": 10 // 每页记录数
},
"msg": "success"
}
1.3 接口文档
系统使用Knife4j（基于Swagger）自动生成API文档，文档地址为：http://{系统地址}/doc.html。
主要特点：
- 在线接口文档：支持在线查看接口定义
- 接口调试：支持在线调试接口
- 文档导出：支持导出OpenAPI规范文档
- 权限控制：支持对接口文档的访问控制
2. 外部接口
2.1 与银行接口
2.1.1 银行代扣接口
功能描述：通过银行系统自动从用户账户中扣除水费。
接口规范：
- 接口方式：文件交换或WebService
- 数据格式：文本文件或XML
- 交换频率：每日或实时
2.1.2 银行实时缴费接口
功能描述：用户在银行柜台、网上银行或手机银行实时缴纳水费。
接口规范：
- 接口方式：WebService或HTTP接口
- 数据格式：XML或JSON
- 交换频率：实时
2.2 支付宝接口
功能描述：用户通过支付宝缴纳水费。
接口规范：
- 接口方式：HTTP接口
- 数据格式：JSON
- 交换频率：实时
2.3 微信支付接口
功能描述：用户通过微信支付缴纳水费。
接口规范：
- 接口方式：HTTP接口
- 数据格式：XML或JSON
- 交换频率：实时
2.4 短信接口
功能描述：向用户发送各类业务通知短信。
接口规范：
- 接口方式：HTTP接口
- 数据格式：JSON
- 交换频率：实时
2.5 物联网集抄平台接口
功能描述：与物联网集抄平台交互，获取智能水表数据。
接口规范：
- 接口方式：HTTP接口或WebService
- 数据格式：JSON或XML
- 交换频率：定时或实时
3. 内部接口
3.1 用户接口
3.1.1 用户信息查询接口
功能描述：查询用户基本信息。
接口规范：
- 请求方式：GET
- 请求路径：/api/users/{userId}
- 返回格式：JSON
3.1.2 用户信息更新接口
功能描述：更新用户基本信息。
接口规范：
- 请求方式：PUT
- 请求路径：/api/users/{userId}
- 请求/返回格式：JSON
3.2 水表接口
3.2.1 水表信息查询接口
功能描述：查询水表基本信息。
接口规范：
- 请求方式：GET
- 请求路径：/api/meters/{meterId}
- 返回格式：JSON
3.2.2 水表读数上传接口
功能描述：上传水表读数。
接口规范：
- 请求方式：POST
- 请求路径：/api/meters/{meterId}/readings
- 请求/返回格式：JSON
3.3 账单接口
3.3.1 账单查询接口
功能描述：查询用户账单信息。
接口规范：
- 请求方式：GET
- 请求路径：/api/users/{userId}/bills
- 返回格式：JSON
3.3.2 缴费接口
功能描述：处理用户缴费。
接口规范：
- 请求方式：POST
- 请求路径：/api/bills/{billId}/payments
- 请求/返回格式：JSON
3.4 工单接口
3.4.1 工单创建接口
功能描述：创建业务工单。
接口规范：
- 请求方式：POST
- 请求路径：/api/workorders
- 请求/返回格式：JSON
3.4.2 工单状态更新接口
功能描述：更新工单处理状态。
接口规范：
- 请求方式：PUT
- 请求路径：/api/workorders/{workorderId}/status
- 请求/返回格式：JSON
4. 接口标准
4.1 接口协议
系统接口主要采用以下协议：
- RESTful API：适用于系统内部模块间的交互以及移动应用等轻量级客户端
- WebService：适用于与外部系统的集成，特别是银行等传统机构
- 消息队列：适用于异步处理的场景，如批量数据处理、通知推送等
4.2 数据格式
接口数据主要采用以下格式：
- JSON：主要用于RESTful API接口，结构简单清晰，适合Web应用
- XML：主要用于WebService接口，兼容性好，适合与传统系统对接
- 文本文件：主要用于批量数据交换，如银行代扣文件等
4.3 接口安全
接口安全采用以下机制：
- 令牌认证：使用JWT(JSON Web Token)进行身份认证
- 签名验证：请求参数签名，确保数据完整性
- IP白名单：限制接口调用者的IP地址
- 传输加密：使用HTTPS协议加密传输数据
- 接口限流：限制单位时间内的请求次数
- 访问日志：记录所有接口调用情况