steel_prices_service/docs/API_RESPONSE_FORMAT.md

API 响应格式规范

统一响应结构

所有 API 响应都遵循以下基本结构：

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 - 搜索价格数据

响应格式

{
  "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
  }
}

分页对象定义

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）

{
  "success": true,
  "data": {
    "count": 150,
    "avgPrice": 3850.5,
    "minPrice": 3600,
    "maxPrice": 4200,
    "stdDev": 150.25,
    "trend": "up",
    "changeRate": "+2.5%"
  }
}

响应格式（Trend）

{
  "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"
    }
  }
}

元数据定义

interface Meta {
  total: number;           // 返回的记录总数
  filters?: {              // 请求的过滤条件（可选）
    region?: string;
    material?: string;
    days?: string;
  };
}

---

3. 操作类接口（带消息）

适用接口

• POST /api/prices/import - 导入数据

响应格式

{
  "success": true,
  "message": "成功导入 300 条数据",
  "data": {
    "imported": 300
  }
}

---

4. 错误响应

统一错误格式

{
  "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. 示例请求

按地区查询（带分页）

GET /api/prices/region?region=昆明&date=2026-01-05&page=1&pageSize=20

搜索价格（多条件）

GET /api/prices/search?material=HPB300&specification=Φ8&startDate=2026-01-01&endDate=2026-01-05&region=昆明&page=1&pageSize=20

获取价格趋势

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 时区