230 lines
4.3 KiB
Markdown
230 lines
4.3 KiB
Markdown
# API 响应格式规范
|
||
|
||
## 统一响应结构
|
||
|
||
所有 API 响应都遵循以下基本结构：
|
||
|
||
```typescript
|
||
interface ApiResponse<T = any> {
|
||
success: boolean; // 请求是否成功
|
||
data?: T; // 响应数据（成功时返回）
|
||
message?: string; // 提示信息（操作类接口）
|
||
error?: string; // 错误信息（失败时返回）
|
||
pagination?: Pagination; // 分页信息（列表类接口）
|
||
meta?: Meta; // 元数据（统计类接口）
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 1. 列表类接口（带分页）
|
||
|
||
### 适用接口
|
||
- `GET /api/prices/region` - 按地区查询价格
|
||
- `GET /api/prices/search` - 搜索价格数据
|
||
|
||
### 响应格式
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": [
|
||
{
|
||
"id": 1,
|
||
"price_id": "2008067775216672769",
|
||
"goods_material": "HPB300",
|
||
"goods_spec": "Φ8",
|
||
"hang_price": 3840,
|
||
...
|
||
}
|
||
],
|
||
"pagination": {
|
||
"page": 1,
|
||
"pageSize": 20,
|
||
"total": 100,
|
||
"totalPages": 5
|
||
}
|
||
}
|
||
```
|
||
|
||
### 分页对象定义
|
||
|
||
```typescript
|
||
interface Pagination {
|
||
page: number; // 当前页码（从 1 开始）
|
||
pageSize: number; // 每页记录数
|
||
total: number; // 总记录数
|
||
totalPages: number; // 总页数
|
||
}
|
||
```
|
||
|
||
### 默认值
|
||
- `page`: 1
|
||
- `pageSize`: 20
|
||
|
||
---
|
||
|
||
## 2. 统计类接口（带元数据）
|
||
|
||
### 适用接口
|
||
- `GET /api/prices/stats` - 获取价格统计
|
||
- `GET /api/prices/trend` - 获取价格趋势
|
||
|
||
### 响应格式（Stats）
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"count": 150,
|
||
"avgPrice": 3850.5,
|
||
"minPrice": 3600,
|
||
"maxPrice": 4200,
|
||
"stdDev": 150.25,
|
||
"trend": "up",
|
||
"changeRate": "+2.5%"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 响应格式（Trend）
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": [
|
||
{
|
||
"date": "2026-01-01",
|
||
"avgPrice": 3850.5,
|
||
"minPrice": 3600,
|
||
"maxPrice": 4200
|
||
},
|
||
{
|
||
"date": "2026-01-02",
|
||
"avgPrice": 3875.0,
|
||
"minPrice": 3650,
|
||
"maxPrice": 4250
|
||
}
|
||
],
|
||
"meta": {
|
||
"total": 30,
|
||
"filters": {
|
||
"region": "昆明",
|
||
"material": "HPB300",
|
||
"days": "30"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### 元数据定义
|
||
|
||
```typescript
|
||
interface Meta {
|
||
total: number; // 返回的记录总数
|
||
filters?: { // 请求的过滤条件（可选）
|
||
region?: string;
|
||
material?: string;
|
||
days?: string;
|
||
};
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 3. 操作类接口（带消息）
|
||
|
||
### 适用接口
|
||
- `POST /api/prices/import` - 导入数据
|
||
|
||
### 响应格式
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "成功导入 300 条数据",
|
||
"data": {
|
||
"imported": 300
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 4. 错误响应
|
||
|
||
### 统一错误格式
|
||
|
||
```json
|
||
{
|
||
"success": false,
|
||
"error": "错误描述信息"
|
||
}
|
||
```
|
||
|
||
### HTTP 状态码
|
||
|
||
| 状态码 | 说明 | 示例 |
|
||
|--------|------|------|
|
||
| 200 | 成功 | 数据查询成功 |
|
||
| 400 | 请求参数错误 | 缺少必填参数 |
|
||
| 404 | 资源不存在 | 数据未找到 |
|
||
| 500 | 服务器错误 | 数据库连接失败 |
|
||
|
||
---
|
||
|
||
## 5. 数据类型规范
|
||
|
||
### 价格字段
|
||
- `make_price`: `number \| null` - 钢厂价（元/吨）
|
||
- `hang_price`: `number` - 挂牌价（元/吨）
|
||
- 所有价格字段在返回时保留 2 位小数
|
||
|
||
### 日期字段
|
||
- `price_date`: `string` - ISO 8601 格式
|
||
- 统计时使用 `YYYY-MM-DD` 格式
|
||
|
||
### 分页参数
|
||
- 所有参数都是字符串类型（从 URL query 获取）
|
||
- 服务层自动转换为数字类型
|
||
|
||
---
|
||
|
||
## 6. 示例请求
|
||
|
||
### 按地区查询（带分页）
|
||
|
||
```bash
|
||
GET /api/prices/region?region=昆明&date=2026-01-05&page=1&pageSize=20
|
||
```
|
||
|
||
### 搜索价格（多条件）
|
||
|
||
```bash
|
||
GET /api/prices/search?material=HPB300&specification=Φ8&startDate=2026-01-01&endDate=2026-01-05®ion=昆明&page=1&pageSize=20
|
||
```
|
||
|
||
### 获取价格趋势
|
||
|
||
```bash
|
||
GET /api/prices/trend?region=昆明&material=HPB300&days=30
|
||
```
|
||
|
||
---
|
||
|
||
## 7. 版本历史
|
||
|
||
| 版本 | 日期 | 变更说明 |
|
||
|------|------|----------|
|
||
| 1.0 | 2026-01-05 | 初始版本，统一所有接口响应格式 |
|
||
|
||
---
|
||
|
||
## 8. 注意事项
|
||
|
||
1. **分页一致性**：所有列表类接口必须返回 `pagination` 对象
|
||
2. **数字精度**：价格字段统一保留 2 位小数
|
||
3. **空值处理**：可选字段为空时返回 `null`，不返回 `undefined`
|
||
4. **错误消息**：错误消息使用中文，简洁明确
|
||
5. **时区处理**：所有日期时间统一使用 `+08:00` 时区
|