简介：一份基于 gin+gorm+redis+mysql 读写分离架构的电子商城项目源码，面向 Go 后端学习者、毕业设计与课程设计开发者。项目实现了 JWT 鉴权、CORS 跨域、AES 对称加密，并引入 ELK 日志平台、jaeger 链路追踪与 skywalk 监控；其中 JWT 保证接口访问安全，AES 用于敏感数据加密，CORS 解决跨域调用，ELK 与链路追踪工具则让日志检索和问题定位更高效。压缩包共 131 个文件，以 Go 源码为主，另含 SQL 初始化脚本（建表与初始数据）、YAML 配置、Dockerfile、Makefile、说明文档及界面截图，配置与容器化文件支持快速搭建环境，图片可辅助核对运行效果，整体仅 666KB，目录结构清晰，按功能模块划分便于定位与二次开发。已有 387 人学习下载。项目内包含用户、商品、Kafka 等业务模块，分层清晰，可参考其接口设计与中间件整合方式。借助该项目可掌握读写分离落地方法、JWT 鉴权与 AES 加密的工程实践，以及从配置到部署的完整组织思路，同时也是一份完整的 Go 工程样例，适合作为课设改造或 Go 微服务入门的参考资料。
1. 电子商城后端项目拆解：读写分离不是配电柜而是分水岭
多数人第一次接触“MySQL 读写分离”时，第一反应是这是 DBA 该操心的东西——配个主从、加个代理就完事，和业务代码没关系。这个基于 gin + gorm + redis + mysql 的电子商城后端项目，恰恰把读写分离做成了一道分水岭：主库扛订单写入，从库扛商品列表、搜索和报表查询，流量一上来，先垮掉的往往不是 CPU，而是那条被慢查询拖死的主库连接池。项目把 JWT 鉴权、CORS 跨域、AES 对称加密、ELK 日志体系、jaeger 链路追踪、kafka 异步解耦全部揉进了一个可复现的工程里。适合两类人：一类是要做课设、毕设但想把架构讲清楚的学生，另一类是小团队后端，想上主从复制但不想把生产环境的坑带回本地慢慢试错。
2. 读写分离的落地骨架：gorm 主从路由与连接池参数
2.1 主从复制的底座：先让 MySQL 自己转起来
读写分离的前提是主从复制已经跑通，否则 gorm 把读请求路由到从库，从库数据落后主库几秒，商品库存显示就会翻车。本地复现我建议直接用 docker 起两个 MySQL 实例，避免在一台机器上装两个 mysqld 的端口冲突和权限问题。
# 主库 docker run -d --name mysql-master \ -p 3306:3306 \ -e MYSQL_ROOT_PASSWORD=master123 \ -v $PWD/master.conf:/etc/mysql/conf.d/master.conf \ mysql:5.7 # 从库 docker run -d --name mysql-slave \ -p 3307:3306 \ -e MYSQL_ROOT_PASSWORD=slave123 \ -v $PWD/slave.conf:/etc/mysql/conf.d/slave.conf \ mysql:5.7主库的master.conf至少要有三行：server-id=1、log-bin=mysql-bin、binlog_format=ROW。从库只配server-id=2，不需要开 log-bin。注意binlog_format必须用 ROW，gorm 批量更新在 STATEMENT 格式下会产生不可控的锁竞争。
# 在从库容器里执行 docker exec -it mysql-slave mysql -uroot -pslave123 \ -e "CHANGE MASTER TO MASTER_HOST='<主库IP>', MASTER_PORT=3306, MASTER_USER='repl', MASTER_PASSWORD='repl123', MASTER_LOG_FILE='mysql-bin.000001', MASTER_LOG_POS=154;" docker exec -it mysql-slave mysql -uroot -pslave123 -e "START SLAVE;"这段的MASTER_LOG_FILE和MASTER_LOG_POS不是固定的，主库要先执行SHOW MASTER STATUS;拿当前偏移量。对新手来说，最容易翻车的就是直接套用网上教程里的 154 这个数值，一旦主库之前写过数据，这个位置就是错的，从库会一直报Got fatal error 1236。复制账号要单独建，别用 root 权限裸奔。
提示：
MASTER_HOST填 docker 宿主机的内网 IP，别填localhost。容器内解释localhost指向自己，永远连不上主库。
2.2 gorm 双数据源与读写路由：从 config.yaml 到上下文标记
项目里config.yaml.example已经预留了双数据源的配置位，照它的结构补全即可。核心思路是用两个独立的gorm.DB实例，一个绑主库一个绑从库，业务层通过一个路由中间件决定走哪条连接。
datastore: master: host: 127.0.0.1 port: 3306 username: root password: master123 database: mall slave: host: 127.0.0.1 port: 3307 username: root password: slave123 database: mall pool: max_open_conns: 100 max_idle_conns: 20 conn_max_lifetime: 60m参数说明：max_open_conns控制连接池上限，写多读少的商城项目主库给 100 够用，从库可以放宽到 200；conn_max_lifetime设 60 分钟，是为了避免 MySQL 的wait_timeout把空闲连接回收后，gorm 还拿旧连接去查询。连接池配小了，压测时会出现database is locked之类的假象，实际是连接耗尽。
func InitDB(cfg *Config) (*gorm.DB, *gorm.DB) { master, err := gorm.Open(mysql.Open(cfg.Master.DSN()), &gorm.Config{}) if err != nil { log.Fatalf("master db connect failed: %v", err) } slave, err := gorm.Open(mysql.Open(cfg.Slave.DSN()), &gorm.Config{}) if err != nil { log.Fatalf("slave db connect failed: %v", err) } return master, slave }DSN()方法里把连接池参数拼进去，形如user:pass@tcp(127.0.0.1:3306)/mall?charset=utf8mb4&parseTime=True&loc=Local。路由的核心是中间件里设置上下文标记，然后在 repository 层根据标记选库。
func dbSelector(c *gin.Context) gin.HandlerFunc { return func(c *gin.Context) { if c.Request.Method == "GET" { c.Set("use_slave", true) } else { c.Set("use_slave", false) } c.Next() } }逻辑说明：GET 请求读从库，非 GET 请求写主库，这个规则对绝大多数商城接口成立。但有一个例外——登录后立刻查购物车，写操作刚提交，读从库会因复制延迟读到旧数据，这种场景需要在 repository 层手动强行走主库。参数上，use_slave这个 key 用 string 类型，避免interface{}断言出错，gorm 的WithContext能直接拿到中间件塞进去的标记。
2.3 事务逃逸：为什么写操作必须走主库
读写分离最隐蔽的坑是事务逃逸。一个 Gin handler 里先查用户余额、再扣款更新余额，如果查询走了从库，更新走了主库，从库同步延迟超过 500ms 时，事务读到的余额是脏的，扣款结果直接错误。项目里事务代码必须使用主库句柄。
func (r *OrderRepo) CreateOrder(ctx context.Context, order *Order) error { return r.master.WithContext(ctx).Transaction(func(tx *gorm.DB) error { if err := tx.Create(order).Error; err != nil { return err } // 行锁更新库存，必须走主库 var inv Inventory if err := tx.Clauses(clause.Locking{Strength: "UPDATE"}). Where("sku_id = ? AND stock >= ?", order.SkuID, order.Num). First(&inv).Error; err != nil { return err } return tx.Model(&inv). Update("stock", gorm.Expr("stock - ?", order.Num)).Error }) }逻辑说明：r.master是固定的主库句柄，事务内所有查询和写入都锁在同一连接上，避免WithContext切库导致的连接不一致。Clauses(clause.Locking{Strength: "UPDATE"})是悲观锁，下单场景库存是硬约束，用乐观锁会在高并发下产生大量重试，反而拖慢主库。
提示：从库实例记得设为只读，
read_only=1。不加这个保护，一旦代码里漏了路由，写操作落到从库会直接失败而不是悄悄丢失，这其实是好事——让 bug 在测试环境就暴露。
3. JWT 鉴权与 AES 加密：登录态的双保险与三个边界
3.1 JWT 注册与校验：gin 中间件的标准写法
项目里user.go和product.go都依赖登录态，JWT 中间件是全局注册的。用golang-jwt/jwt/v5解析Authorization头，拿到user_id后塞进 gin 的 Context。
func JWTAuth(secret string) gin.HandlerFunc { return func(c *gin.Context) { tokenStr := c.GetHeader("Authorization") if tokenStr == "" || !strings.HasPrefix(tokenStr, "Bearer ") { c.AbortWithStatusJSON(401, gin.H{"error": "missing token"}) return } token, err := jwt.Parse(strings.TrimPrefix(tokenStr, "Bearer "), func(t *jwt.Token) (interface{}, error) { if _, ok := t.Method.(*jwt.SigningMethodHMAC); !ok { return nil, fmt.Errorf("unexpected signing method") } return []byte(secret), nil }) if err != nil || !token.Valid { c.AbortWithStatusJSON(401, gin.H{"error": "invalid token"}) return } claims, ok := token.Claims.(jwt.MapClaims) if !ok || claims["user_id"] == nil { c.AbortWithStatusJSON(401, gin.H{"error": "bad claims"}) return } c.Set("user_id", claims["user_id"]) c.Next() } }参数说明：secret从配置文件的jwt.secret读取，生产环境用环境变量注入，别写死在代码里。jwt.Parse的验签回调必须检查SigningMethodHMAC，否则攻击者可以用none算法伪造 token。过期时间放在 claims 里，签发时设exp，项目里默认 2 小时，刷新 token 用 redis 记录过期状态。
单点登录的额外处理：用户修改密码或强制下线时，把jti（token ID）写进 redis 黑名单，中间件里每次请求都查一次 redis。这个项目里 redis 本来就是标配，顺手用上，不增加额外组件。
3.2 AES 对称加密：BASE64 与密钥轮换的 I/O 细节
商城里的手机号、收货地址这类 PII 字段，入库前用 AES 加密是项目摘要里明确写的功能。这里选AES-128-CBC配合 PKCS7 padding，输出 BASE64 字符串存储，能兼容 MySQL 的 varchar 字段。
func AESEncrypt(plaintext, key []byte) (string, error) { block, err := aes.NewCipher(key) if err != nil { return "", err } blockSize := block.BlockSize() padding := blockSize - len(plaintext)%blockSize plaintext = append(plaintext, bytes.Repeat([]byte{byte(padding)}, padding)...) ciphertext := make([]byte, len(plaintext)) iv := make([]byte, blockSize) if _, err := io.ReadFull(rand.Reader, iv); err != nil { return "", err } mode := cipher.NewCBCEncrypter(block, iv) mode.CryptBlocks(ciphertext, plaintext) return base64.StdEncoding.EncodeToString(append(iv, ciphertext...)), nil }逻辑说明：随机 IV 拼在密文头部，解密时先截取前blockSize字节作为 IV，这样同一明文每次加密结果不同，避免攻击者通过密文比对猜测重复数据。BASE64 输出长度是明文长度的 4/3 再加 IV 的编码长度，varchar 字段长度按这个公式预留。
密钥配置：config.yaml.example里的aes.key要求 16/24/32 字节，对应 AES-128/192/256。项目用 16 字节即可，密钥轮换时要兼容旧数据——每次解密先尝试新 key，失败再用旧 key，这是最朴素的双密钥方案。
3.3 CORS 与 token：分布式下跨域不背黑锅
前端部署在独立域名时，CORS 配置错误会让所有带 Authorization 头的请求变成 401 或 CORS error，排查时很容易误伤 JWT 验证逻辑。
func CORSMiddleware() gin.HandlerFunc { return func(c *gin.Context) { c.Header("Access-Control-Allow-Origin", config.AllowOrigin) c.Header("Access-Control-Allow-Methods", "GET, POST, PUT, DELETE, OPTIONS") c.Header("Access-Control-Allow-Headers", "Authorization, Content-Type, X-Requested-With") c.Header("Access-Control-Max-Age", "86400") if c.Request.Method == "OPTIONS" { c.AbortWithStatus(204) return } c.Next() } }关键点：Access-Control-Allow-Headers必须显式包含Authorization，否则浏览器会拦截带 token 的请求；OPTIONS预检请求要在 JWT 中间件之前直接 204 返回，不然预检请求没有 Authorization 头，会被 JWT 中间件拦下来。中间件注册顺序：CORS -> JWT -> 路由，顺序反了就是一场跨域与鉴权的连环翻车。
4. ELK + jaeger + kafka：日志链路三件套的落地与取舍
4.1 日志管道：filebeat 到 logstash 再到 kibana
项目里日志不是打到控制台就完事，而是走 ELK 沉淀。应用把 JSON 格式日志写到本地文件，filebeat 采集后发给 logstash 清洗，最后进 elasticsearch 由 kibana 展示。filebeat.yml 的关键配置：
filebeat.inputs: - type: log enabled: true paths: - /var/log/mall/*.log json.keys_under_root: true json.add_error_key: true output.logstash: hosts: ["logstash:5044"]参数说明：json.keys_under_root让 JSON 字段直接落在顶级，kibana 里就能直接按user_id、trace_id过滤。应用侧日志要带上trace_id，这里用 jaeger 的 span 上下文生成，排障时一条链路日志全串起来。logstash 端做 grok 解析容易过度设计，JSON 日志直接透传最简单，只在缺字段时补@timestamp。
4.2 链路追踪：jaeger 与 skywalking 的选型逻辑
这两个都是链路追踪方案，但定位不同。jaeger 更偏开发者，部署轻量、支持 OTLP 协议，和 Go 生态配合顺手；skywalking 更偏运维平台，自带告警、拓扑图和服务网格支持，但部署重、学习曲线陡。这个商城项目规模下，我倾向 jaeger——应用的config.yaml.example里写好JAEGER_AGENT_HOST和JAEGER_AGENT_PORT，中间件里初始化 tracer，每个请求生成 trace_id 打进日志即可。skywalking 适合后续服务数量超过十个、需要聚合拓扑的时候再考虑。不管选哪个，trace 数据不要落 MySQL，直接进 ES，避免给数据库加无谓负载。
4.3 kafka 解耦：日志落库与削峰的配合姿势
kafka.go 是项目里的异步枢纽，商品浏览记录、订单创建事件都走它。典型场景：用户下单后，订单服务发一条消息到 kafka，库存服务消费后扣减库存，同时一条浏览记录消息被日志消费者写入从库。生产者：
func (k *KafkaProducer) SendOrderCreated(order *Order) error { msg, _ := json.Marshal(order) return k.Producer.SendMessages(context.Background(), &kafka.Message{ TopicPartition: kafka.TopicPartition{Topic: &k.OrderTopic, Partition: kafka.AnyPartition}, Value: msg, }) }参数说明：分区数建议 3~6 个，主题副本数在 docker 环境设为 1，生产环境至少 3。发送时RequiredAcks设WaitForAll，防止 leader 写完就返回、follower 还没同步导致的消息丢失。消费者的关键参数：EnableAutoCommit设为 false，手动提交 offset，处理成功后再 commit，避免处理异常时消息被标记为已消费导致丢单。
for { msg, err := consumer.ReadMessage(ctx) if err != nil { continue } if err := processOrderEvent(msg); err == nil { consumer.CommitMessage(ctx, msg) } }这么写的代价是可能重复消费，但重复消费能靠业务操作幂等兜底，消息丢失则没有后悔药，两害相权取重复。
5. 常见问题与避坑：我在这套架构里真实撞过的四个坑
5.1 MySQL SSL 连接错误，go-sql-driver 连测试环境就报错
现象：本地连接 docker MySQL，启动就报tls: first record does not look like a TLS handshake。原因：MySQL 8.0 默认开了 SSL，客户端没用 TLS 连接，驱动和服务器协商失败。解决：DSN 加tls=skip-verify跳过证书校验，或者建库时指定--ssl=0关闭 SSL。生产环境该开着，但本地测试没必要为证书折腾。
5.2 读写分离后，从库数据永远比主库慢一步
现象：商品列表页显示刚上架的商品，但用户点详情页却提示不存在。原因：列表查询走了从库，详情页走了主库——不是路由串了，而是复制延迟造成的主从数据不一致。解决：写操作后 1 秒内的读强制走主库，项目里用 redis 写一个write_recently标志，下游查询先查这个 flag。真正治本的是让从库parallel_workers打开并行复制，而不是加大主库性能。
5.3 JWT token 过期了但 redis 黑名单查不到
现象：用户点了退出登录，token 还能继续访问接口，直到自然过期。原因：logout 接口只把 jti 写进 redis，但没设过期时间，而 JWT 中间件里查黑名单用的 key 命名和写的时候不一致。解决：黑名单 key 统一定为jwt:blacklist:<jti>，过期时间设为与 token 剩余有效时间一致。这是典型的自己埋雷，同一个常量要抽出来，不然后端几个人写 project 和 mall 两种前缀，排查时能查到怀疑人生。
5.4 kafka 消费者重复消费导致日志双写
现象：kibana 里同一 trace_id 的日志出现两条，但接口只调用了一次。原因：EnableAutoCommit默认 true，offset 在拉取后自动提交，进程在处理时崩溃重启，rebalance 后重新消费同一批消息。解决：手动提交，配合业务幂等，加一个if EXISTS(select 1 from order_log where trace_id=?)的判重。这套方案关键是手动 commit 不能放在 process 函数内部，否则局部返回忘记提交，offset 卡住，消费组持续 rebalance。
6. 复现验证与调优收尾：压测、权限验证和部署检查
开始复现前，先核对一遍 Dockerfile 和 config.yaml.example 的配置文件。Dockerfile 里 Go 应用建议用多阶段构建，FROM golang:1.20 AS builder编译产物扔进alpine运行时镜像；容器里跑非 root 用户。config.yaml.example里所有密码用REPLACE_ME占位，别直接继承默认值。启动顺序是 MySQL 主从 -> Redis -> kafka -> 应用，中间套一个 docker-compose 的前置健康检查，等 MySQLSHOW SLAVE STATUS的Slave_IO_Running和Slave_SQL_Running都是 Yes 再启动应用，不然应用启动时建表建索引会连到还没就绪的主库。
读写分离是否生效，验证方法很简单：分别查看主库和从库的SHOW PROCESSLIST，主库要有 INSERT/UPDATE 在执行，而 SELECT 雨后春笋般出现在从库。压测用ab -n 10000 -c 100打商品列表接口，观察从库的 QPS 曲线远高于主库，说明路由生效且复制链路没拖后腿。如果从库 QPS 一直为零，回头查中间件的use_slave标记是否被 gorm 的WithContext正确传播——这个标记在跨 goroutine 传递时最容易丢，这是我在这个项目里踩得最疼的坑，后来每个 repository 方法的第一行都先断言c.GetBool("use_slave")，确保路由标记不会静默丢失。从那以后我每次拉一个新工程下来，都强制先跑一遍全部测试用例，再启动主从复制链路，等两个Running: Yes打出来才开始改代码。这套组合拳打下来，部署翻车的概率小了很多，希望帮到你。
本文还有配套的精品资源，点击获取
