SKU设计
分类: 科技创建于: 6/6/2025
好的，我们来详细说明前后端接口的传值结构，包括请求（Request）和响应（Response）的JSON格式。
一、 获取商品详情接口
这是前端展示商品详情页时最核心的接口。
1. 请求 (Frontend -> Backend)
- HTTP 方法:
GET - URL 路径:
/api/products/{productId} - 路径参数:
productId: 商品的唯一标识符（例如，之前数据库products表中的id）。
示例请求 URL: GET /api/products/123
- 请求体 (Request Body): 无（GET 请求通常没有请求体）
- 请求头 (Request Headers):
Authorization: Bearer <token>(如果需要用户认证才能查看部分商品信息，或者获取个性化价格等)Accept: application/json
2. 响应 (Backend -> Frontend)
- HTTP 状态码:
200 OK: 成功获取商品详情。404 Not Found: 商品 ID 不存在。500 Internal Server Error: 服务器内部错误。
- 响应体 (Response Body): JSON 格式，包含商品的所有详细信息、变体信息和属性信息。
示例响应体 (JSON):
1{ 2 "id": 123, 3 "name": "时尚T恤", 4 "description": "纯棉材质，舒适透气，多色可选。这款T恤采用XX工艺...", 5 "brand": { 6 "id": 1, 7 "name": "品牌A" 8 }, 9 "category": { 10 "id": 5, 11 "name": "T恤", 12 "parent_category_name": "服装" 13 }, 14 "base_price": 99.00, // 商品基础价格，通常是最低SKU价格或默认价格 15 "main_image_url": "/images/tshirt_main_default.jpg", // 商品主图 16 "product_images": [ // 商品画廊图片 17 {"id": 1, "url": "/images/tshirt_gallery_1.jpg", "alt_text": "T恤正面"}, 18 {"id": 2, "url": "/images/tshirt_gallery_2.jpg", "alt_text": "T恤背面"} 19 ], 20 "custom_attributes": { // 自由属性（JSONB，描述性属性） 21 "材质": "100% 纯棉", 22 "适用季节": "夏季", 23 "领型": "圆领", 24 "袖长": "短袖", 25 "洗涤说明": "机洗，最高30°C，不可漂白" 26 }, 27 "variants": [ // 所有可购买的SKU变体列表 28 { 29 "id": 1001, // SKU变体ID 30 "sku": "TSHIRT-RED-S", // 唯一SKU编码 31 "price": 99.00, // 此SKU的价格 32 "stock": 50, // 此SKU的库存 33 "image_url": "/images/tshirt_red_s.jpg", // 此SKU特有的图片，可覆盖主图 34 "barcode": "XYZ1234567890", 35 "is_active": true, 36 "attributes": [ // 此SKU包含的属性值列表 37 {"attribute_id": 1, "attribute_name": "颜色", "attribute_value_id": 10, "attribute_value_name": "红色", "attribute_value_value": "#FF0000", "attribute_type": "color"}, 38 {"attribute_id": 2, "attribute_name": "尺码", "attribute_value_id": 20, "attribute_value_name": "S", "attribute_value_value": "S", "attribute_type": "text"} 39 ] 40 }, 41 { 42 "id": 1002, 43 "sku": "TSHIRT-RED-M", 44 "price": 109.00, 45 "stock": 30, 46 "image_url": "/images/tshirt_red_m.jpg", 47 "attributes": [ 48 {"attribute_id": 1, "attribute_name": "颜色", "attribute_value_id": 10, "attribute_value_name": "红色", "attribute_value_value": "#FF0000", "attribute_type": "color"}, 49 {"attribute_id": 2, "attribute_name": "尺码", "attribute_value_id": 21, "attribute_value_name": "M", "attribute_value_value": "M", "attribute_type": "text"} 50 ] 51 }, 52 { 53 "id": 1003, 54 "sku": "TSHIRT-BLUE-S", 55 "price": 99.00, 56 "stock": 0, // 已售罄 57 "image_url": "/images/tshirt_blue_s.jpg", 58 "attributes": [ 59 {"attribute_id": 1, "attribute_name": "颜色", "attribute_value_id": 11, "attribute_value_name": "蓝色", "attribute_value_value": "#0000FF", "attribute_type": "color"}, 60 {"attribute_id": 2, "attribute_name": "尺码", "attribute_value_id": 20, "attribute_value_name": "S", "attribute_value_value": "S", "attribute_type": "text"} 61 ] 62 } 63 // ... 更多变体 64 ], 65 "available_attributes": [ // 为前端渲染属性选择器提供的总览 66 { 67 "id": 1, 68 "name": "颜色", 69 "type": "color", 70 "values": [ // 颜色属性下所有可供选择的值（即使某些组合可能缺货） 71 {"id": 10, "display_name": "红色", "value": "#FF0000", "display_order": 1}, 72 {"id": 11, "display_name": "蓝色", "value": "#0000FF", "display_order": 2} 73 ] 74 }, 75 { 76 "id": 2, 77 "name": "尺码", 78 "type": "text", 79 "values": [ // 尺码属性下所有可供选择的值 80 {"id": 20, "display_name": "S", "value": "S", "display_order": 1}, 81 {"id": 21, "display_name": "M", "value": "M", "display_order": 2}, 82 {"id": 22, "display_name": "L", "value": "L", "display_order": 3} 83 ] 84 } 85 ] 86}
响应体字段说明：
id,name,description,base_price,main_image_url,product_images: 商品的基础信息。brand,category: 关联的品牌和分类信息（可选，可只返回ID）。custom_attributes: 存储在products表JSONB字段中的描述性属性，前端直接渲染。variants: 所有可用的 SKU 列表。前端会根据用户选择的属性来匹配这些 SKU。每个 SKU 包含了它的价格、库存、图片以及它所代表的具体属性值组合。attributes: SKU 对应的属性值列表，每个元素包含attribute_id(属性类型ID)、attribute_name(属性类型名称)、attribute_value_id(属性值ID)、attribute_value_name(属性值显示名称)、attribute_value_value(属性值实际存储值，如颜色HEX码或尺码字母) 和attribute_type(属性类型，方便前端判断渲染方式)。
available_attributes: 后端聚合出的此商品所有涉及到的可变属性类型以及每个类型下的所有可能值。这是前端渲染“颜色选择”、“尺码选择”等 UI 的核心数据。
二、 加入购物车接口
当用户在商品详情页选择了特定 SKU 并点击“加入购物车”时，前端需要将选定的 SKU 信息发送给后端。
1. 请求 (Frontend -> Backend)
- HTTP 方法:
POST - URL 路径:
/api/cart/add - 请求头 (Request Headers):
Content-Type: application/jsonAuthorization: Bearer <token>(用于识别用户身份)
- 请求体 (Request Body): JSON 格式，至少包含选定的 SKU ID 和数量。
示例请求体 (JSON):
1{ 2 "variantId": 1001, // 用户选择的SKU变体ID 3 "quantity": 1 // 用户选择的购买数量 4}
请求体字段说明：
variantId: 对应后端product_variants表中的id。这是最关键的，因为一个variantId唯一地标识了一个商品（T恤）的特定属性组合（红色 S码）。quantity: 用户希望购买的数量。
2. 响应 (Backend -> Frontend)
- HTTP 状态码:
200 OK: 成功加入购物车。400 Bad Request: 请求参数不合法（如variantId不存在，quantity小于 1）。401 Unauthorized: 未认证用户。403 Forbidden: 无权操作（例如，商品已被下架）。404 Not Found: 对应的 SKU 不存在。409 Conflict: 库存不足（例如，请求购买 5 件，但只有 3 件库存）。500 Internal Server Error: 服务器内部错误。
- 响应体 (Response Body): JSON 格式，通常包含操作结果、更新后的购物车总数或已添加的商品信息。
示例响应体 (JSON):
成功响应：
1{ 2 "success": true, 3 "message": "商品已成功加入购物车！", 4 "cartItemCount": 3, // 购物车中商品总数 5 "addedItem": { 6 "variantId": 1001, 7 "productName": "时尚T恤", 8 "sku": "TSHIRT-RED-S", 9 "price": 99.00, 10 "quantity": 1, 11 "imageUrl": "/images/tshirt_red_s.jpg" 12 } 13}
库存不足响应：
1{ 2 "success": false, 3 "message": "抱歉，库存不足。当前此商品的库存仅剩 5 件。", 4 "errorCode": "INSUFFICIENT_STOCK", 5 "availableStock": 5 6}
响应体字段说明：
success: 布尔值，表示操作是否成功。message: 给人看的提示信息。cartItemCount: （可选）购物车中商品的总数量，方便前端更新购物车图标。addedItem: （可选）返回刚刚加入购物车商品的部分信息，方便前端展示“添加成功”的浮层或通知。errorCode,availableStock: （可选）在失败时提供更多上下文信息，方便前端做更精确的错误提示。
总结
这种前后端传值结构通过将商品信息、变体信息和属性信息进行清晰地分离和聚合，实现了高度的灵活性和可扩展性。前端不需要关心后端是如何存储和管理这些复杂关系的，它只需要消费结构化的 JSON 数据，并根据其中的信息动态渲染 UI 和进行交互。