cattleData/backend/API_TEST.md

# 牛只数据管理 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: 并发数
```

---

祝测试顺利！如有问题，请查看服务器日志或联系技术支持。