商品图片上传接口需求
前端不再依赖独立 Evento 图床。商品模板和店铺图片统一通过现有后端服务上传,由后端负责存储并返回可公开访问的图片地址。
接口约定
POST {origin(CONNECT_BASE_URL)}/api/uploads/product-image
Authorization: Bearer <session-token>
Content-Type: multipart/form-data
表单字段:
| 字段 |
类型 |
必填 |
说明 |
picture |
File |
是 |
JPEG、PNG 或 WebP,最大 10 MB |
成功响应:
{
"url": "https://cdn.example.com/sast-shop/products/uuid.webp"
}
url 必须是无内嵌凭据的绝对 HTTPS 地址,并允许商城客户端直接通过 GET 加载。
错误状态
| HTTP 状态 |
场景 |
400 |
multipart 或图片内容不合法 |
401 |
未登录或会话失效 |
403 |
当前用户无上传权限 |
413 |
文件超过 10 MB |
415 |
文件类型不支持或文件签名不匹配 |
429 |
触发用户级上传限流 |
5xx |
存储服务或后端内部异常 |
错误响应只需返回稳定的错误码;前端会展示统一中文提示,不依赖后端内部错误文案。
后端验收要求
- 根据文件内容签名校验真实类型,不能只信任客户端 MIME 或扩展名。
- 重新生成不可预测且不会冲突的对象名,不直接使用用户文件名作为存储路径。
- 对已认证用户做权限校验、用户级限流和容量控制。
- 禁止 SVG、HTML 等可执行内容,上传和公开下载域名不得返回可执行 MIME。
- 清理 EXIF 等非必要元数据,并设置合理的图片尺寸上限;需要时在服务端二次压缩。
- 不记录 Authorization、图片二进制或存储凭据。
- 存储失败时不得返回尚不可访问的 URL;成功响应后 URL 应立即可读。
- 为接口补充单元测试、权限测试、大小与类型边界测试,并纳入后端健康监控。
商品图片上传接口需求
前端不再依赖独立 Evento 图床。商品模板和店铺图片统一通过现有后端服务上传,由后端负责存储并返回可公开访问的图片地址。
接口约定
表单字段:
picture成功响应:
{ "url": "https://cdn.example.com/sast-shop/products/uuid.webp" }url必须是无内嵌凭据的绝对 HTTPS 地址,并允许商城客户端直接通过 GET 加载。错误状态
4004014034134154295xx错误响应只需返回稳定的错误码;前端会展示统一中文提示,不依赖后端内部错误文案。
后端验收要求