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

商品图片接口

简介

本文件面向电商应用开发者，提供"商品图片处理"的完整接口参考。内容覆盖：

商品图片上传（主图、编辑器内嵌图片）
图片处理（缩略图生成、压缩、格式转换、ICO图标生成）
多图管理（主图设置、轮播图、排序）
图片访问（尺寸裁剪、CDN 加速）
安全策略（鉴权、防盗链建议）
缓存与性能优化方案
请求与响应示例及数据结构说明

项目结构

围绕商品图片能力，关键代码分布在以下位置：

API 控制器：接收请求、鉴权、参数校验、调用服务
业务服务：工作端权限校验、归属校验、图片存储与更新
图片基础设施：缩略图、压缩、转码、水印、ICO转换等
附件系统：统一存储、URL 生成、图库查询
配置中心：站点图片宽度、缩略图尺寸、水印开关、存储驱动等

graph TB
Client["客户端<br/>小程序/前端"] --> API["API 控制器<br/>WorkController"]
API --> Svc["业务服务<br/>WorkProductService"]
Svc --> Att["附件服务<br/>attachment()"]
Att --> ImgMgr["图像处理管理器<br/>ImageManager"]
ImgMgr --> Driver["GD 驱动<br/>GdDriver"]
ImgMgr --> Facade["Image 门面<br/>静态接口"]
Svc --> DB["数据库<br/>商品表/文件表"]
Att --> FS["文件系统/云存储<br/>images/upload/..."]

图表来源

WorkController.php:174-198
WorkProductService.php:248-290
ImageManager.php:23-167
GdDriver.php:21-545
Image.php:26-50

核心组件

控制器层：负责登录与工作端权限校验、参数取值、调用服务并统一返回
服务层：校验商品归属、执行图片上传、写入主图或内容图、读取图库
图片层：提供 resize、thumb、transcode、watermark、toIco、info、buildThumbPath 等能力
附件层：统一存储、缩略图生成、URL 生成、草稿与图库管理
配置层：站点图片宽度、缩略图宽高、水印开关、存储驱动等

章节来源

WorkController.php:174-198
WorkProductService.php:248-290
ImageManager.php:23-167
GdDriver.php:21-545

架构总览

下图展示一次"商品图片上传"的端到端流程：客户端发起上传，控制器鉴权后交由服务层处理；服务层根据类型选择主图或内容图路径，调用附件服务进行存储与缩略图生成；最终返回可访问的图片 URL。

sequenceDiagram
participant C as "客户端"
participant Ctrl as "WorkController"
participant Svc as "WorkProductService"
participant Att as "附件服务"
participant Img as "ImageManager/GdDriver"
participant DB as "数据库"
C->>Ctrl : POST /product/work/upload
Ctrl->>Ctrl : 鉴权与工作端权限校验
Ctrl->>Svc : uploadImage(itemId, type, imgWidth, workId)
Svc->>Svc : 校验商品归属(ownedByWork)
alt 类型=content
Svc->>Att : store(module=item_id, type=content, options=width/watermark)
else 类型=thumb
Svc->>Att : store(module=item_id, type=main, options=thumb_width/thumbnail)
end
Att->>Img : 生成缩略图/压缩/转码/水印/ICO
Img-->>Att : 返回文件号
Att-->>Svc : 返回文件号
Svc->>DB : 更新商品主图(仅thumb模式)
Svc-->>Ctrl : {image, file_url}
Ctrl-->>C : 成功响应

图表来源

WorkController.php:174-198
WorkProductService.php:248-290
ImageManager.php:23-167
GdDriver.php:21-545

详细组件分析

商品图片上传接口

路由与方法
- 方法：POST
- 路径：/product/work/upload
- 认证：需要登录与工作端权限
请求参数
- item_id：整数，必填，商品 ID
- type：字符串，可选，默认 thumb；支持 thumb（主图）、content（编辑器内嵌图）
- img_width：整数，可选；当 type=content 时生效，用于内容图目标宽度
- image：文件字段，必填，二进制图片数据
处理逻辑
- 控制器校验登录与工作端权限
- 服务层校验商品归属（当前工作台拥有）
- 若 type=content：按配置的目标宽度生成内容图，并可选择是否加水印
- 若 type=thumb：按配置的缩略图宽高生成缩略图，并回写商品主图
响应数据
- code：状态码
- message：提示信息
- data.image：文件号（用于后续删除/重命名等操作）
- data.file_url：可访问的图片 URL

flowchart TD
Start(["进入 upload"]) --> Auth["鉴权与工作端权限校验"]
Auth --> Params{"参数合法?"}
Params -- 否 --> Err1["返回无效参数错误"]
Params -- 是 --> CheckItem["校验商品归属(ownedByWork)"]
CheckItem --> Owned{"归属有效?"}
Owned -- 否 --> Err2["返回未找到/无权限"]
Owned -- 是 --> Type{"type=content?"}
Type -- 是 --> StoreContent["store(type=content, width=img_width, watermark)"]
Type -- 否 --> StoreMain["store(type=main, thumbnail=thumb_width/thumb_height)"]
StoreContent --> UpdateMain{"是否更新主图?"}
StoreMain --> UpdateMain
UpdateMain -- 是 --> SaveDB["更新商品主图"]
UpdateMain -- 否 --> Skip["跳过更新"]
SaveDB --> Resp["返回 {image, file_url}"]
Skip --> Resp

图表来源

WorkController.php:174-198
WorkProductService.php:248-290

章节来源

WorkController.php:174-198
WorkProductService.php:248-290

图片处理能力

基础图片处理

缩略图生成
- 通过 AttachmentUploadOptions 指定缩略图宽高，底层使用 ImageManager::thumb 与 GdDriver::resize 实现
图片压缩
- 通过 ImageManager::resize/transcode 控制质量与尺寸，避免放大原图
格式转换
- 支持 jpg/png/gif/webp 互转，依据目标扩展名自动选择编码器
水印
- 支持文字水印与图片水印，可通过配置开启/关闭

新增 ICO 图标转换功能

更新新增了完整的 ICO 图标生成功能，支持现代浏览器的 favicon 需求

ICO 格式转换
- 通过 ImageManager::toIco 和 GdDriver::toIco 实现
- 支持任意图片格式转换为标准 ICO 容器格式
- 采用 PNG-in-ICO 技术，保留 alpha 透明通道
- 支持 1-256 像素尺寸的图标生成
- 自动等比缩放并居中绘制，四周留透明边距
跨浏览器兼容性
- 生成的 ICO 文件符合现代浏览器标准
- 支持 PNG 压缩以保持小文件大小
- 透明背景在所有主流浏览器中正确显示
应用场景
- 网站 favicon 自动生成
- 应用程序图标制作
- 多尺寸图标批量处理

classDiagram
class ImageManager {
+driver()
+open(path)
+info(path)
+resize(src,dst,w,h,q)
+transcode(src,dst,w,h,q)
+toIco(src,dst,size)
+thumb(src,thumb,w,h,q)
+watermark(src,dst,options,q)
+buildThumbPath(rel,subdir)
}
class ImageEditor {
+resize(w,h)
+thumb(w,h)
+watermark(options)
+save(dst,q)
+info()
}
class GdDriver {
+info(abs)
+resize(src,dst,w,h,q)
+thumb(src,thumb,w,h,q)
+watermark(src,dst,options,q)
+transcode(src,dst,w,h,q)
+toIco(src,dst,size)
+buildIcoContainer(pngData,size)
}
class ImageFacade {
+static driver()
+static open(path)
+static info(path)
+static resize(src,dst,w,h,q)
+static toIco(src,dst,size)
+static thumb(src,thumb,w,h,q)
+static watermark(src,dst,options,q)
+static buildThumbPath(rel,subdir)
}
ImageManager --> GdDriver : "委托"
ImageManager --> ImageEditor : "开放链式入口"
ImageEditor --> GdDriver : "执行操作"
ImageFacade --> ImageManager : "静态门面"

图表来源

ImageManager.php:23-167
ImageEditor.php:23-159
GdDriver.php:21-545
Image.php:26-50

章节来源

ImageManager.php:23-167
ImageEditor.php:23-159
GdDriver.php:21-545
Image.php:26-50

多图管理与排序

主图设置
- 当 type=thumb 时，上传成功后会更新商品主图字段
轮播图管理
- 通过附件服务的图库能力获取商品的多图列表（gallery），可用于轮播展示
排序
- 商品列表按 sort ASC, id DESC 排序；图库顺序由附件服务维护

章节来源

WorkProductService.php:248-290
WorkProductService.php:184-187

图片访问与 CDN 加速

图片 URL
- 通过附件服务的 url 方法生成可访问链接，支持相对/绝对路径
尺寸裁剪
- 可在 URL 上附加尺寸参数（如 ?w=xxx&h=xxx）由服务器动态裁剪；或直接使用已生成的缩略图
CDN 加速
- 将 images/upload 目录指向对象存储或 CDN，并在配置中启用相应驱动，即可实现静态资源加速

章节来源

file.php:55-55

安全验证与防盗链

鉴权
- 所有上传接口需登录且具备工作端权限，失败返回未授权/禁止访问
归属校验
- 上传前校验商品归属当前工作台，防止越权修改
防盗链建议
- 在 Web 服务器层限制 Referer 白名单
- 对敏感图片启用临时签名 URL（结合对象存储/CDN）
- 避免直接暴露源站路径，优先通过 CDN 域名访问

章节来源

WorkController.php:224-248
WorkProductService.php:260-272

依赖关系分析

控制器依赖服务：WorkController -> WorkProductService
服务依赖附件与配置：WorkProductService -> attachment(), Config
附件依赖图片处理：attachment() -> ImageManager -> GdDriver
配置影响行为：site.img_width、site.thumb_width/height、site.watermark、storage driver

graph LR
WC["WorkController"] --> WPS["WorkProductService"]
WPS --> ATT["attachment()"]
ATT --> IMG["ImageManager"]
IMG --> GD["GdDriver"]
IMG --> FACADE["Image Facade"]
WPS --> CFG["Config"]

图表来源

WorkController.php:174-198
WorkProductService.php:248-290
ImageManager.php:23-167
GdDriver.php:21-545
Image.php:26-50

章节来源

WorkController.php:174-198
WorkProductService.php:248-290
ImageManager.php:23-167
GdDriver.php:21-545

性能与缓存

缩略图预生成
- 上传即生成缩略图，减少首屏加载时的实时计算
不放大原图
- 当原图小于等于目标宽度时跳过缩放，避免无意义重算
格式与质量
- 合理设置 quality 与目标格式（webp/jpg）以平衡画质与体积
- ICO 图标使用 PNG 压缩以减少文件大小
缓存策略
- 为静态图片设置长期缓存头（如一年）
- 使用 CDN 缓存不同尺寸的裁剪结果
- 对频繁访问的商品图采用边缘缓存
- ICO 图标文件可设置更长的缓存时间
并发与 I/O
- 大文件上传建议分片与断点续传（前端实现）
- 图片处理尽量异步化（队列）以降低请求延迟

安全与防盗链

接口级安全
- 必须登录且具备工作端权限
- 严格校验 item_id 归属当前工作台
传输安全
- 全站 HTTPS
- 限制 Content-Type 与文件大小
存储安全
- 非公开图片使用私有桶/目录
- 通过签名 URL 短期授权访问
防盗链
- 配置 Referer 白名单
- 使用 CDN 的防盗链与热防保护

故障排查

常见错误
- 未登录或权限不足：检查 Authorization 与工作端权限
- 参数非法：确认 item_id、type、image 字段存在且合法
- 商品不存在或无归属：确认 item_id 属于当前工作台
- 图片处理失败：检查 GD 扩展、磁盘空间、目录权限
- ICO 转换失败：检查输入文件格式和尺寸范围
定位步骤
- 查看控制器与服务层的返回值与错误码
- 检查附件服务日志与存储目录权限
- 核对配置项 site.img_width、site.thumb_width/height、site.watermark
- 验证 GD 库支持的图像格式

章节来源

WorkController.php:174-198
WorkProductService.php:260-290

结论

本接口提供了从上传、处理到访问的完整商品图片能力。通过统一的附件服务与图片基础设施，实现了缩略图、压缩、转码、水印以及新增的 ICO 图标生成功能；配合 CDN 与缓存策略，可满足电商场景下的高并发与低延迟需求。建议在部署时完善鉴权、防盗链与存储配置，以获得最佳的安全与性能表现。

附录：接口规范与示例

接口定义

名称：商品图片上传
方法：POST
路径：/product/work/upload
认证：需要登录与工作端权限
请求体（multipart/form-data）
- item_id：整数，必填
- type：字符串，可选，默认 thumb；支持 thumb/content
- img_width：整数，可选；type=content 时生效
- image：文件，必填
响应体（JSON）
- code：字符串，OK 表示成功
- message：字符串，提示信息
- data.image：字符串，文件号
- data.file_url：字符串，图片访问 URL

请求示例

上传主图（thumb）
- 方法：POST
- 路径：/product/work/upload
- 表单字段：item_id=123, type=thumb, image=<图片文件>
上传内容图（content）
- 方法：POST
- 路径：/product/work/upload
- 表单字段：item_id=123, type=content, img_width=800, image=<图片文件>

响应示例

成功
- code: "OK"
- message: "success"
- data:
  - image: "文件号"
  - file_url: "https://cdn.example.com/images/.../xxx.jpg"
失败
- code: "INVALID_PARAMS"/"UNAUTHORIZED"/"FORBIDDEN"/"NOT_FOUND"
- message: "对应错误提示"

数据结构说明

文件号（image）
- 用于后续删除、重命名、移动等操作
图片 URL（file_url）
- 可直接在页面或 CDN 中使用
缩略图
- 通过缩略图配置自动生成，文件名遵循 _thumb 规则
内容图
- 按 img_width 生成目标宽度，便于编辑器内嵌显示
ICO 图标
- 通过 Image::toIco() 方法生成，支持 PNG 压缩和透明通道
- 适用于网站 favicon 和应用程序图标

章节来源

WorkController.php:174-198
WorkProductService.php:248-290
ImageManager.php:104-115
GdDriver.php:400-503

添加日期：2026-10-05