Go电商系统开发实战：订单、库存与幂等性设计要点

把“goshop 电商项目01”这个代号放在标题里时，我其实是想给自己做一份项目存档。这套项目不是网上常见的商品管理 demo，而是一套按真实小商户需求整理的电商系统雏形：前台能浏览商品、加购物车、下单，后台能管理商品、库存和订单，服务端要保证库存不超卖、订单不重复、金额不失真。关于 Go 后端、MySQL 数据建模、Redis 缓存、Docker 联调这些点，我会在这篇里全部过一遍。

这个项目适合谁？如果你是准备自己动手写一套电商系统，或者不想被传统的 MVC 培训项目牵着走，想弄明白商品、订单、支付这些模块之间的真实关系，那么这篇会比较有用。整套代码以 Go 为主，但即使你平时写 Java 或 PHP，里面的建模思路和业务约束也都是通用的。

1. 开工前，先把电商的“最小闭环”想清楚

1.1 为什么我把“能不能运营”放在“功能多不多”前面

做电商项目很容易陷入一个误区：先堆功能。今天想加秒杀，明天想上拼团。但我给 goshop 定的第一阶段目标非常克制，只做五件事：商品、购物车、订单、库存、会员。这五块跑通了，一个消费者从注册到下单再到付款，然后商家发货，主链路就完整了，支付和外部登录这些模块，后面再接也不影响这个骨架。

我见过不少开发者在项目初期把权限、优惠券、积分全部塞进去，结果数据库表一大把，最后连商品和订单都没打通。电商最大的难点不在功能多，而在好几个服务之间的一致性。所以“01”这个阶段宁可少做，也必须把链路做扎实。等订单、库存、支付流水这组关系理顺了，后面加营销模块才不会把表结构推倒重来。

1.2 三端分离：用户端、管理端、服务端

实践中最容易让人混乱的，就是“商城”到底指哪个页面。我的做法是一开始就把边界写清楚：用户端是小程序或 H5，管理端是后台网页，服务端是纯 API。三端共用同一套接口，权限通过角色区分。

这样拆分后，前后端只需要约定接口格式，不需要互相依赖页面。后面如果想把用户端从 H5 换成小程序，服务端一行都不用改，至少不用改业务逻辑。

1.3 为什么选 Go 而不选 Spring Boot

这个项目叫 goshop，有层意思是“用 Go 做电商”。选 Go 并不是因为它比 Java 更高级，而是从实际收益出发：第一，Go 编译成单个二进制文件，部署省心；第二，协程和并发模型在处理库存这类高并发读写场景时天然合适；第三，这个项目的定位是个人可控的中小型系统，用 Spring Boot 难免带上一堆依赖和配置，反而把业务淹没。如果你的团队更熟 Java，继续用 Spring Boot 没问题，但下面讲的建模思路是通用的。

2. 初始化 goshop：技术栈和目录里藏着的规矩

2.1 这组技术栈是怎么配出来的

我在项目里用的组合是 Go + Gin + GORM + MySQL + Redis + Docker Compose。先解释为什么这么选：

• Gin 是 Go 里使用率最高的 HTTP 框架，路由和中间件生态成熟，文档多，出问题容易查。
• GORM 用来做 ORM，能减少建表 SQL 的重复劳动。虽然很多人批评它性能上限低，但第一阶段最重要的是开发效率。
• MySQL 存订单、用户、商品这些强事务数据，因为订单金额和库存必须保证一致性，不能像日志一样随便丢。
• Redis 用来缓存商品列表、登录态和做幂等控制，把热数据从 MySQL 的压力中分出来。
• Docker Compose 用来拉起本地 MySQL 和 Redis，避免每台新电脑都手动装一遍环境。

中间件没有选消息队列。第一阶段下单可以直接同步扣库存，消费者并发量还没到必须异步削峰的程度。引入 MQ 会给部署和排错都增加成本，这个要等项目确实有延迟需求再加。

2.2 目录结构：internal 是一道保护墙

Go 官方推荐的项目结构我一直很认可，goshop 的目录是这样：

goshop ├── cmd │ └── server │ └── main.go ├── config │ ├── config.yaml │ └── config.go ├── internal │ ├── handler │ │ ├── user.go │ │ ├── product.go │ │ ├── cart.go │ │ └── order.go │ ├── middleware │ │ ├── auth.go │ │ ├── cors.go │ │ └── request_id.go │ ├── model │ │ ├── user.go │ │ ├── product.go │ │ └── order.go │ ├── repository │ │ ├── product.go │ │ └── order.go │ └── service │ ├── order.go │ └── product.go ├── migrations │ └── 001_init.sql ├── pkg │ ├── response │ │ └── resp.go │ └── jwt │ └── token.go └── deploy └── docker-compose.yml

internal目录在 Go 里有特殊意义，外部包无法导入，这相当于一道编译期保护，避免别人不小心调用项目内部未稳定的逻辑。handler只做参数接收和响应返回，service只做业务编排，repository只管数据库读写。分层的好处是后面如果要把 GORM 换掉，或者把某个服务拆成微服务，影响的边界都很清晰。

2.3 初始化配置：环境变量不是摆设

我在 config.yaml 里只放本地默认值，真正的密码、密钥优先从环境变量读取。因为代码会提交到仓库，如果把数据库密码写死在配置文件里，等于把凭证公开。像我这里写的是：

server: port: 8080 mysql: host: localhost port: 3306 user: goshop password: ${MYSQL_PASSWORD} dbname: goshop redis: host: localhost port: 6379 jwt: secret: ${JWT_SECRET} expire_hours: 72

${MYSQL_PASSWORD}这种写法在 Go 里通常是用环境变量做替换，或者干脆用配置库来读。这不算高深技术，但很多人为了本地跑得方便，顺手就把真实密码写进去了，一次提交就埋了雷。

3. 数据库设计是地基：哪些表必须一开始就建好

3.1 商品模型：SPU 和 SKU 千万别混

电商建表最容易搞错的，是把“商品”和“规格商品”当成一回事。我在 goshop 里分了两张表：product_spu表示一件商品，比如一件 T 恤；product_sku表示具体可下单的规格，比如“白色 M 码”。库存挂在 SKU 上，价格也挂在 SKU 上，SPU 只保存商品标题、主图、详情等公共属性。

这么设计的原因很实际：同一个商品会有多个颜色、尺寸，每个规格的库存和价格可能不一样。如果不拆开，后面加“按规格查库存”的功能时，SQL 会写得很难看，甚至要改表结构。我在建表时会额外注意索引：SKU 表里对spu_id建索引，因为所有按商品查规格的请求都会走到这个字段；sku_code加唯一索引，防止同一个规格被重复创建。

3.2 订单模型：主订单加订单明细，一对多是标配

订单相关的表我建议一开始就拆成orders和order_items。orders存订单号、用户 ID、订单状态、支付金额、收货信息、创建时间；order_items存下单时的快照信息，包括 SKU ID、商品名称、规格描述、单价、数量、小计。

关键点是，order_items里商品名称和单价必须在下单时复制一份，不能只存 SKU ID，再靠联表去查“当时卖多少钱”。因为商家改价格、改标题是常有的事，订单属于历史事实，不能被商品信息变更影响。这一点在财务对账时非常重要。同样的道理也适用于优惠金额和运费，这些都要在订单生成的那一刻固定下来。

3.3 金额字段：永远不要用 float 存钱

建表第一原则：金额用整数存“分”，不用decimal(10,2)，更不用float。比如商品售价 99.9 元，在数据库里存 9990。原因是浮点数存在二进制无法精确表示小数的问题，多个金额一累加就会出现“0.1 + 0.2 不等于 0.3”的经典错误；decimal虽然能用，但在一些语言和 ORM 里容易出现类型转换问题，还要额外处理精度。用整数“分”最简单粗暴，所有计算都在代码里用整数完成，前端展示时再除以 100。

3.4 库存扣减：一次 UPDATE 就是最可靠的锁

库存表我最常用的结构是inventory(sku_id, stock)，不存冗余字段。扣减库存时不要先 SELECT 再 UPDATE，那样两个请求同时读到同一个库存数，就有超卖风险。正确做法是直接在事务里执行：

UPDATE inventory SET stock = stock - 1 WHERE sku_id = ? AND stock >= 1;

如果RowsAffected等于 0，说明库存不足，立即回滚。这种方式用数据库行锁保证了原子性，代码里不需要手动加锁，并发量不高的阶段完全够用。等真到了秒杀级别，再考虑 Redis 预扣、MQ 异步写库那些更复杂的方案。

4. 从注册到下单，核心接口是怎么一步步落地的

4.1 注册登录：密码用 bcrypt，状态用 JWT

用户模块是第一道门。注册时密码一定不能明文保存，我用bcrypt哈希，成本因子设为 10。登录验证通过后，签发一个 JWT，放到接口调用的Authorization头里。

JWT 的好处是服务端不需要为每个登录用户存储 session，用户身份直接写在 token 里，适合前后端分离。我设置 72 小时过期，并在 token 中带上user_id和角色字段。注意 JWT 的 secret 需要足够长且从环境变量注入，生成 token 时要在签名前把过期时间、用户 ID 都带上，不能只签一个空字符串。整个过程中还有一个容易忽视的安全点：用户 ID 不要直接用自增 id 暴露给前端，业务上可以另外生成一个user_no，这样订单、购物车里引用的是业务编号，外部更难猜测真实规模。

4.2 商品列表：Redis 缓存穿透和缓存击穿都要防

商品列表是流量最大的读接口。我加了 Redis 缓存，key 按product:list:category:{id}设计，过期时间 10 分钟。每次写商品时主动删除相关缓存，而不是依赖过期，避免用户看到太久的老数据。

这里有个学院派不讲但实战会踩的坑：如果某个分类下没有商品，查询结果为空，这时不能什么都不缓存，否则恶意请求会反复打到数据库，造成缓存穿透。我习惯把空列表也缓存 1 分钟，或者直接对不存在的 key 缓存一个空 JSON，这样能挡掉一部分请求。对于热点商品详情，还会在回源数据库时加一个简单的“单飞锁”，只让一个请求去查库，其他请求短暂等待后复用缓存，避免缓存刚过期的那一瞬间把数据库打垮。

4.3 购物车：临时数据但别丢精度

购物车表我保持得比较简单：cart_item(id, user_id, sku_id, quantity, selected, created_at)。添加购物车时先判断该 SKU 是否已在购物车，如果已存在就累加数量，不要插入重复行。同时要重新从 SKU 表读一次库存，如果库存已经不满足数量，要立即提示用户，而不是等到下单才发现。

购物车里的价格我一般不以购物车为准，因为价格在购物车阶段只是展示，真正结算时必须重新读取 SKU 当前售价。这样可以避免用户加购之后商家调价，最后结算时价格不一致导致的纠纷。购物车数量上限也要做限制，比如单个 SKU 不超过 99 件，购物车总条目不超过 100，防止一个用户塞几万条数据把表撑大。

4.4 下单接口：一个事务里完成三件事

提交订单是整个项目里最需要小心的接口。我在service层这样做：

1. 检查购物车项或直接传的商品 SKU 列表，全部存在且库存足够。
2. 用“幂等键”查是否已下过单。前端每次提交订单时生成一个唯一idempotency_key，服务端在 Redis 里先 SETNX，如果已存在直接返回上一次结果，避免重复下单。
3. 开启数据库事务，生成订单号和订单明细，扣减库存，锁定购物车中的对应商品，最后提交事务。

核心代码思路是这样的：

func (s *OrderService) CreateOrder(ctx context.Context, userID int64, req CreateOrderReq) (*OrderVO, error) { ok, err := s.redis.SetNX(ctx, "order:dup:"+req.IdempotencyKey, req.OrderNo, 10*time.Minute).Result() if err != nil { return nil, err } if !ok { return nil, ErrDuplicateOrder } err = s.db.Transaction(func(tx *gorm.DB) error { var inv Inventory err := tx.Clauses(clause.Locking{Strength: "UPDATE"}). Where("sku_id = ?", req.SkuId). First(&inv).Error if err != nil { return err } if inv.Stock < req.Quantity { return ErrInsufficientStock } if err := tx.Model(&inv). Update("stock", gorm.Expr("stock - ?", req.Quantity)).Error; err != nil { return err } if err := tx.Create(&order).Error; err != nil { return err } return tx.Create(&orderItems).Error }) if err != nil { return nil, err } return s.buildOrderVO(ctx, order) }

注意这里我用了行锁锁住库存记录，再 UPDATE。很多人觉得一条原子 UPDATE 就够了，但在“先查后写”的业务逻辑多的时候，显式加锁更保险，也更便于在代码里维护。如果并发量真的很低，完全可以只保留那个原子 UPDATE。

4.5 支付回调：以结果为准，不能只信前端

支付回调是订单状态从“待支付”变“已支付”的转折点。这里必须注意幂等：支付平台可能会因为网络重试回调同一个支付单多次，服务端要用payment_id做唯一索引，重复回调时要么直接返回成功，要么只执行一次状态流转。退款同理，要记录退款流水，不能只改订单状态。

我在代码里把支付回调处理也放到事务中：先查询支付流水是否存在，不存在才创建并更新订单状态。订单状态机的变更我都封装在 service 层，禁止在 handler 里直接改状态字段，这样后面加售后状态时不会出现状态互相乱改的情况。回调接口还要记得做签名验签，不能只凭 HTTP 请求里带几个参数就认定支付成功。

5. 本地联调与部署：把 Docker Compose 用明白

5.1 一键拉起 MySQL 和 Redis

本地开发最常见的痛苦，是“在我电脑上可以跑”但其实跑不了。我现在的做法是项目根目录放deploy/docker-compose.yml，执行一条命令就能把 MySQL 和 Redis 拉起来：

services: mysql: image: mysql:8.0 environment: MYSQL_ROOT_PASSWORD: root MYSQL_DATABASE: goshop MYSQL_USER: goshop MYSQL_PASSWORD: goshop123 ports: - "3306:3306" volumes: - mysql_data:/var/lib/mysql redis: image: redis:7 ports: - "6379:6379" volumes: - redis_data:/data volumes: mysql_data: redis_data:

本地第一次启动的顺序是：docker compose up -d，然后跑迁移脚本，最后启动 Go 服务。这里必须提醒一个坑：如果你在容器里跑应用、在宿主机跑 MySQL，连接地址写127.0.0.1没问题；但如果两个服务都在容器里，就不能再写127.0.0.1了，要写 docker compose 里的服务名mysql。不少初学者第一次联调失败，都是栽在这个地址上。

5.2 数据库迁移：AutoMigrate 可以起步，但正式库要留 SQL

GORM 的AutoMigrate在开发阶段很好用，能根据模型自动建表。但我上了正式环境后，会把建表和字段变更都整理成 SQL 迁移文件，放在migrations目录里，比如001_init.sql。原因是生产环境改表不能靠自动同步，风险太大；有 SQL 文件就能在发版前先执行变更，出问题也好回滚。建立索引也写在迁移脚本里，比如订单表的order_no加唯一索引，user_id + status加联合索引，金额查询走索引，这些提前做了比上线后再优化舒服得多。

5.3 日志和错误码：统一到让人一看就懂

一个小型接口项目如果没有统一错误码，前端排错会非常痛苦。我在 goshop 里定了一套简洁规则：HTTP 状态码只表示这次请求“通没通”，业务错误码表示“为什么没通”。比如 200 返回但 code 是 40001，表示用户权限不足；503 表示依赖服务挂了。响应格式统一成这样：

{ "code": 0, "message": "ok", "data": {} }

中间件会在每个请求进入时生成一个request_id，日志里都带上它。这样一旦用户反馈问题，我只要拿到 request_id，就能在日志里把整条链路串起来。别小看这个习惯，没有 request_id，排查线上问题经常要翻半天日志。

6. 常见问题与排查技巧：这些坑我先替你踩过了

6.1 启动时报数据库连接失败，第一件事查什么

我遇到最多的问题就是连不上 MySQL。按顺序排查：先docker compose ps看容器是不是 Running；再在宿主机mysql -h 127.0.0.1 -P 3306 -ugoshop -p试一下；最后看 Go 服务里的 MySQL 地址是不是和 compose 端口一致。这个流程能解决 80% 的连接问题，别一上来就怀疑网络不通。

6.2 商品详情缓存全是空数据，为什么会缓存击穿

如果某个热点商品缓存过期，同一时间大量请求同时去查数据库，这就是缓存击穿。我用两级手段解决：缓存里存空值防穿透，同时对热点 key 加“单飞锁”，也就是只允许一个请求回源数据库，其他请求短暂等待后复用缓存。实现上可以用 Redis 的SETNX做锁，拿到锁的请求写缓存，没拿到锁的等一下再读缓存。

6.3 订单重复提交，怎么用幂等键解决

前面代码里已经写了幂等键。这里再说一个容易忽略的点：幂等键要放在业务参数里，由前端每次生成，不能是用户 ID，也不能是商品 ID，否则同一用户同一商品就永远只能下一次单了。一般用 UUID 或“用户 ID + 时间戳 + 随机数”生成，服务端第一次收到时存入 Redis 并设置过期时间，后续相同请求直接返回“重复提交”。

6.4 库存扣减后和实际退款对不上，原因在什么地方

出现库存对不上，多半是在“下单扣减库存”和“取消订单回补库存”之间没有保证幂等。取消订单时如果没有判断订单状态，同一个取消请求被触发两次，库存就回补了两次。应对办法是：取消订单必须在事务里把订单状态从“待支付/已支付”更新为“已取消”，只有更新成功的行数大于 0，才执行库存回补。这个判断顺序不能反过来。

6.5 一个避坑速查表

最后再分享一个我个人的习惯：每次写完一个核心模块，我都会把接口的入参、出参、错误码整理成一份接口清单，放在docs目录里。这个动作看起来慢，但后面做管理端、写前端对接、甚至让同事接手，都会省下大量沟通成本。goshop 电商项目 01 阶段的核心就在这里，业务链路能跑通，表结构不返工，后面 02、03 阶段往里面加营销、加售后，地基才不会塌。