很多同学拿到谷粒商城这套电商项目时，最常见的操作顺序是先启动后端服务，然后报一堆表不存在的错，最后才想起来还有SQL脚本没导入。pms_catelog.sql 就是那个必须跑在前面、却经常被忽略的商品系统数据库脚本。如果你正在学微服务、做毕设，或者第一次把一套完整的电商后台跑起来，这份文件是你绕不开的第一块地基。
我最初接触这份脚本时，觉得它不过是几十张建表语句拼在一起，后来实际维护过商品模块才发现，里面每一个字段都跟后续业务逻辑有关联。这篇就把我处理 pms_catelog.sql 的经验拆开讲：它到底包含哪些核心表，导入时要注意什么，跑通之后有哪些坑等着你，以及可以借鉴的表设计思路。
1. 先搞明白这份脚本在整套系统里的位置
1.1 第七节才轮到数据库脚本，前面在铺垫什么
如果你按教程顺序走，会发现前面几节基本在搭环境、建工程、拉依赖，到了第七节突然冒出来一个 pms_catelog.sql，说明项目已经从“环境准备”阶段切到“业务落地”阶段。第七节往往是开始建商品库，因为后面的商品管理、品牌管理、属性维护、SKU发布全都依赖这张脚本。
pms_catelog.sql 这个名字其实把两个信息拼在一起：pms 是商品管理模块的前缀，catelog 应该是 catalog 的拼写，也就是分类目录。文件名把模块缩写跟“目录”揉在一起，容易第一眼看不懂，但只要记住它是给商品模块建多张表的脚本就行。
我第一次拿到它时，习惯先看整个文件有多少个 CREATE TABLE，再扫一遍表名。因为里面的核心业务表不是一张两张，而是二十张起步的一组表，涵盖分类、品牌、属性、SPU、SKU以及各种关系表。先建立起全局地图，后面逐个业务去看字段才不容易迷路。
1.2 一个模块一个库的前缀命名规则
看这份脚本前，最好先理解整个项目的库前缀体系。谷粒商城按微服务拆了好几个模块，对应的数据库也分开，比如：
- pms_：商品、分类、品牌、属性、SPU、SKU
- oms_：订单、订单项、退换货
- ums_：会员、会员等级、收货地址
- wms_：库存、采购、出入库
- sms_：营销、优惠券、秒杀
每个库下的表统一带模块前缀，比如 pms_category、pms_brand、pms_sku_info。多库环境下，不同模块的表即使同名，前缀也能把归属区分开。更重要的是，将来如果某个模块要分库分表，按前缀去拆分非常自然。所以说，pms_catelog.sql 里所有表名都以 pms_ 开头，不是随手写的，而是整个项目命名规范的一部分，你后面建新表时也要遵守这条约定。
1.3 为什么用脚本文件而不是直接给可视化模型
有人可能会问，为什么不直接给一个 PowerDesigner 模型或者数据库连接导出文件，还要我们自己执行 SQL？我的经验是，SQL 脚本是团队协作里最稳的数据库变更载体。可视化模型文件很难做 diff，谁改了一个字段，对比起来很痛苦。而 SQL 文件是普通文本，可以放进 git，每次变更都有历史，代码评审时能直接看到字段类型和默认值的变化。
pms_catelog.sql 这种文件还自带一个优势：可重复执行。虽然重复执行建表语句会报 “table already exists”，但整个文件的结构和字符集设置是完整的，换一台机器或者让别人接手，只需要跑一遍就能生成同样的库，比手动点鼠标精度高很多。我后来在公司做数据库初始化，也坚持导出成 .sql 脚本放在项目目录里，而不是让同事自己在数据库客户端里点来点去。
2. 从建表语句拆出商品域的核心模型
2.1 SPU和SKU两张表，电商商品拆层的标准答案
先解释两个基础概念。SPU 是标准产品单元，可以理解成商家后台发布的“商品主体”，比如“某品牌旗舰手机”；SKU 是具体库存单位，比如“某品牌旗舰手机 256G 原色钛金属”。一个 SPU 下面挂多个 SKU，每个 SKU 对应具体的价格、库存、参数组合。
pms_spu_info 这张表承担 SPU 基本信息，大致字段有 spu_id、spu_name、spu_description、catalog_id、brand_id、publish_status、create_time、update_time。pms_sku_info 承担 SKU 信息，大致字段有 sku_id、spu_id、sku_name、sku_attr_value、sku_pic、price、sale_count、sku_total_stock。
为什么要拆成两张表？如果你不拆，每个颜色规格都要重复一遍商品标题、商品介绍、分类和品牌，数据冗余会很夸张。而且商品详情页和结算页需要的信息维度不一样，详情页拿 SPU 层数据，下单确认页拿 SKU 层数据。分层存储，后台维护和前台查询都更清晰。
我特别提醒一点：pms_sku_info 里通常有一个 sku_attr_value 字段，比如“原色钛金属;256GB”。这是 SKU 销售属性的快照，不是去关联属性表实时计算出来的。这种“冗余快照”在订单系统里非常常见，因为下单时商品规格必须固定，如果将来属性表改了，历史订单里的 SKU 描述不能跟着变。看到这种字段，别急着说它违反范式，业务上这是必要的。
2.2 分类、品牌和中间关系表，多对多是怎么落地的
脚本里一般同时存在 pms_category、pms_brand、pms_category_brand_relation 三张表。分类管理商品目录，品牌标识商品由谁生产，两者是多对多关系。比如一个品牌可能同时做手机和家电，一个分类下又会集合多个品牌。
多对多落到数据库里，需要中间关系表。pms_category_brand_relation 这张表的结构通常很简单，就是 category_id、brand_id、sort 三个字段。后台在“品牌分类关联”页面勾选时，操作的就是这张表。如果你图省事，直接在 pms_brand 表上加 category_id，遇到跨分类品牌就得重复维护品牌记录，或者强行只保留一个分类，这会直接导致商品发布时品牌选择不完整。
我维护商品系统时遇到过类似问题，当时业务人员要求一个品牌能挂在多个分类下，数据库结构不支持，最后不得不加中间表迁移数据。所以看到脚本里已有这张 relation 表时，会觉得很成熟，千万别因为它“没有实际业务意义”就砍掉。
2.3 属性组与属性关联，后台“规格参数”功能背后的设计
商品详情页经常有“规格参数”区域，这个功能在数据库里不是简单一张字段表，而是好几张表配合出来的。pms_attr_group 是属性组，比如“主体”“屏幕”“存储”；pms_attr 是具体属性，比如“品牌”“型号”“屏幕尺寸”；还要有 pms_attr_attrgroup_relation 把属性和组关联起来。
pms_attr 表有几个关键字段值得注意：attr_name、catelog_id、attr_type、value_type、select_options、quick_show。attr_type 区分是规格参数还是销售属性，销售属性会参与 SKU 生成，规格参数只做商品描述。select_options 用来存可选项，比如“红,蓝,绿”，后台渲染下拉框时直接 split 字符串就行。很多教科书会让你建一个枚举值表，但实际业务里属性可选项相对固定，单独建表反而增加查询负担。只要选项数量不大，逗号分隔是可接受的折中方案。
2.4 图片、富文本和属性值，哪些内容该拆成独立表
脚本里还有 pms_spu_images、pms_sku_images、pms_spu_info_desc、pms_product_attr_value 这类表。为什么图片不直接存在 spu 表的 image 字段里？因为一个商品有轮播图、详情图、SKU 展示图，数量不固定，如果用逗号分隔塞进单个字段，后续单独删一张图会很别扭，而且列表页需要缩略图时还得解析整串。
富文本详情也一样。pms_spu_info_desc 常常存的是大段 HTML，如果塞进 spu 主表，每次查询商品列表都会把大字段加载出来，影响性能。拆出来之后，列表页不查 desc 表，只有进详情页才按 spu_id 去取。pms_product_attr_value 则存具体商品的具体属性值，比如某个 SPU 的“处理器型号”对应的值，这样 SPU 主表不用动态加列，新增属性也不会影响已有数据。这套“表拆得细、职责单一”的思路，很值得刚写表结构的同学学习。
3. 手把手把pms_catelog.sql跑起来
3.1 环境准备：MySQL版本、客户端字符集和导入姿势
我建议先把 MySQL 版本确认好，5.7 以上或 8.0 都没有问题。这份脚本的核心是建表和初始化数据，基本不涉及 8.0 专属语法，但要特别注意字符集。现在建表语句一般都用 utf8mb4，因为要存 emoji 和一些特殊符号，utf8 在 MySQL 里其实是 utf8mb3，长度和映射都有限制，存储中文没问题，存品牌或者评论里的特殊字符就可能报错。
导入姿势有三种，效果差异不小：
- 命令行 source
- 图形客户端（Navicat/DataGrip）直接执行文件
- 后端代码里用 JDBC 执行整个文件
命令行方式最贴近服务器环境。我的习惯是：mysql -uroot -p 进入交互界面后，先 set names utf8mb4;，再 source /path/to/pms_catelog.sql;。这样能减少很多乱码问题。图形客户端一般会自动按文件头部的 SET NAMES 执行，但也要检查连接编码。第三种方式我不推荐在正式环境用，因为如果脚本里面有大量语句，JDBC 执行超时或事务中断不好排查。
3.2 看清文件头部的建库语句，别被USE切走
打开脚本文件，头部通常类似这样：
CREATE DATABASE IF NOT EXISTS `gulimall_pms` DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci; USE `gulimall_pms`;这两行信息量很大：脚本会自动建库，并且把当前库切换到 gulimall_pms。如果你已经在 Navicat 里选中了一个自定义库，再执行整个文件，文件里的 USE 会把你切到 gulimall_pms，之后建的表都进到 pms 库去了。很多同学以为导入失败，其实是没注意到当前连接的库被脚本切换了。
如果数据库名和你的配置不一致，比如后端配的是其它库名，建议先改脚本里的 USE 语句。改库名没有想象中可怕，只有头部一个地方，全局替换也行，但注意不要把表名里的 pms_ 前缀也替换掉。
3.3 导入之后立刻做的三个验证
导入结束不报错，不代表一定成功。我每次都会做三步验证：
- 表数量是否匹配。执行 SHOW TABLES;，数一下是不是有预期的那二十多张。
- 关键表有没有初始数据。比如 pms_category 通常有分类初始数据，pms_brand 可能有品牌数据。如果这些基础表是空的，后面跑商品发布功能基本上不了。
- 索引是否齐全。SHOW INDEX FROM pms_sku_info; 看看主键和业务索引是否建立了。
验证方式很简单，但能省后面调试接口的大量时间。很多后端启动后报“字段不存在”或“表不存在”，其实就是 SQL 脚本没有完整导入，或者导入到了错误的库。
3.4 如果导入报错，先看这四类原因
导入过程中最常见的报错类别大概归纳一下：
- 语法错误：MySQL 版本过老，某些字段类型或索引语法不支持。
- 字符集错误：文件里中文字符变成问号，通常客户端的 character_set_client 不对。
- 权限错误：连数据库的用户没有 CREATE、INSERT 权限，导入到一半中断。
- 重复执行错误：表已经存在或者主键冲突。这种情况不能继续执行，应该先 DROP 库或者清空已有表。
遇到报错，用 source 命令的时候别加 --force，因为强制跳过错误会导致半套表结构，后面更难排查。最好把错误记录下来，定位到具体是哪张表哪条语句，解决后从头再来一遍。
4. 跑通脚本后最容易踩的坑
4.1 注释乱码不是脚本坏了，是连接字符集不一致
之前提过 set names utf8mb4，我再展开说下，因为这是很常见的问题。MySQL 有三个跟字符集相关的系统变量：character_set_client、character_set_connection、character_set_results。它们分别管“客户端发来的语句怎么解读”“连接层内部怎么转换”“返回结果用什么编码”。一条 SET NAMES utf8mb4 会同时把这三个变量都设置好，所以导入前执行一次最省事。
另一个细节是，Windows 自带的 cmd 默认编码不是 UTF-8，中文注释在终端里看起来乱码不一定是数据库乱码，可能只是显示问题。要确认数据是否真的乱码，可以在导入后用 SELECT 语句查询某个中文名字，如果查询结果正常，说明数据没坏，只是终端显示编码不对。如果查询也乱码，再从连接字符集上排查。
4.2 脚本里没有外键，不是设计偷懒，而是给微服务留后路
我最初检查表结构时，发现整份脚本几乎找不到 FOREIGN KEY，第一反应是不规范。后来做微服务开发，才理解这样设计的合理性。微服务架构下，数据库可能被拆成多个物理库，商品服务管 pms，订单服务管 oms，订单表如果还通过外键引用商品表，跨库之间根本建不了。即使单库能建外键，强约束也会让数据迁移和分布式事务变得非常麻烦。
所以这份脚本采用应用层维护数据完整性：删除分类前，业务代码先检查有没有品牌关联和商品引用；删除品牌前，先查商品表有没有在用。数据库保留的只是逻辑外键，也就是普通索引字段，通过索引加速 join，但不做物理约束。这是分库分表环境下的常见做法，也是在扩展性和规范之间做取舍。
4.3 逻辑删除状态字段和@TableLogic的配合
很多表里会出现 show_status、publish_status、delete_status 这类字段，初学者很容易混淆。其中 publish_status 一般只表示发布状态，不表示逻辑删除；逻辑删除需要单独的删除标记字段。如果用 MyBatis-Plus，实体类里要在逻辑删除字段上加 @TableLogic，并且配置默认值，否则调用删除接口时会执行物理 DELETE，数据真没了。
我有个印象很深的教训：项目里有一段批量更新商品状态的定时任务，本来想更新 publish_status，结果把 delete_status 也带上了，导致商品从列表消失。排查下来的原因是这两个字段都叫 status，业务代码里映射错了。所以拿到 pms_catelog.sql 之后，先花十分钟把所有 status 字段的注释读一遍，搞清楚每个字段的语义，再开始写 Mapper。
4.4 清空表数据时自增主键不回退，导致关联错乱
测试阶段免不了要清空表再初始化。MySQL 里 TRUNCATE 和 DELETE 清空表的区别是：TRUNCATE 会重置自增主键，DELETE 不会。很多人习惯用 DELETE FROM，删完后插入新数据，主键从之前的最大值继续增长。如果此时其他表还保存着旧 id 的引用，那些旧数据就成了孤儿。
比如 pms_sku_info 的 spu_id 引用 pms_spu_info 的 spu_id，你 DELETE 了 pms_spu_info 又重新插入，新数据 spu_id 是 11，但 sku 表里还留着旧 spu_id=1 的数据，关联就断了。如果只是为了重置环境，我建议对每张表都用 TRUNCATE，而不要用 DELETE；如果不想重置自增，就保留数据，或者先导出备份再手动处理。总之，清库前先想清楚，不然调试数据对不上时，排查成本远比重新造数高。
5. 从表结构反推业务：这版设计值得借鉴的地方
5.1 create_time和update_time，没有自动更新会怎样
大部分表都有 create_time 和 update_time，但脚本里未必都写了自动更新。我拿到 SQL 脚本后会专门查这两行，如果建表语句是create_time datetime DEFAULT CURRENT_TIMESTAMP，那插入时会自动填当前时间；如果是update_time datetime DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP，那每次更新记录都会自动刷新时间。没有自动更新时，就需要后端手动 set 当前时间，不然时间字段一直是 NULL 或旧值。
很多数据同步方案依赖更新时间做增量抽取，比如每次只同步 update_time 大于上次游标的数据。如果 update_time 不自动更新，同步方案会漏数据。所以如果你要在这套脚本基础上做数据同步，最好确保这两列都加了自动更新属性。本地开发时可以跑一条 ALTER TABLE 去补，但正式环境最好在一开始就设计好。
5.2 sort字段和status字段，为什么几乎每个业务表都有
分类表、品牌表、属性表、SKU 表里基本都会出现 sort 和 status 这类字段。sort 用来做手工排序，status 用来做状态控制。这两个字段看起来很普通，但对商品后台非常重要。
没有 sort 字段时，列表只能按创建时间或主键排序，业务人员想把某个品牌置顶，基本上做不到。有了 sort，后台上下移、置顶就很简单。status 则负责上下架、启用禁用、是否显示等状态。我见过不少实际业务表一开始没设计这两个字段，后来产品经理要求加排序和停用功能，数据库都上线了，只能临时加字段，麻烦不说，数据补录也是大工程。所以设计表时先预设这两个字段，成本很低，收益很高。
5.3 冗余catelog_id，空间换时间的典型例子
pms_attr 表里冗余了 catelog_id，而不是像理论中那样完全靠中间表关联。乍一看，这打破了第三范式，因为分类信息已经不是“只在一张表里维护”。但站在查询角度来看，商城后台经常要按分类过滤属性，如果每次都要从属性组关联到分类，SQL 会多一层 join；数据量大之后，join 成本不可忽视。冗余 catelog_id 之后，一条WHERE catelog_id = ?就出来了，性能直观提升。
代价是什么？需要保证冗余字段和中间表里数据一致。比如某分类被移动，所有引用它的属性要同步修改。这种一致性可以通过应用层事务控制，或者定时校验。对于电商标品这样读多写少、分类层级不太频繁变动的场景，空间换时间的收益远大于维护成本。看到 pms_catelog.sql 里有这种冗余，不要觉得不规范，它其实是电商后台常见的工程取舍。
6. 拿到这份脚本后，我建议你再做的小改造
6.1 给分类树造测试数据的一个小技巧
pms_category 表一般用 parent_id 实现父子关系，cat_level 表示当前层级。初始数据一般只有手填的几个分类，测试无限层级菜单时不够用。这时可以写一条自关联 INSERT，把现有分类复制一批作为子分类：
INSERT INTO pms_category (parent_id, name, cat_level, sort, status) SELECT category_id, CONCAT('测试-', name), cat_level + 1, 0, 1 FROM pms_category WHERE cat_level = 1;要注意造数时保持 cat_level 和 parent_id 的对应关系，否则前端递归组件会出问题。这种造数技巧同样适用于品牌和属性组，关键是先摸清表里的父子字段和状态字段，别一股脑把 NULL 也插进去。
6.2 多租户改造：不是所有表都需要tenant_id
如果你想在谷粒商城基础上做 SaaS 版，脑子里第一个念头可能是给所有表加 tenant_id。我的建议是先想清楚哪些表是“平台级数据”，哪些表是“租户级数据”。分类、品牌，如果每个租户都要维护自己的分类树，那必须加 tenant_id；如果平台统一维护一份标准分类，所有租户共用，那加了 tenant_id 反而每次查询都要带条件，性能和维护成本都会上升。
商品表、SKU 表、属性值表一般属于租户私有数据，需要加 tenant_id。更合理的做法是给租户级核心表加，而像 pms_category_brand_relation 这种纯关系表，可以通过关联主表是否带租户来判断归属，不一定要冗余一个字段。多租户隔离不是非黑即白，用共享表加租户字段还是独立库，取决于数据隐私要求。
6.3 如果让我重写这份建表脚本，我会改这三处
第一，属性可选项 select_options 从 varchar 改成 MySQL 8.0 的 JSON 字段。如果还要兼容 5.7，就保持 varchar，但如果只跑 8.0，JSON 字段查询和校验都更好，选项数量超过 255 字符也不怕。
第二，给 pms_sku_info 增加一个唯一索引，比如UNIQUE KEY uk_spu_attr (spu_id, sku_attr_value(100))，防止同一个 SPU 下录入完全相同的 SKU。这里的坑是 sku_attr_value 如果太长，直接建普通索引会有长度限制，可以先用字段截断或哈希列。
第三，把状态语义进一步拆分。publish_status、delete_status 这类字段名虽然可读，但都在表达“状态”，属性一多就容易混淆。我倾向于统一命名，比如 deleted 表示逻辑删除，published 表示上架，enabled 表示启用。命名清晰，比任何文档都能减少写 SQL 时的低级错误。
最后说一点个人体会。数据库脚本是整个项目的起点，也是最容易被轻视的部分。很多同学急着把后端服务跑起来，看到报错才回头导入 SQL，结果因为字符集、库名、重复执行各种问题卡一晚上。其实拿到 pms_catelog.sql 后，花半个小时把表结构和初始化数据认真过一遍，后面跑商品模块会顺畅很多。尤其是从这套表设计里学到的“拆表”思路，放到真实的电商系统里依然适用。
