商品详情接口 | DouPHP 开发手册 | 文档中心 | DouPHP企业建站系统

商品详情接口

简介

本文件面向电商应用开发者，提供“商品详情获取”功能的完整 API 文档。内容涵盖：

HTTP 方法与 URL 路径、参数说明
商品完整信息返回结构（基本信息、详细描述、规格属性、图片集、价格信息等）
关联数据加载（品牌、分类、优惠券等）
附加功能（浏览量统计、收藏状态检查）
请求与响应示例（覆盖不同商品类型展示）

项目结构

本项目采用模块化分层设计：API 控制器负责路由与入参校验，服务层封装业务逻辑，模型层负责数据访问与格式化。商品详情能力由产品模块的 API 控制器与服务共同实现，并复用前台服务以统一数据组装。

graph TB
Client["客户端"] --> API["API 路由<br/>/api/?route=product"]
API --> Ctrl["ProductController<br/>show/index/attribute_list"]
Ctrl --> Svc["ProductService<br/>buildProductShowData / buildApiAttributeData"]
Svc --> Model["Product 模型<br/>findPublishedById / findApiAttributeBase"]
Svc --> Brand["Brand 模型<br/>品牌信息"]
Svc --> Pricing["PricingService<br/>销售价计算"]
Svc --> Attach["附件/相册<br/>gallery/galleryFirst"]
Svc --> Fav["Favorites 模块<br/>收藏状态"]

图表来源

api/route/product.php:31-34
api/controller/product/ProductController.php:87-113
front/service/product/ProductService.php:210-258
front/model/product/Product.php:167-170

章节来源

api/route/product.php:15-47
api/controller/product/ProductController.php:15-154

核心组件

API 控制器：ProductController 暴露商品列表、详情与属性选择后的价格计算接口；ItemController 提供条目详情（用于非商品类内容）。
服务层：ProductService 负责商品详情数据组装、价格计算、图片集与收藏态、品牌信息加载等。
模型层：Product 提供上架商品查询、基础字段读取、分类/品牌关联等。

章节来源

api/controller/product/ProductController.php:32-113
front/service/product/ProductService.php:35-59
front/model/product/Product.php:36-57

架构总览

商品详情请求从 API 路由进入 ProductController::show，调用 ProductService::buildProductShowData 组装详情数据，包括：

商品主体信息（标题、描述、主图、自定义属性等）
价格体系（原价、销售价、积分换算）
图片集（相册首图与全量图集）
品牌信息（可选）
收藏状态（可选）
配置开关（如是否开启下单入口）

sequenceDiagram
participant C as "客户端"
participant R as "API 路由"
participant Ctrl as "ProductController"
participant Svc as "ProductService"
participant M as "Product 模型"
participant P as "PricingService"
participant F as "Favorites 模块"
participant B as "Brand 模型"
C->>R : GET /api/?route=product/show?id={id}
R->>Ctrl : show(request)
Ctrl->>Svc : buildProductShowData(id, userId)
Svc->>M : findPublishedById(id)
M-->>Svc : 商品模型
Svc->>P : salePrice("product", id, userId)
P-->>Svc : 销售价信息
Svc->>F : getFavoritesState("product", id, userId)
F-->>Svc : 收藏状态
Svc->>B : find(brand_id)
B-->>Svc : 品牌信息
Svc-->>Ctrl : 商品详情数组
Ctrl-->>C : ApiResponse.success({product, defined, title, open, coupon_list})

图表来源

api/route/product.php:31-34
api/controller/product/ProductController.php:87-113
front/service/product/ProductService.php:210-258
front/model/product/Product.php:167-170

详细组件分析

商品详情接口（产品模块）

方法：GET
路径：/api/?route=product/show
必需参数：
- id：商品 ID（支持通过 RouteId 解析 slug/category_slug）
可选参数：
- category_slug：分类别名（配合 id 或 slug 使用）
- slug：商品别名（配合 id 或 category_slug 使用）
鉴权：可携带 api 登录态以获取会员视角的价格与收藏状态
返回：
- product：商品详情对象（见下方数据结构）
- defined：自定义属性对（键值对）
- title：页面标题
- open：功能开关（如 order）
- coupon_list：可用优惠券列表（当启用优惠券模块时）

flowchart TD
Start(["请求进入"]) --> Parse["解析 id/slug/category_slug"]
Parse --> Valid{"ID 有效?"}
Valid -- 否 --> Err["抛出错误"]
Valid -- 是 --> Load["加载商品详情"]
Load --> Price["计算销售价/积分"]
Price --> Gallery["加载图片集/首图"]
Gallery --> Fav["查询收藏状态"]
Fav --> Brand["加载品牌信息"]
Brand --> Coupon["加载优惠券列表(可选)"]
Coupon --> Resp["返回 ApiResponse.success"]

图表来源

api/controller/product/ProductController.php:87-113
front/service/product/ProductService.php:210-258

章节来源

api/controller/product/ProductController.php:87-113
front/service/product/ProductService.php:210-258

商品属性选择后价格计算接口

方法：GET
路径：/api/?route=product/attribute_list
必需参数：
- id：商品 ID
可选参数：
- attribute_data：JSON 字符串，表示已选属性集合（服务端会解码为数组）
返回：
- attribute_list：属性选项及选中项信息
- box：包含 price、sale_price、point 等价格与积分信息

sequenceDiagram
participant C as "客户端"
participant Ctrl as "ProductController"
participant Svc as "ProductService"
participant Attr as "AttributeService"
C->>Ctrl : GET /api/?route=product/attribute_list?id={id}&attribute_data=...
Ctrl->>Svc : buildApiAttributeData(id, userId, attributeData, attribute)
Svc->>Attr : getAttributeList(...)
Attr-->>Svc : 属性列表
Svc-->>Ctrl : {attribute_list, box}
Ctrl-->>C : ApiResponse.success

图表来源

api/controller/product/ProductController.php:116-137
front/service/product/ProductService.php:302-344

章节来源

api/controller/product/ProductController.php:116-137
front/service/product/ProductService.php:302-344

条目详情接口（非商品类内容）

方法：GET
路径：/api/?route=item/show
必需参数：
- id：条目 ID（支持 slug/category_slug）
行为：
- 加载条目详情
- 记录并累加点击数（click）
返回：
- item：条目详情对象
- defined：自定义属性对
- title：页面标题

sequenceDiagram
participant C as "客户端"
participant Ctrl as "ItemController"
participant Svc as "ItemService"
C->>Ctrl : GET /api/?route=item/show?id={id}
Ctrl->>Svc : buildItemShowData(id)
Svc-->>Ctrl : 条目数据
Ctrl->>Svc : recordItemView(id)
Ctrl-->>C : ApiResponse.success({item, defined, title})

图表来源

api/controller/item/ItemController.php:94-122

章节来源

api/controller/item/ItemController.php:94-122

依赖关系分析

控制器依赖服务：ProductController 依赖 ProductService；ItemController 依赖 ItemService。
服务依赖模型与外部模块：ProductService 依赖 Product 模型、PricingService、附件系统、Favorites 模块、Brand 模型。
路由声明：API 路由将 /api/?route=product 映射到 ProductController 的 index/show/attribute_list。

graph LR
Route["API 路由"] --> Ctrl["ProductController"]
Ctrl --> Svc["ProductService"]
Svc --> Model["Product 模型"]
Svc --> Pricing["PricingService"]
Svc --> Attach["附件/相册"]
Svc --> Fav["Favorites 模块"]
Svc --> Brand["Brand 模型"]

图表来源

api/route/product.php:31-34
api/controller/product/ProductController.php:32-113
front/service/product/ProductService.php:210-258

章节来源

api/route/product.php:15-47
api/controller/product/ProductController.php:15-154
front/service/product/ProductService.php:35-59

性能考虑

列表页批量预取：通过 with('category') 与 prefetchers 预热 URL、多语言、附件缩略图与相册首图，减少 N+1 查询。
详情页按需加载：仅加载必要字段，避免冗余数据。
价格计算缓存：PricingService 按商品与用户维度计算销售价，建议结合缓存策略降低重复计算。
附件与相册：使用进程内缓存命中 gallery_first，提升首图加载速度。
分页与限制：列表页默认分页大小可控，避免一次性返回过多数据。

故障排查指南

无效 ID：当传入的 id/slug/category_slug 无法解析为有效记录时，控制器抛出领域异常（page_wrong），请检查参数与路由解析。
未登录场景：若未登录，收藏状态可能为空；如需会员视角价格与收藏态，请确保携带 api 登录态。
模块开关：品牌、优惠券、收藏等功能受配置开关控制，若返回为空，请检查对应功能是否启用。
属性选择：attribute_data 必须为合法 JSON 字符串，否则会被忽略或返回空结果。

章节来源

api/controller/product/ProductController.php:87-113
front/service/product/ProductService.php:210-258

结论

商品详情接口通过清晰的控制器-服务-模型分层，提供了稳定且可扩展的商品详情查询能力。其返回结构覆盖基本信息、详细描述、规格属性、图片集、价格信息与关联数据，并支持收藏状态与优惠券等扩展功能。开发者可基于该接口快速构建商品详情展示页面。

附录：接口规范与示例

接口定义

商品详情
- 方法：GET
- 路径：/api/?route=product/show
- 参数：
  - id：必填，商品 ID
  - category_slug：可选，分类别名
  - slug：可选，商品别名
- 返回：
  - product：商品详情对象
  - defined：自定义属性对
  - title：页面标题
  - open：功能开关（如 order）
  - coupon_list：优惠券列表（可选）
商品属性选择后价格
- 方法：GET
- 路径：/api/?route=product/attribute_list
- 参数：
  - id：必填，商品 ID
  - attribute_data：可选，JSON 字符串，表示已选属性集合
- 返回：
  - attribute_list：属性选项与选中项
  - box：price、sale_price、point
条目详情（非商品）
- 方法：GET
- 路径：/api/?route=item/show
- 参数：
  - id：必填，条目 ID
- 返回：
  - item：条目详情对象
  - defined：自定义属性对
  - title：页面标题

章节来源

api/route/product.php:31-34
api/route/item.php:29-31
api/controller/product/ProductController.php:87-137
api/controller/item/ItemController.php:94-122

商品详情返回结构（product）

基本信息
- id：商品 ID
- category_id：分类 ID
- title：标题
- name：名称（多语言）
- description：摘要/描述
- content：详细内容（HTML）
- created_at：创建时间
- status：状态
- click：点击量（注意：商品模块详情未自动累加；条目模块会累加）
- stock：库存
- sales：销量
- model：型号标识（用于同型号推荐）
- brand_id：品牌 ID
- point：积分
- url：商品链接
- thumb：缩略图 URL
- image：主图附件
- image_other：相册首图 URL
- gallery_list：图片集（全量图集）
- favorites：收藏状态（true/false/null）
- brand：品牌信息对象（当启用品牌功能）
- defined：自定义属性对（键值对）
- price_format：格式化价格（API 场景）
- sale_price：销售价信息（含 value/format）
附加信息
- open.order：是否开启下单入口（来自配置）
- coupon_list：优惠券列表（当启用优惠券模块）

章节来源

front/service/product/ProductService.php:210-258
front/model/product/Product.php:59-85
api/controller/product/ProductController.php:99-113

请求与响应示例

商品详情
- 请求：GET /api/?route=product/show&id=123
- 响应：
  - code：成功码
  - data：
    - product：{...}
    - defined：{...}
    - title："商品详情"
    - open：{order: true/false}
    - coupon_list：[...]
属性选择后价格
- 请求：GET /api/?route=product/attribute_list&id=123&attribute_data={"color":"红","size":"L"}
- 响应：
  - code：成功码
  - data：
    - attribute_list：[...]
    - box：{price:"¥199.00", sale_price:{value:199.00, format:"¥199.00"}, point:199}
条目详情
- 请求：GET /api/?route=item/show&id=456
- 响应：
  - code：成功码
  - data：
    - item：{...}
    - defined：{...}
    - title："条目详情"

章节来源

api/controller/product/ProductController.php:87-137
api/controller/item/ItemController.php:94-122

浏览统计与收藏状态

浏览统计：
- 商品模块：详情接口未自动累加 click（需自行处理或在其他位置实现）
- 条目模块：详情接口会自动记录并累加 click
收藏状态：
- 商品模块：在详情中返回 favorites 状态（true/false/null），取决于是否启用收藏功能与当前登录态
- 列表页：同样返回 favorites 状态，便于前端展示

章节来源

api/controller/item/ItemController.php:112-115
front/service/product/ProductService.php:236-237

添加日期：2026-10-05