253 lines
6.4 KiB
Markdown
253 lines
6.4 KiB
Markdown
# 福建水务业务系统接口设计
|
||
|
||
## 目录
|
||
- [1. 接口概述](#1-接口概述)
|
||
- [2. 外部接口](#2-外部接口)
|
||
- [3. 内部接口](#3-内部接口)
|
||
- [4. 接口标准](#4-接口标准)
|
||
|
||
## 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格式响应：
|
||
|
||
```json
|
||
{
|
||
"code": 0, // 业务状态码，0表示成功，非0表示失败
|
||
"data": {}, // 响应数据
|
||
"msg": "success" // 响应消息
|
||
}
|
||
```
|
||
|
||
分页查询响应格式：
|
||
|
||
```json
|
||
{
|
||
"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协议加密传输数据
|
||
- **接口限流**：限制单位时间内的请求次数
|
||
- **访问日志**：记录所有接口调用情况 |