简介
本文件面向电商应用开发者，提供“商品规格属性”查询接口的完整参考。内容涵盖：
- HTTP 方法与参数规范
- 属性值获取（文本、图片等类型）
- 自定义属性支持（商家可添加业务相关属性）
- 属性组合筛选思路（基于返回的可选值进行前端组合）
- 属性权重与显示顺序控制
- 缓存机制与性能优化建议
- 完整的请求与响应示例及数据结构说明
项目结构
该功能在 API 层通过声明式路由暴露 GET /api/?route=attribute，控制器调用核心服务读取属性与属性值，并返回标准化 JSON 数据。后台侧提供属性与属性值的增删改查能力，用于配置商品规格。
graph TB
Client["客户端"] --> Route["API 路由<br/>/api/?route=attribute"]
Route --> Ctrl["AttributeController::index"]
Ctrl --> Svc["AttributeService::getAttributeList"]
Svc --> DB_Attr["数据库表 attribute"]
Svc --> DB_Val["数据库表 attribute_value"]
Ctrl --> Resp["统一响应 ApiResponse"]图表来源
- api/attribute.php:15-29
- api/controller/AttributeController.php:47-84
- core/service/AttributeService.php:44-78
章节来源
- api/attribute.php:15-29
- api/controller/AttributeController.php:47-84
核心组件
- API 路由：将 /api/?route=attribute 映射到 AttributeController::index
- 控制器：校验参数、读取配置开关、组装返回结构
- 核心服务：按模块、分类、商品维度查询属性与属性值，处理默认选中项与价格浮动
- 模型：属性与属性值的数据访问封装
- 语言包：属性类型与提示文案
章节来源
- api/attribute.php:15-29
- api/controller/AttributeController.php:47-84
- core/service/AttributeService.php:44-78
- admin/model/Attribute.php:29-85
- admin/model/AttributeValue.php:26-53
- languages/zh_cn/attribute.lang.php:15-44
架构总览
下图展示一次属性查询请求从路由到数据库再到响应的完整流程。
sequenceDiagram
participant C as "客户端"
participant R as "API 路由"
participant A as "AttributeController"
participant S as "AttributeService"
participant D as "数据库(attribute, attribute_value)"
C->>R : GET /api/?route=attribute&rec=list&module=&item_id=&category_id=
R->>A : 调用 index()
A->>A : 校验 rec/module/item_id
A->>S : getAttributeList(module, category_id, item_id, 'common')
S->>D : 查询 attribute (按 module/category_id 排序)
S->>D : 对每个属性查询 attribute_value (按 item_id/att_id)
D-->>S : 属性列表 + 属性值列表
S-->>A : 结构化属性数据(含默认选中、价格浮动)
A-->>C : { code, message, data : { attribute_list } }图表来源
- api/attribute.php:15-29
- api/controller/AttributeController.php:47-84
- core/service/AttributeService.php:44-78
详细组件分析
API 控制器：AttributeController::index
- 作用：接收请求参数，校验合法性，读取系统配置开关，调用服务获取属性列表，并裁剪为精简的 JSON 结构返回
- 关键逻辑：
- 仅当 rec=list 时返回实际数据，否则返回空列表
- 必须传入 module 与 item_id；未通过校验则返回参数错误
- 若 features.attribute 关闭，返回空列表
- 调用服务获取原始数据后，构造 attribute_list，包含 attribute_id、name、value_list（每项含 attribute_value_id、value）
flowchart TD
Start(["进入 index"]) --> CheckRec["检查 rec 是否为 list"]
CheckRec --> |否| Empty["返回空 attribute_list"]
CheckRec --> |是| Validate["校验 module 与 item_id"]
Validate --> |失败| Err["返回 INVALID_PARAMS"]
Validate --> |成功| FeatureCheck{"features.attribute 开启?"}
FeatureCheck --> |否| Empty
FeatureCheck --> |是| Fetch["调用服务获取属性列表"]
Fetch --> Build["构建 attribute_list"]
Build --> Return["返回成功响应"]图表来源
- api/controller/AttributeController.php:47-84
章节来源
- api/controller/AttributeController.php:47-84
核心服务：AttributeService
- 作用：根据 module、category_id、item_id 查询属性与属性值，计算默认选中项与价格浮动，并按 sort/id 排序
- 关键点：
- 支持按分类及其子分类过滤属性（含全局属性 category_id=0）
- 对每个属性，若存在 item_id 则加载其属性值列表
- 自动处理第一个属性值的 price_change 清零规则（避免默认值带加价）
- 返回字段包含 att_id、name、type、value_list、selected_value_id、selected_value_price_change
classDiagram
class AttributeService {
+getAttributeList(module, category_id, item_id, mode, attribute_data) array
+getValueList(module, item_id, att_id, mode, attribute_data) array
}
class DB {
<<facade>>
+table(name) Builder
}
AttributeService --> DB : "查询 attribute / attribute_value"图表来源
- core/service/AttributeService.php:44-142
章节来源
- core/service/AttributeService.php:44-142
后台模型：Attribute 与 AttributeValue
- Attribute：定义属性表的字段与筛选器（按商品分类范围查询）、默认排序、是否存在属性值记录判断
- AttributeValue：定义属性值表字段与类型转换（如 price_change 为浮点），支持新增/更新/删除
erDiagram
ATTRIBUTE {
int id PK
int category_id
string name
string type
int sort
}
ATTRIBUTE_VALUE {
int id PK
string module
int item_id
int att_id FK
string value
string type
string image
text remark
float price_change
}
ATTRIBUTE ||--o{ ATTRIBUTE_VALUE : "一对多"图表来源
- admin/model/Attribute.php:29-85
- admin/model/AttributeValue.php:26-53
章节来源
- admin/model/Attribute.php:29-85
- admin/model/AttributeValue.php:26-53
后台服务：属性值 AJAX 操作
- 作用：提供属性值的添加、删除、图片上传等操作，并返回渲染后的 HTML 片段
- 关键点：
- 新增时校验必填项与重复值，首次值禁止设置加价（自动清零）
- 删除时清理关联图片并刷新列表
- 图片上传后更新属性值图片并刷新列表
章节来源
- admin/service/AttributeService.php:222-319
依赖关系分析
- 路由依赖控制器
- 控制器依赖核心服务与配置、校验工具、统一响应
- 核心服务依赖数据库抽象与分类工具
- 后台服务依赖模型与附件、审计、配置等
graph LR
Route["api/route/attribute.php"] --> Ctrl["api/controller/AttributeController.php"]
Ctrl --> CoreSvc["core/service/AttributeService.php"]
CoreSvc --> DB["DB Facade"]
AdminSvc["_/module/attribute/admin/service/AttributeService.php"] --> Models["admin/model/*"]图表来源
- api/attribute.php:15-29
- api/controller/AttributeController.php:47-84
- core/service/AttributeService.php:44-78
- admin/service/AttributeService.php:222-319
章节来源
- api/attribute.php:15-29
- api/controller/AttributeController.php:47-84
- core/service/AttributeService.php:44-78
- admin/service/AttributeService.php:222-319
性能与缓存
- 当前实现未内置内存级缓存；每次请求直接查询数据库
- 建议优化策略：
- 对高频属性列表做短期缓存（例如按 module+category_id 维度缓存数分钟）
- 对属性值列表按 item_id+att_id 维度缓存，减少重复 IO
- 使用数据库索引优化 where 条件（module、category_id、item_id、att_id）
- 合并查询与分页限制，避免一次性返回过多数据
- 结合 CDN 或边缘缓存静态资源（如属性图片）
故障排查
- 参数错误：module 非字母或 item_id 非法将返回参数错误码
- 功能关闭：若 features.attribute 未开启，将返回空属性列表
- 默认值加价清零：首个属性值若设置了 price_change，将被自动清零，避免默认价异常
- 后台操作失败：新增属性值时若为空或重复会返回校验失败；删除需确认且会清理图片
章节来源
- api/controller/AttributeController.php:55-64
- core/service/AttributeService.php:100-104
- admin/service/AttributeService.php:222-319
- languages/zh_cn/attribute.lang.php:41-44
- languages/zh_cn/admin/attribute.lang.php:25-43
结论
该接口提供了按模块与商品维度查询规格属性的标准方式，支持文本与图片两种属性类型，具备默认选中与价格浮动能力。通过后台可灵活扩展自定义属性，满足多样化业务场景。建议在生产环境引入缓存与索引优化，提升高并发下的稳定性与性能。
附录：接口规范与示例
接口概览
- 方法：GET
- 路径：/api/?route=attribute
- 鉴权：公开接口（依据路由与中间件配置）
- 功能：获取指定模块与商品的规格属性及其可选值
请求参数
- rec：字符串，固定传 list（其他值返回空列表）
- module：字符串，模块标识（如 product）
- item_id：整数，商品 ID（必填）
- category_id：整数，可选，用于限定属性所属分类范围
响应结构
- 成功
- code：数字，通常为 200
- message：字符串，成功消息
- data：对象
- attribute_list：数组，元素包含：
- attribute_id：整数，属性 ID
- name：字符串，属性名称
- value_list：数组，元素包含：
- attribute_value_id：整数，属性值 ID
- value：字符串，属性值
- attribute_list：数组，元素包含：
- 失败
- code：数字，错误码（如参数非法）
- message：字符串，错误信息
- data：空或附加信息
请求示例
- GET /api/?route=attribute&rec=list&module=product&item_id=12345&category_id=10
响应示例
- 成功
- { "code": 200, "message": "success", "data": { "attribute_list": [ { "attribute_id": 1, "name": "颜色", "value_list": [ {"attribute_value_id": 101, "value": "红色"}, {"attribute_value_id": 102, "value": "蓝色"} ] }, { "attribute_id": 2, "name": "尺寸", "value_list": [ {"attribute_value_id": 201, "value": "S"}, {"attribute_value_id": 202, "value": "M"} ] } ] } }
- 失败（参数非法）
- { "code": 400, "message": "参数错误", "data": [] }
属性类型与值
- 文本：适用于颜色、尺寸、材质等常见规格
- 图片：适用于需要展示图标的属性（如面料样式）
- 备注与加价：后台可为属性值设置备注与价格浮动（首个值加价会被清零）
自定义属性
- 商家可在后台为商品分类添加自定义属性（文本或图片），并在商品编辑时为其赋值
- 前端通过该接口获取已配置的属性与可选值，动态渲染选择控件
属性组合查询
- 接口返回所有可选值，前端可根据用户选择的多个属性值组合筛选商品
- 后端可按需扩展筛选接口以支持多属性条件组合（当前接口仅返回属性与值）
权重与显示顺序
- 属性排序：按 sort 升序，其次按 id 升序
- 属性值排序：按 id 升序
- 建议在后台维护合理的 sort 值以控制展示顺序
缓存机制与性能优化
- 当前无内置缓存；建议按 module+category_id 与 item_id+att_id 维度引入短期缓存
- 数据库层面确保 module、category_id、item_id、att_id 有合适索引
- 图片等资源走 CDN，减少带宽与延迟