商品详情页 API 替换指南

概述

本文档说明如何将商品详情页的模拟数据替换为真实的后端API接口。商品详情页包含商品图片、商品信息、商品特点等模块，所有数据都来自酒谷商品主数据表。

核心API接口

1. 获取商品详情

当前模拟接口：

// api/product.js
export const getProductDetail = async (productId) => {
    // 模拟实现
}

需要替换为真实接口：

// 真实API调用示例
export const getProductDetail = async (productId) => {
    try {
        const response = await uni.request({
            url: `${API_BASE_URL}/api/products/${productId}`,
            method: 'GET',
            header: {
                'Authorization': `Bearer ${getToken()}`,
                'Content-Type': 'application/json'
            }
        })
        
        if (response.statusCode === 200) {
            return {
                success: true,
                message: '商品详情获取成功',
                data: response.data.data
            }
        } else {
            throw new Error(response.data.message || '商品详情获取失败')
        }
    } catch (error) {
        console.error('获取商品详情失败:', error)
        return {
            success: false,
            message: error.message || '商品详情获取失败',
            data: null
        }
    }
}

接口地址： GET /api/products/{productId}

返回数据结构：

{
    "success": true,
    "message": "商品详情获取成功",
    "data": {
        "id": "product_jg_001",
        "name": "酒谷陈酿",
        "price": 888.00,
        "points": 400,
        "mainImage": "https://...",
        "packageImage": "https://...",
        "qualityImage": "https://...",
        "qualityDescription": "采用高温制曲、二次投料...",
        
        // 商品特点字段 - 从酒谷商品主数据表获取
        "material": "水、高粱、小麦",
        "alcohol": "53%vol.",
        "origin": "贵州省仁怀市茅台镇",
        "type": "酱香型白酒",
        "capacity": "500ml",
        "storage": "干燥、通风、阴凉的环境条件下存储",
        "company": "贵州茅台酒股份有限公司"
    }
}

2. 获取商品图片

当前模拟接口：

// api/product.js
export const getProductImages = async (productId, imageType = 2) => {
    // 模拟实现
}

需要替换为真实接口：

// 真实API调用示例
export const getProductImages = async (productId, imageType = 2) => {
    try {
        const response = await uni.request({
            url: `${API_BASE_URL}/api/products/${productId}/images`,
            method: 'GET',
            data: {
                imageType: imageType, // 图片分类==2 (商品详情图片)
                limit: 6 // 限制最多6张图片
            },
            header: {
                'Authorization': `Bearer ${getToken()}`,
                'Content-Type': 'application/json'
            }
        })
        
        if (response.statusCode === 200) {
            return {
                success: true,
                message: '商品图片获取成功',
                data: {
                    images: response.data.data.images,
                    total: response.data.data.total
                }
            }
        } else {
            throw new Error(response.data.message || '商品图片获取失败')
        }
    } catch (error) {
        console.error('获取商品图片失败:', error)
        return {
            success: false,
            message: error.message || '商品图片获取失败',
            data: {
                images: [],
                total: 0
            }
        }
    }
}

接口地址： GET /api/products/{productId}/images?imageType=2&limit=6

返回数据结构：

{
    "success": true,
    "message": "商品图片获取成功",
    "data": {
        "images": [
            {
                "id": "img_001",
                "url": "https://...",
                "type": 2,
                "sort": 1,
                "description": "商品主图"
            }
        ],
        "total": 6
    }
}

数据来源说明

商品主数据表字段映射

前端字段	数据库字段	说明	示例值
`name`	`product_name`	商品名称	茅台飞天 53° 500ml
`price`	`product_price`	商品价格	888.00
`material`	`raw_material`	原料	水、高粱、小麦
`alcohol`	`alcohol_content`	酒精度数	53%vol.
`origin`	`production_place`	厂址	贵州省仁怀市茅台镇
`type`	`wine_type`	酒品类型	酱香型白酒
`capacity`	`net_content`	容量	500ml
`storage`	`storage_advice`	储存条件	干燥、通风、阴凉的环境条件下存储
`company`	`company_name`	公司	贵州茅台酒股份有限公司

图片地址表字段映射

前端字段	数据库字段	说明	筛选条件
`url`	`image_url`	图片URL地址	-
`type`	`image_category`	图片分类	= 2 (商品详情图片)
`sort`	`sort_order`	排序权重	ASC
`productId`	`product_code`	商品编码	= 当前商品ID

替换步骤

步骤1：配置API基础地址

在 api/config.js 中配置真实的后端API地址：

// api/config.js
export const API_CONFIG = {
    BASE_URL: 'http://localhost:8080', // 替换为真实后端地址
    TIMEOUT: 10000,
    HEADERS: {
        'Content-Type': 'application/json'
    }
}

步骤2：替换模拟接口

将 api/product.js 中的模拟实现替换为真实API调用：

// 替换前
export const getProductDetail = async (productId) => {
    await delay(600) // 删除模拟延迟
    // 删除模拟数据逻辑
    // 添加真实API调用
}

// 替换后
export const getProductDetail = async (productId) => {
    try {
        const response = await uni.request({
            url: `${API_CONFIG.BASE_URL}/api/products/${productId}`,
            method: 'GET',
            timeout: API_CONFIG.TIMEOUT,
            header: {
                ...API_CONFIG.HEADERS,
                'Authorization': `Bearer ${getToken()}`
            }
        })
        
        // 处理响应数据
        return handleApiResponse(response)
    } catch (error) {
        return handleApiError(error)
    }
}

步骤3：更新错误处理

使用统一的错误处理机制：

// utils/api.js
export const handleApiResponse = (response) => {
    if (response.statusCode >= 200 && response.statusCode < 300) {
        return {
            success: true,
            message: response.data.message || '请求成功',
            data: response.data.data
        }
    } else {
        throw new Error(response.data.message || `请求失败: ${response.statusCode}`)
    }
}

export const handleApiError = (error) => {
    console.error('API请求失败:', error)
    return {
        success: false,
        message: error.message || '网络请求失败',
        data: null
    }
}

步骤4：测试接口

确保后端服务正常运行
测试商品详情接口：GET /api/products/{productId}
测试商品图片接口：GET /api/products/{productId}/images?imageType=2&limit=6
验证返回数据结构是否符合前端要求

注意事项

1. 图片数量限制

商品详情页最多显示6张图片
通过 limit=6 参数控制
前端使用 .slice(0, 6) 作为备用限制

2. 图片分类筛选

商品详情图片的 imageType 必须为 2
后端需要根据此条件筛选图片

3. 数据完整性

确保所有必需字段都有值
对于可选字段，提供合理的默认值
处理空值或null的情况

4. 性能优化

图片使用CDN加速
实现图片懒加载
考虑图片压缩和格式优化

5. 错误处理

网络错误：显示重试按钮
数据错误：显示默认内容
权限错误：跳转到登录页

测试清单

商品详情接口正常返回
商品图片接口正常返回
图片数量限制为6张
所有商品特点字段正确显示
错误情况处理正常
加载状态显示正常
页面跳转功能正常

总结

完成以上替换后，商品详情页将从模拟数据切换到真实的后端API，实现数据的动态获取和展示。确保在替换过程中保持前端界面的稳定性和用户体验的一致性。

PRODUCT_API_REPLACEMENT.md 8.5 KB Постоянная ссылка История Исходник