bun_orders_lite/api.md

API 接口文檔

訂單管理系統 API 接口文檔

1. 添加訂單

接口信息

• 接口路徑: POST /api/orders
• 功能描述: 添加新的訂單記錄
• 請求格式: JSON
• 響應格式: JSON

請求參數

參數名	類型	必填	說明
customer_name	String	是	客戶姓名
product_name	String	是	商品名稱
quantity	Number	是	商品數量，必須大於0
price	Number	是	商品單價，必須大於0
status	String	否	訂單狀態，默認為"pending"

響應參數

參數名	類型	說明
success	Boolean	請求是否成功
message	String	響應消息
data	Object	返回的數據對象
data.id	Number	新增訂單的ID
data.customer_name	String	客戶姓名
data.product_name	String	商品名稱
data.quantity	Number	商品數量
data.price	Number	商品單價
data.status	String	訂單狀態
data.created_at	String	創建時間

成功響應示例

{
  "success": true,
  "message": "訂單創建成功",
  "data": {
    "id": 6,
    "customer_name": "陳八",
    "product_name": "HomePod Mini",
    "quantity": 1,
    "price": 99.99,
    "status": "pending",
    "created_at": "2023-12-01 10:30:00"
  }
}

失敗響應示例

{
  "success": false,
  "message": "缺少必需字段或字段值無效"
}

Curl 請求示例

curl -X POST http://localhost:3000/api/orders \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "customer_name": "陳八",
    "product_name": "HomePod Mini",
    "quantity": 1,
    "price": 99.99,
    "status": "pending"
  }'

2. 查詢訂單列表

接口信息

• 接口路徑: GET /api/orders
• 功能描述: 查詢訂單列表，支持條件篩選和分頁
• 請求格式: Query String
• 響應格式: JSON

查詢參數

參數名	類型	必填	默認值	說明
page	Number	否	1	頁碼
pageSize	Number	否	10	每頁顯示數量
customerName	String	否	-	客戶姓名模糊匹配
productName	String	否	-	商品名稱模糊匹配
status	String	否	-	訂單狀態精確匹配

響應參數

參數名	類型	說明
success	Boolean	請求是否成功
data	Object	返回的數據對象
data.orders	Array	訂單列表
data.pagination	Object	分頁信息
data.pagination.page	Number	當前頁碼
data.pagination.pageSize	Number	每頁顯示數量
data.pagination.total	Number	總記錄數
data.pagination.totalPages	Number	總頁數

成功響應示例

{
  "success": true,
  "data": {
    "orders": [
      {
        "id": 1,
        "customer_name": "張三",
        "product_name": "iPhone 15",
        "quantity": 1,
        "price": 999.99,
        "status": "completed",
        "created_at": "2023-12-01 10:30:00"
      },
      {
        "id": 2,
        "customer_name": "李四",
        "product_name": "MacBook Pro",
        "quantity": 1,
        "price": 1999.99,
        "status": "pending",
        "created_at": "2023-12-01 10:25:00"
      }
    ],
    "pagination": {
      "page": 1,
      "pageSize": 10,
      "total": 2,
      "totalPages": 1
    }
  }
}

Curl 請求示例

查詢所有訂單（默認分頁）

curl "http://localhost:3000/api/orders"

分頁查詢

curl "http://localhost:3000/api/orders?page=1&pageSize=5"

按客戶姓名查詢

curl "http://localhost:3000/api/orders?customerName=張"

按商品名稱查詢

curl "http://localhost:3000/api/orders?productName=iPhone"

按狀態查詢

curl "http://localhost:3000/api/orders?status=pending"

組合條件查詢

curl "http://localhost:3000/api/orders?page=1&pageSize=10&customerName=張&status=completed"

3. 錯誤碼說明

錯誤碼	狀態碼	說明
400	400 Bad Request	請求參數錯誤
404	404 Not Found	路由不存在
500	500 Internal Server Error	服務器內部錯誤

4. 公共響應格式

所有接口響應都遵循以下格式：

{
  "success": true/false,
  "message": "響應消息",
  "data": {}
}

• success: 請求是否成功的布爾值
• message: 響應消息，成功時可選，失敗時必填
• data: 返回的業務數據，根據接口不同而異