但凡没做过商城的人第一次接到“商品新增”这个需求大概率会觉得是个轻松活儿无非是运营在后台点一下“新增商品”填个名称、传几张图、设个价格后端接个接口往表里插一条记录完事。可真把“商城项目—商品新增”从需求评审、方案设计一直做到联调上线你会发现这是整个商品管理链路里最容易被低估的一环。它不只涉及一张主表而是牵扯到分类挂接、品牌关联、属性模板、图片素材、SKU 规格组合、库存价格、审核状态这一整套数据模型的协同落库前端要应对动态表单后端要保证事务一致性和防重复提交数据库层面还得考虑唯一索引的兜底。这篇文章我想把商品新增这个功能从设计到落地的完整思路拆开讲一遍。包括 SPU/SKU 模型怎么拆分、表结构怎么设计、前端表单怎么做、后端新增接口怎么实现、以及我在实际开发和联调中踩过的几个真实问题。如果你正在做商城类项目或者正准备接“商品新增”这一块的开发任务这篇内容可以作为一份可参考的落地清单来用。1. 商品新增的前置设计先想清楚再写增删改查1.1 商品新增到底在解决什么问题我们得先跳出“写个 insert 语句”的思维。商城项目里商品新增这个动作的最终目标是运营人员通过后台界面把一件真实商品的完整销售信息录入系统并让它具备被前台用户浏览、搜索、加购、下单的能力。也就是说新增成功之后这件商品至少要能在以下环节被正确使用前台商品列表/详情页能展示包括主图、轮播图、详情图和商品参数搜索模块能按商品名称、分类、品牌检索到它购物车和订单模块能根据 SKU 找到对应的价格和库存库存系统和后续的库存扣减能定位到具体规格的商品。所以商品新增不是一个孤立的“写库操作”而是整个商品域数据的一次“集中初始化”。任何一个环节的数据没写对后面搜索、详情、下单都会跟着出问题。这也就是为什么正规的商城项目商品新增一定会拆成多张表来设计而不是一张大宽表搞定一切。1.2 SPU 与 SKU一个音箱和一个“黑色低音炮”的区别聊商品模型必然绕不开 SPU 和 SKU 这两个概念。SPUStandard Product Unit是标准化产品单元它描述的是“这是个什么东西”比如“某品牌便携蓝牙音箱”SKUStock Keeping Unit是库存量单位它描述的是“具体哪一个可售卖的规格”比如“曜石黑 / 低音炮版 / 官方标配”。可以做个生活化的类比SPU 像是你在一家餐厅菜单上看到的“宫保鸡丁”这道菜SKU 则是你下单时选的“免辣”“加花生”“大份”这种具体选项。后厨备菜、出餐、算账都要按这个具体选项来。这个区分直接影响商品新增的表单设计公共信息挂在 SPU 上商品名称、所属三级分类、品牌、主图、详情介绍、上下架状态规格化信息挂在 SKU 上每个规格组合对应的价格、原价、库存、预警值、SKU 编码、条码、规格图。如果在设计的时候不把这两层拆开就会出现“同一件商品的两种颜色要维护两条完全独立的商品记录”这种尴尬局面前台详情页也没法把“黑色”和“白色”聚合到同一个商品下展示。所以商品新增的第一步永远是确认业务上到底有没有规格差异只要有就必须 SPU/SKU 双层建模。1.3 分类树、品牌和属性模板怎么影响新增表单商品新增里最容易被忽略的是分类和属性模板的联动关系。商城一般用的是三级分类比如“家用电器 → 影音设备 → 蓝牙音箱”。分类选定之后商品名称、品牌、甚至部分属性字段都要跟着分类变化。更常见的设计是给分类挂属性模板。属性模板里包含两类属性关键属性如蓝牙版本、电池容量、续航时间用于前台详情页展示参数销售属性如颜色、套餐类型、版本用于生成 SKU 的规格维度。前端在做新增页面时选完三级分类后就要异步加载这个分类下的属性模板然后动态生成表单控件。如果分类没有挂属性模板表单就只需要填基础信息如果有就得多渲染一块“商品参数”区域并且销售属性要参与后面的 SKU 规格组合生成。所以商品新增前端页面的复杂程度完全取决于分类和属性模板的建模深度。在动手写页面之前一定先和产品确认清楚属性是自由填还是从模板选销售属性的值是否受枚举控制这些决定直接影响到后端入参结构。2. 数据模型设计新增功能背后要落哪些表2.1 商品主表与详情表字段怎么划分才不臃肿商品新增涉及的落库表通常至少是四张以上。第一张是商品主表SPU 表它存的是商品最核心的公共字段。以我常用的一套设计为例主要字段包括字段说明备注id商品ID主键spu_code商品编码业务唯一name商品名称展示用category_id三级分类ID冗余分类路径brand_id品牌ID可空sale_status上下架状态0下架 1上架audit_status审核状态与审核流联动main_image主图URL相对路径detail_html商品详情富文本可放长文本表创建人/创建时间/更新时间审计字段必备这里有个值得注意的点detail_html 这种比较长且更新频繁的内容可以单独拆一张商品详情表主表只存 id 关联。这样主表查询时不会因为拉取大字段把查询拖慢也方便以后做详情内容的版本管理。新增的时候两张表在同一个事务里一起写就行。2.2 SKU 表与库存表价格和库存怎么挂SKU 表是商品新增里第二重要的表它记录每个规格维度的组合对应的售卖单位。每行 SKU 对应一种具体规格字段一般包含sku_codeSKU 编码业务唯一spu_id关联商品主表规格值颜色、套餐等可以存 JSON 或者拆成多列price / original_price售价和原价注意金额用分或 decimal(10,2) 精确保存stock / warn_stock库存与预警库存状态启用/停用。库存字段放不放 SKU 表这是一个有争议的点。简单项目可以直接把 stock 放在 SKU 表里SKU 和库存一一对应省事。但一旦要支持多个仓库、库存流水、锁定库存就最好把库存拆成独立表SKU 只保留物理库存汇总字段。新增商品时可以先写 SKU 表库存初始化到库存表里两条记录一起提交。2.3 图片表和属性表的组织方式图片存储有两种常见方案第一种是把主图、轮播图、详情图直接以字段形式存在 SPU 表或详情表里第二种是单独建一张商品图片表每条记录存一张图的 URL 和图片类型主图/轮播图/规格图通过 spu_id 或 sku_id 关联。我偏向第二种原因很实际图片数量不固定用逗号拼接 URL 的方式回显时要 split维护起来也容易出错而单独的图片表可以轻松支持“运营上传 5 张轮播图”这种动态多的场景也方便后续做图片懒加载和 CDN 刷新。属性表也类似。SPU 属性表存关键属性记录属性名和属性值SKU 属性表则存每个 SKU 的销售属性名值对。虽然现在很多项目图省事用 JSON 字段把属性塞进一个列但一旦你要做属性筛选、属性搜索JSON 方案就会让你痛不欲生。新增功能在设计阶段多建一张表后面会少很多重构。3. 前端商品新增页面的实现细节3.1 页面结构分步表单单页长表单怎么选商品新增的前端页面常见有两种形态上下滚动的长表单或者分步骤的表单。我的经验是基础信息 图片 详情介绍放第一部分销售属性与 SKU 生成放第二部分价格库存和上架设置放第三部分。分步骤的好处是每一步的校验可以聚焦不至于让用户一口气面对几十个字段。不过分步也有代价步骤之间的数据要暂存切换步骤时经常会遇到“回到上一步改动后下一步的数据要重新计算”的联动。特别是 SKU 列表它是由第二步的销售属性值组合生成的如果第二步改了属性第三步已有的价格库存数据怎么处理这必须要提前跟产品对齐。我建议的做法是前端用一个集中的 store 对象保存整个新增表单的数据每个步骤组件只负责读写它自己的碎片第二步销售属性变更时如果检测到 SKU 列表里已有某个组合的数据则保留已有价格库存只新增缺失的组合。这样用户体验最稳也不至于进退两难。3.2 分类级联、品牌联动与参数预加载分类选择是商品新增表单里最典型的联动场景。前端用级联组件展示三级分类树选择到叶子节点第三级分类后立刻发起请求把这个分类对应的品牌列表和属性模板拉回来。这里有个容易被忽略的细节如果分类没有选到三级后端不应该允许提交。因为后续商品挂接、搜索分类筛选都依赖三级分类只选到一级或二级就保存会产生大量无法归类到叶子节点的脏数据。品牌联动也不能做成“全量加载”。如果商城里品牌几百个可以直接用带搜索的下拉框远程搜索按关键词查品牌。属性模板加载后前端要动态渲染关键属性和销售属性控件销售属性通常要支持“新增规格值”这也是一种常见的交互设计运营填一个属性值再选择该值对应的图片用于 SKU 列表的展示。3.3 SKU 规格生成笛卡尔积与动态表格SKU 生成的本质是“销售属性值的笛卡尔积”。比如颜色有黑、白两种版本有标准版、高配版两种组合出来就是 2×24 个 SKU。前端实现时要注意几点组合顺序要固定属性顺序、属性值顺序一旦变化生成的 SKU 顺序也变后续用户看规格列表对不上会很痛苦每个 SKU 行要兜底初始化新生成的行价格和库存可以给默认值比如复制第一个已填的行避免运营漏填前端校验要识别“空价格/零库存”的 SKU 行给出明确提示不能等提交到后端才报错。这块最容易出的问题是销售属性为空时 SKU 怎么处理。有些商品确实没有规格只有单个 SKU。设计时要在属性模板层约定好如果分类没有启用任何销售属性就默认生成一个空规格的 SKU 行用户只填价格库存即可。4. 后端新增接口的核心实现4.1 接口入参设计DTO 怎么组织才不会“上帝参数”商品新增的后端接口入参不能简单地搞成几十个平铺字段那样不仅可读性差后续加参数还要改接口签名。推荐的做法是定义一个层次化的新增 DTO内部包含多个子对象基础信息对象商品名称、分类 ID、品牌 ID、商品编码、详情内容图片列表对象主图、轮播图 URL 列表属性对象关键属性列表、销售属性列表SKU 列表对象每个 SKU 的规格值、价格、库存。用 Java 的 Spring Boot 写大概是一个 ProductAddDTO 里嵌套 SkuInfo、AttrInfo 这种子类。前端传来的 JSON 结构要和这个 DTO 完全对应这样后端做参数校验时也能逐层校验。这里有个经验不要把 DTO 和数据库实体混用。商品新增的参数语义和数据库表的字段语义并不完全一致比如数据库里可能需要 spu_id 关联但入参里根本没有这个字段。混用会导致实体上出现一堆“当前场景用不到”的空字段维护起来非常难受。老老实实拆一个独立的入参对象再在 Service 层做 DTO 到实体的转换。4.2 事务边界为什么新增必须包在同一个事务里商品新增涉及主表、详情表、图片表、属性表、SKU 表、库存表这一串写入操作。任何一个步骤失败前面已经写入的数据都必须回滚否则就会产生“有商品没 SKU”“有图片没主表记录”的孤儿数据。所以在 Service 层实现新增方法时一定要把整个写库过程包裹在一个事务里。常规做法是用声明式事务方法上标注 Transactional默认遇到 RuntimeException 回滚。但要注意两点别在事务里做耗时操作比如远程调图片处理服务、调用搜索索引同步这些应该放在提交事务之后异步处理数据库连接池和事务边界要匹配如果商品详情特别大、SKU 特别多整个新增做成一个大事务可能会占用连接较久要考虑是否拆分但通常单商品新增的数据量完全可控一个大事务是合理的。事务提交之后再发送一个消息或触发事件让下游的搜索模块、缓存模块去同步商品数据。这是一种经典的“先写库再同步”的模式能避免商品新增时因为远程调用失败导致本地事务回滚。4.3 校验逻辑三层校验配合才稳妥商品新增的参数校验不能只靠前端后端必须做完整的三层校验。第一层是参数格式校验商品名不能为空、长度上限、价格必须大于 0、库存不能为负数、SKU 列表不能为空。这一层可以直接用 Bean Validation 的注解比如 NotBlank、NotNull、DecimalMin挂在 DTO 字段上Controller 层统一处理校验异常。第二层是业务校验分类 ID 是否存在、分类是否叶子节点、品牌是否有效、属性值是否符合该分类的模板约束、SKU 编码是否重复。这一层需要查数据库写在 Service 层。注意这类校验的查询结果最好聚合成一个校验结果对象别一个个查询再拼装减少无意义的数据库往返。第三层是数据库层的兜底最重要的就是给关键字段加唯一索引比如 spu_code、sku_code。三层校验配合的好处是第一层挡掉脏参数第二层挡掉业务错误第三层防止高并发下两条相同编码的请求同时通过业务校验造成重复。哪怕前两层漏了数据库也能拒绝。4.4 防重复提交一个不能省的幂等设计商品新增这个操作天然是“重复提交会出大问题”的场景。运营在弱网环境下点击保存前端请求超时用户以为没提交成功又点了一次结果后端落了两条一模一样的商品。所以后端新增接口一定要做幂等控制。比较实用的方案是 token 机制前端进入新增页面时先向后端请求一个新增令牌后端把令牌存 Redis 并设置过期时间提交商品数据时这个令牌作为参数带上后端在处理前先尝试从 Redis 删除该令牌删除成功才继续处理删除失败说明令牌已用过直接拒绝重复请求。这个方案的核心在于“删除令牌”这一步是原子的同一时间只有一个请求能删成功天然具备互斥能力。如果项目里不用 Redis也可以用数据库唯一业务单号比如前端生成一个 uuid 作为 biz_id 存到商品表并加唯一索引同一业务单号的第二次插入会直接撞唯一索引失败。两者都可行我更推荐 token 方案因为不需要为商品表增加额外的业务字段。5. 联调与上线阶段踩过的坑5.1 图片上传成功但商品图不显示第一次联调的时候遇到一个非常典型的坑运营在新增页面把图传上去了图片管理里也能看到但前台商品详情页就是显示不出来。排查到最后发现问题出在图片 URL 的存储规则上。当时后端存的是对象存储服务返回的完整外链包含访问域名但由于测试环境用的域名是临时的换环境后域名失效图片自然就裂了。后来统一改成只存相对路径前端展示时根据当前环境的静态资源域名前缀拼接完整地址。这个改动虽然小但波及上传、回显、SKU 规格图、富文本详情图好几个环节建议在项目一开始就约定好图片 URL 的统一存储格式。另外一个相关的小坑是图片格式和大小校验。运营传了个 20MB 的 PNG前端压缩没做干净后端也没限制结果图片服务处理超时商品新增整体提交失败事务回滚。后来在前端上传组件里加了大小限制和前端压缩后端接口再做一次大小与格式校验双重保险。5.2 SKU 编码冲突拼接规则差点酿成大祸最初设计 SKU 编码时图省事用了“SPU 编码 规格值拼音首字母”的拼接方式。比如“黑色-标准版”拼出来是 SPU001-HSB。测试的时候没发现问题直到运营录入一款颜色较多的商品发现某个规格组合生成的编码和另一个 SKU 恰好撞上了导致数据库唯一索引直接报错商品一整单都提交不上去。排查过程比较经典先看错误日志定位到唯一索引冲突再把两条 SKU 的编码拿出来对比发现“黑色-高配版”和“灰色-标配版”的拼音首字母组合竟然一样。问题不在数据而在编码生成规则没有保证唯一性。后来改成“SPU 编码 三位流水号”的形式流水号在 SKU 列表生成时按顺序分配并配了数据库唯一索引兜底问题彻底解决。这个坑给我的教训是业务编码尽量不要用“可读性强但规则脆弱”的拼接方式尤其不能依赖中文转拼音缩写这种天然有冲突隐患的方案。编码只需要保证唯一、稳定、短所以纯流水号或雪花 ID 才是更省心的选择。5.3 弱网环境下重复提交导致的脏数据上线后的某一天运营反馈后台出现了两条几乎一模一样的商品记录唯一区别就是创建时间差了不到一秒。查了一下日志果然是用户在弱网环境下点了两次“保存”第一次请求超时但后端实际已经提交成功前端又自动重试了一次。之前为了赶进度防重复提交的 token 机制一直没有做只是在前端按钮上加了 loading 禁用。但 loading 只能拦住正常操作拦不住浏览器层面的重试和用户无感知的二次点击。这次事故之后我把 token 机制补齐了并且把新增接口也改成支持按业务单号幂等让重复请求直接返回第一条成功结果。上线后类似问题再没出现过。这也提醒我上线前写测试用例时一定要把“重复提交”这种异常场景列入测试范围不要只测正常路径。5.4 分类属性模板校验遗漏导致前台参数为空还有一次问题出在业务校验写得不够完整。当时分类模板里配置了销售属性但后端新增接口的校验逻辑里没有强制校验“该分类必须填写模板中启动的销售属性值”。结果运营提交时漏填了颜色属性后面 SKU 生成了一个没有规格值的单条记录前台详情页的参数区域直接空白搜索里的规格筛选也乱了。修复方案有两步后端在商品新增时检查该分类模板启用的销售属性集合要求入参的每个 SKU 都包含全部必填销售属性的值同时前端在生成 SKU 列表时如果销售属性缺失就置灰“提交”按钮并提示。这一步做完之后才彻底堵住这个口子。6. 写在最后的几点体会商品新增这个功能单独看就是一个典型的“多表事务写入”场景但它背后牵扯到分类、属性、图片、SKU、库存、审核、搜索索引这么多条线做得好不好直接决定后面整个商品域的开发效率。我在实际做这个功能时最深的体会就是一开始多花点时间在模型拆分和 DTO 设计上后面联调和维护会省下成倍的时间。另外有两点实操建议可以分享。第一商品新增的日志一定要打全包括入参摘要、生成的 SPU 编码、SKU 数量、每个 SKU 的价格库存概要。这样上线后一旦出现数据疑问能快速根据日志定位到是哪次操作产生的。第二认真对待数据库层面的唯一索引不要总觉得“后端已经校验过了就够”唯一索引是最后一堵墙掉以轻心迟早会吃到苦头。最后想说的是商品新增不是一次性的“写库动作”它往往也是商品生命周期管理的起点。后面商品编辑、上下架、审核、复制商品、批量导入这些功能很多逻辑都要复用到这里面的模型和校验规则。所以第一版设计时留出扩展空间比如把校验逻辑独立成可复用的校验器、把 SKU 生成逻辑设计成可批量调用的服务这些都是值得提前投入的。做商城项目的朋友如果正卡在商品新增的设计上希望这篇内容能帮你少走几条弯路。
