484 lines
10 KiB
Markdown
484 lines
10 KiB
Markdown
# 牛只数据管理 API 测试文档
|
||
|
||
## 服务器信息
|
||
- **服务器地址**: 119.45.30.82
|
||
- **端口**: 12240
|
||
- **基础URL**: `http://119.45.30.82:12240`
|
||
- **API基础路径**: `/api/cattle-data`
|
||
|
||
---
|
||
|
||
## 1. 检查服务是否正常运行
|
||
|
||
### 方法1: 浏览器访问
|
||
```
|
||
http://119.45.30.82:12240/swagger-ui.html
|
||
```
|
||
如果能看到 Swagger UI 界面，说明服务正常运行。
|
||
|
||
### 方法2: 使用 curl 命令
|
||
```bash
|
||
curl http://119.45.30.82:12240/api/cattle-data
|
||
```
|
||
|
||
### 方法3: 检查服务状态（在服务器上）
|
||
```bash
|
||
# 检查端口是否监听
|
||
netstat -tlnp | grep 8080
|
||
|
||
# 或使用 ss 命令
|
||
ss -tlnp | grep 8080
|
||
|
||
# 检查进程
|
||
ps aux | grep cattletends
|
||
```
|
||
|
||
---
|
||
|
||
## 2. API 接口测试
|
||
|
||
### 2.1 获取所有牛只数据
|
||
|
||
**接口**: `GET /api/cattle-data`
|
||
|
||
**测试方法1: 浏览器直接访问**
|
||
```
|
||
http://119.45.30.82:12240/api/cattle-data
|
||
```
|
||
|
||
**测试方法2: 使用 curl**
|
||
```bash
|
||
curl -X GET "http://119.45.30.82:12240/api/cattle-data"
|
||
```
|
||
|
||
**测试方法3: 使用 Postman**
|
||
- Method: GET
|
||
- URL: `http://119.45.30.82:12240/api/cattle-data`
|
||
|
||
---
|
||
|
||
### 2.2 按省份筛选数据
|
||
|
||
**接口**: `GET /api/cattle-data?province=安徽省`
|
||
|
||
**测试方法1: 浏览器**
|
||
```
|
||
http://119.45.30.82:12240/api/cattle-data?province=安徽省
|
||
```
|
||
|
||
**测试方法2: curl**
|
||
```bash
|
||
curl -X GET "http://119.45.30.82:12240/api/cattle-data?province=安徽省"
|
||
```
|
||
|
||
---
|
||
|
||
### 2.3 按品种筛选数据
|
||
|
||
**接口**: `GET /api/cattle-data?type=鲁西牛`
|
||
|
||
**测试方法1: 浏览器**
|
||
```
|
||
http://119.45.30.82:12240/api/cattle-data?type=鲁西牛
|
||
```
|
||
|
||
**测试方法2: curl**
|
||
```bash
|
||
curl -X GET "http://119.45.30.82:12240/api/cattle-data?type=鲁西牛"
|
||
```
|
||
|
||
---
|
||
|
||
### 2.4 根据ID获取单条数据
|
||
|
||
**接口**: `GET /api/cattle-data/{id}`
|
||
|
||
**示例**: 获取ID为1的数据
|
||
|
||
**测试方法1: 浏览器**
|
||
```
|
||
http://119.45.30.82:12240/api/cattle-data/1
|
||
```
|
||
|
||
**测试方法2: curl**
|
||
```bash
|
||
curl -X GET "http://119.45.30.82:12240/api/cattle-data/1"
|
||
```
|
||
|
||
---
|
||
|
||
### 2.5 创建牛只数据
|
||
|
||
**接口**: `POST /api/cattle-data`
|
||
|
||
**请求头**:
|
||
```
|
||
Content-Type: application/json
|
||
```
|
||
|
||
**请求体示例**:
|
||
```json
|
||
{
|
||
"type": "鲁西牛",
|
||
"province": "安徽省",
|
||
"location": "安徽淮南市",
|
||
"price": 25.50,
|
||
"provincePrice": 24.80,
|
||
"inventory23th": 1000,
|
||
"slaughter23th": 500,
|
||
"inventory24th": 1200,
|
||
"slaughter24th": 600,
|
||
"inventory25th": 1300,
|
||
"slaughter25th": 650
|
||
}
|
||
```
|
||
|
||
**测试方法1: curl**
|
||
```bash
|
||
curl -X POST "http://119.45.30.82:12240/api/cattle-data" \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"type": "鲁西牛",
|
||
"province": "安徽省",
|
||
"location": "安徽淮南市",
|
||
"price": 25.50
|
||
}'
|
||
```
|
||
|
||
**测试方法2: Postman**
|
||
- Method: POST
|
||
- URL: `http://119.45.30.82:12240/api/cattle-data`
|
||
- Headers: `Content-Type: application/json`
|
||
- Body (raw JSON): 使用上面的 JSON 示例
|
||
|
||
---
|
||
|
||
### 2.6 更新牛只数据
|
||
|
||
**接口**: `PUT /api/cattle-data/{id}`
|
||
|
||
**示例**: 更新ID为1的数据
|
||
|
||
**测试方法: curl**
|
||
```bash
|
||
curl -X PUT "http://119.45.30.82:12240/api/cattle-data/1" \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"type": "鲁西牛",
|
||
"province": "安徽省",
|
||
"location": "安徽淮南市",
|
||
"price": 26.00
|
||
}'
|
||
```
|
||
|
||
---
|
||
|
||
### 2.7 删除牛只数据
|
||
|
||
**接口**: `DELETE /api/cattle-data/{id}`
|
||
|
||
**示例**: 删除ID为1的数据
|
||
|
||
**测试方法: curl**
|
||
```bash
|
||
curl -X DELETE "http://119.45.30.82:12240/api/cattle-data/1"
|
||
```
|
||
|
||
---
|
||
|
||
### 2.8 批量导入数据（Excel文件）
|
||
|
||
**接口**: `POST /api/cattle-data/import`
|
||
|
||
**测试方法1: curl**
|
||
```bash
|
||
curl -X POST "http://119.45.30.82:12240/api/cattle-data/import" \
|
||
-F "file=@/path/to/your/file.xlsx"
|
||
```
|
||
|
||
**测试方法2: Postman**
|
||
- Method: POST
|
||
- URL: `http://119.45.30.82:12240/api/cattle-data/import`
|
||
- Body: form-data
|
||
- Key: `file` (类型选择 File)
|
||
- Value: 选择你的 Excel 文件
|
||
|
||
**注意**: Excel 文件格式要求：
|
||
- 第一行：表头（时间、产品/品种、所在产地、活牛价格(元/斤)）
|
||
- 从第二行开始：数据行
|
||
|
||
---
|
||
|
||
### 2.9 获取所有省份数据（15个省份）
|
||
|
||
**接口**: `GET /api/cattle-data/provinces`
|
||
|
||
**说明**: 返回所有省份的存栏出栏数据和省份均价
|
||
|
||
**测试方法1: 浏览器**
|
||
```
|
||
http://119.45.30.82:12240/api/cattle-data/provinces
|
||
```
|
||
|
||
**测试方法2: curl**
|
||
```bash
|
||
curl -X GET "http://119.45.30.82:12240/api/cattle-data/provinces"
|
||
```
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "success",
|
||
"data": [
|
||
{
|
||
"id": 1,
|
||
"province": "内蒙古",
|
||
"provincePrice": 14.01,
|
||
"inventory23th": 948,
|
||
"slaughter23th": 464,
|
||
"inventory24th": 938,
|
||
"slaughter24th": 470,
|
||
"inventory25th": 1032,
|
||
"slaughter25th": 520,
|
||
"createTime": "2025-11-27T10:00:00",
|
||
"upTime": "2025-11-27T10:00:00"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 2.10 根据省份名称获取省份数据
|
||
|
||
**接口**: `GET /api/cattle-data/provinces/{province}`
|
||
|
||
**说明**: 根据省份名称查询单个省份的存栏出栏数据
|
||
|
||
**测试方法1: 浏览器**
|
||
```
|
||
http://119.45.30.82:12240/api/cattle-data/provinces/内蒙古
|
||
```
|
||
|
||
**测试方法2: curl**
|
||
```bash
|
||
curl -X GET "http://119.45.30.82:12240/api/cattle-data/provinces/内蒙古"
|
||
```
|
||
|
||
---
|
||
|
||
### 2.11 获取全国总量数据（全国存出栏）
|
||
|
||
**接口**: `GET /api/cattle-data/national`
|
||
|
||
**说明**: 自动从省份数据表计算并返回全国年份存栏和出栏总量数据
|
||
|
||
**测试方法1: 浏览器**
|
||
```
|
||
http://119.45.30.82:12240/api/cattle-data/national
|
||
```
|
||
|
||
**测试方法2: curl**
|
||
```bash
|
||
curl -X GET "http://119.45.30.82:12240/api/cattle-data/national"
|
||
```
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "success",
|
||
"data": {
|
||
"id": 1,
|
||
"nationalInventory23th": 3042,
|
||
"nationalSlaughter23th": 7251,
|
||
"nationalInventory24th": 2802,
|
||
"nationalSlaughter24th": 7304,
|
||
"nationalInventory25th": 2587,
|
||
"nationalSlaughter25th": 0,
|
||
"createTime": "2025-11-27T10:00:00",
|
||
"upTime": "2025-11-27T10:00:00"
|
||
}
|
||
}
|
||
```
|
||
|
||
**说明**:
|
||
- 如果数据不存在，会自动从 `cattleprovince` 表计算并创建
|
||
- 全国总量 = 15个省份对应字段的总和
|
||
|
||
---
|
||
|
||
### 2.12 重新计算全国总量数据
|
||
|
||
**接口**: `POST /api/cattle-data/national/recalculate`
|
||
|
||
**说明**: 根据 `cattleprovince` 表中的所有省份数据重新计算全国总量
|
||
|
||
**测试方法: curl**
|
||
```bash
|
||
curl -X POST "http://119.45.30.82:12240/api/cattle-data/national/recalculate"
|
||
```
|
||
|
||
**使用场景**:
|
||
- 直接修改了数据库中的省份数据后，需要重新计算全国总量
|
||
- 确保全国总量数据与省份数据保持一致
|
||
|
||
---
|
||
|
||
## 3. 使用 Swagger UI 测试（推荐）
|
||
|
||
### 访问 Swagger UI
|
||
```
|
||
http://119.45.30.82:12240/swagger-ui.html
|
||
```
|
||
|
||
在 Swagger UI 中：
|
||
1. 可以看到所有接口的详细文档
|
||
2. 可以直接在页面上测试接口
|
||
3. 可以查看请求和响应示例
|
||
4. 支持在线测试所有接口
|
||
|
||
---
|
||
|
||
## 4. 响应格式说明
|
||
|
||
所有接口返回统一的响应格式：
|
||
|
||
**成功响应**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "操作成功",
|
||
"data": {
|
||
// 具体数据
|
||
}
|
||
}
|
||
```
|
||
|
||
**错误响应**:
|
||
```json
|
||
{
|
||
"code": 400,
|
||
"message": "错误信息",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 5. 快速测试脚本
|
||
|
||
### 测试脚本 (test_api.sh)
|
||
```bash
|
||
#!/bin/bash
|
||
|
||
BASE_URL="http://119.45.30.82:12240/api/cattle-data"
|
||
|
||
echo "=== 测试1: 获取所有数据 ==="
|
||
curl -X GET "${BASE_URL}"
|
||
|
||
echo -e "\n\n=== 测试2: 按省份筛选 ==="
|
||
curl -X GET "${BASE_URL}?province=安徽省"
|
||
|
||
echo -e "\n\n=== 测试3: 按品种筛选 ==="
|
||
curl -X GET "${BASE_URL}?type=鲁西牛"
|
||
|
||
echo -e "\n\n=== 测试4: 创建数据 ==="
|
||
curl -X POST "${BASE_URL}" \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"type": "测试品种",
|
||
"province": "测试省",
|
||
"location": "测试市",
|
||
"price": 20.00
|
||
}'
|
||
|
||
echo -e "\n\n=== 测试完成 ==="
|
||
```
|
||
|
||
**使用方法**:
|
||
```bash
|
||
chmod +x test_api.sh
|
||
./test_api.sh
|
||
```
|
||
|
||
---
|
||
|
||
## 6. 常见问题排查
|
||
|
||
### 6.1 连接超时
|
||
- 检查服务器防火墙是否开放 8080 端口
|
||
- 检查服务器是否正常运行
|
||
- 检查网络连接
|
||
|
||
### 6.2 404 错误
|
||
- 确认 URL 路径正确
|
||
- 确认服务已启动
|
||
- 检查 context-path 配置
|
||
|
||
### 6.3 500 错误
|
||
- 查看服务器日志
|
||
- 检查数据库连接
|
||
- 检查请求参数格式
|
||
|
||
### 6.4 查看服务日志
|
||
```bash
|
||
# 如果使用启动脚本
|
||
tail -f log.out
|
||
|
||
# 或查看 Spring Boot 日志
|
||
tail -f logs/spring.log
|
||
```
|
||
|
||
---
|
||
|
||
## 7. 接口列表汇总
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| GET | `/api/cattle-data` | 获取所有数据（支持 province、type 参数筛选） |
|
||
| GET | `/api/cattle-data/{id}` | 根据ID获取单条数据 |
|
||
| POST | `/api/cattle-data` | 创建新数据 |
|
||
| PUT | `/api/cattle-data/{id}` | 更新数据 |
|
||
| DELETE | `/api/cattle-data/{id}` | 删除数据 |
|
||
| POST | `/api/cattle-data/import` | 批量导入Excel文件 |
|
||
| POST | `/api/cattle-data/import-province` | 批量导入省份存栏出栏及均价（Excel） |
|
||
| GET | `/api/cattle-data/provinces` | 获取所有15个省份的存栏出栏数据和省份均价 |
|
||
| GET | `/api/cattle-data/provinces/{province}` | 根据省份名称查询单个省份的存栏出栏数据 |
|
||
| GET | `/api/cattle-data/national` | 获取全国总量数据（自动从省份数据表计算） |
|
||
| POST | `/api/cattle-data/national/recalculate` | 重新计算全国总量数据 |
|
||
|
||
---
|
||
|
||
## 8. 测试建议
|
||
|
||
1. **先测试 GET 接口**：确认服务正常运行
|
||
2. **测试 POST 创建**：添加测试数据
|
||
3. **测试 PUT 更新**：修改刚创建的数据
|
||
4. **测试 DELETE 删除**：清理测试数据
|
||
5. **测试导入功能**：使用真实的 Excel 文件
|
||
|
||
---
|
||
|
||
## 9. 性能测试
|
||
|
||
### 使用 Apache Bench (ab) 进行压力测试
|
||
```bash
|
||
# 安装 ab
|
||
yum install httpd-tools -y # CentOS
|
||
apt-get install apache2-utils -y # Ubuntu
|
||
|
||
# 测试 GET 接口
|
||
ab -n 1000 -c 10 http://119.45.30.82:12240/api/cattle-data
|
||
|
||
# 参数说明：
|
||
# -n: 总请求数
|
||
# -c: 并发数
|
||
```
|
||
|
||
---
|
||
|
||
祝测试顺利！如有问题，请查看服务器日志或联系技术支持。
|
||
|