简介这是一份基于 Go 语言与 uni-app 框架开发的商城系统完整源码面向具备一定编程基础的全栈开发者、Go 后端学习者和电商项目二次开发人员。项目以 Go 为主力后端语言搭配 uni-app 构建跨平台商城前端适合用来理解前后端分离架构下的接口设计、数据流转与页面交互逻辑。压缩包共 384 个文件压缩后约 19.39MB文件类型以 vue 页面组件、js 脚本、go 源文件、scss 样式为主其中 vue 页面组件 184 个、js 脚本 96 个、go 源文件 36 个、scss 样式 19 个同时包含 Dockerfile、yaml、conf 等部署与热重载配置以及 gitignore、md、license 等项目说明文件。从内容预览可以看出项目兼顾本地开发便捷性与容器化部署需求目录结构完整便于按模块检索和二次开发。目前已有 105 人学习下载对想要快速上手 Go 后端、熟悉 uni-app 跨端开发或搭建商城业务骨架的人来说是一份值得参考的代码资产。1. 一个 zip 包里的商城系统值得拆开看的不只是页面打开这个基于gouniapp开发的商城系统.zip里面躺着.air.conf、Dockerfile、几个.gitignore和iconfont.css。单看文件列表像随手打包的 demo实际上它是一个能跑通的完整前后端工程Go 侧负责商品、订单、用户这类 REST APIUniApp 侧负责 H5、微信小程序和 App 三端复用。一个下午拆完我印象最深的反而不是业务代码而是三件事Air 热加载配置决定了开发效率iconfont.css 引错路径会让小程序端图标全部消失Dockerfile 和.gitignore的配合方式又决定了部署和多环境切换会不会翻车。这套项目适合刚把 Go 语言环境配置好的后端工程师也适合想用 UniApp 快速套一个商城界面的前端两类人读到的重点完全不同。2. Go 后端的骨架gin 路由、GORM 模型与 air 热加载2.1 先读懂.air.conf在干什么Air 是 Go 社区最常见的文件监听热加载工具原理是监听目录变更触发重新编译并重启子进程。压缩包里的.air.conf大概率长这样root . tmp_dir tmp [build] cmd go build -o ./tmp/main . bin ./tmp/main include_ext [go, html, yml, yaml, toml, json] exclude_dir [assets, tmp, vendor, frontend] delay 1000 stop_on_error true log air.loginclude_ext里有没有json直接决定改配置会不会触发重启exclude_dir里的frontend则保证你去动 UniApp 代码时后端不会跟着重新编译。delay 1000是防抖调度单位毫秒连续保存多个文件时它会合并成一次重启不是 Air 没反应。最容易踩的坑是bin路径如果项目里main.go不在根目录或go build输出到了别的目录第一次跑air就会报exec: ./tmp/main: no such file这时候先检查cmd和bin是否配对而不是重装 Air。参数作用换环境时要改什么cmd编译命令模块名或输出目录变化时bin启动的二进制路径与cmd中的-o保持一致include_ext哪些扩展名触发重载项目里有.proto或.tmpl要手动加exclude_dir哪些目录被忽略监听前端 node_modules、构建目录、tmpdelay变更后的重启延迟编辑器保存多次时调大到 1500~2000提示Air 是开发期工具别把它写进生产镜像。Dockerfile里用多阶段构建最终镜像不包含air和tmp。2.2 从.gitignore反推后端目录结构.gitignore出现多个说明这个仓库是按「后端 前端」分目录维护的或解压后文件夹发生了嵌套。一个典型的商城 Go 工程目录是这样的. ├── .air.conf ├── Dockerfile ├── main.go ├── config/ │ └── app.yaml ├── internal/ │ ├── api/ # 路由注册和 handler │ ├── model/ # GORM 数据模型 │ ├── service/ # 业务逻辑层 │ └── middleware/ # 鉴权、日志、CORS、recover ├── pkg/ │ └── response/ # 统一响应结构 └── frontend/ # uni-app 工程后端.gitignore通常包含/tmp/、*.log和config/app.yaml——后者的存在说明这套项目把真实数据库密码和环境变量放在本地不上库。前端.gitignore则必然有node_modules/和dist/。拿到压缩包后先按.gitignore里出现的路径核对解压是否完整比直接跑go run更省时间。2.3 用 GORM 定义商品模型的边界商城最核心的模型是商品ProductGORM 写法里有几个细节直接影响到前端拿到的 JSONtype Product struct { ID uint gorm:primaryKey json:id Name string gorm:size:100;not null json:name Price float64 gorm:type:decimal(10,2) json:price Stock int gorm:not null json:stock Description string gorm:type:text json:description,omitempty CreatedAt time.Time json:created_at DeletedAt gorm.DeletedAt json:- }DeletedAt标了json:-否则前端列表接口里会多出一堆deleted_at字段小程序端渲染时还得专门过滤它属于白费流量。omitempty用在description上空描述就不会序列化出去商品列表页的响应体积能小不少。Price 用decimal(10,2)而不是 float是为了避免浮点精度导致「商品价格出现 99.9999」这种客服来骂人的问题。2.4 统一响应结构避免小程序端到处判断商城后端给 UniApp 的响应格式必须固定前后端联调才省事。常规做法是统一成code message datapackage response func OK(c *gin.Context, data any) { c.JSON(http.StatusOK, gin.H{ code: 0, message: success, data: data, }) } func Fail(c *gin.Context, code int, msg string) { c.JSON(http.StatusOK, gin.H{ code: code, message: msg, data: nil, }) }注意Fail用的也是200状态码业务错误通过code区分。这样做的好处是 UniApp 端的请求拦截器只需要判断code是否为 0HTTP 状态码只留给网络层问题比如 401 未登录、500 服务崩溃。很多新手把「订单不存在」返回 404前端uni.request的success回调根本进不去只能在fail里抓逻辑一下就乱了。3. 前端 UniApp图标字体、登录态与 H5 定位的坑3.1 iconfont.css 的引入与字体文件路径压缩包里单独出现的iconfont.css一般放在frontend/src/static/iconfont/或frontend/static/通过 main.js 或 App.vue 引入// main.js import /static/iconfont/iconfont.css如果iconfont.css里引用字体是相对路径../fonts/iconfont.ttf那字体文件必须和 css 保持原目录结构解压后挪了位置就会 404。微信小程序端更特殊开发者工具里图标能显示真机上可能一片空白因为小程序不允许运行时加载本地字体文件体积超过 40KB 的 ttf 必须转成 base64 内联到 css 里。要是你打包后图标全没了优先排查这一步而不是怀疑框架版本。3.2 token 存储与请求封装商城接口几乎都要求登录态Authorization头不能漏。把 token 存到uni.setStorageSync再统一封装 requestconst BASE_URL http://localhost:8080/api/v1 function request(path, method GET, data {}) { return new Promise((resolve, reject) { uni.request({ url: ${BASE_URL}${path}, method, data, header: { Content-Type: application/json, Authorization: uni.getStorageSync(token) }, success(res) { const { code, message } res.data if (code 401) { uni.removeStorageSync(token) uni.navigateTo({ url: /pages/login/index }) return } if (code ! 0) { uni.showToast({ title: message, icon: none }) reject(res.data) return } resolve(res.data) }, fail(err) { uni.showToast({ title: 网络异常, icon: none }) reject(err) } }) }) }这段代码最关键的是把业务错误和网络错误分开处理code ! 0走 toastfail回调才走网络兜底。还有一处容易漏后端要求Authorization: Bearer token时header 里不能只写 token联合调试时会发现 Go 侧解析出空字符串接口返回 401。两边的字段名和前缀务必在接口文档里定死。3.3 H5 嵌入微信公众号获取定位其实不是 uni 的问题很多人用uni.getLocation在微信内置浏览器里取定位安卓上偶尔成功、iOS 一直失败接着开始怀疑是 H5 兼容性。真实原因通常是微信公众号的 JS 接口鉴权没过wx.getLocation依赖后端生成签名签名里又带着当前页面的 URL。这个 URL 必须是公众号后台「JS 接口安全域名」下匹配的地址本地localhost调试基本都会被拒。常见接法是先走微信授权拿 openid再让后端返回wx.config需要的参数import wx from jweixin-module wx.config({ debug: false, appId: res.appId, timestamp: res.timestamp, nonceStr: res.nonceStr, signature: res.signature, jsApiList: [getLocation] }) wx.ready(() { wx.getLocation({ type: gcj02, success: (loc) { // loc.latitude, loc.longitude 提交给后端 } }) })注意jweixin-module要 npm 安装后在小程序打包时排除否则产物体积会增大。真机测试时别再一边开着 fiddler 抓包一边点授权微信 JS 接口对签名验证有严格时效页面缓存可能导致签名 URL 和实际 URL 不一致报错往往是invalid signature。3.4 manifest.json 必须核对的配置表UniApp 打包前manifest.json是关键。常见坑按下面这张表排查配置项位置作用常见问题mp-weixin.appidmanifest.json 小程序部分微信小程序 ID留空时开发者工具报 appid 不存在h5.router.basemanifest.json H5 部分H5 部署的子路径部署到子目录不设置直接白屏vueVersionmanifest.json 全局Vue 2 / Vue 3vue2 转 vue3 后this.$emit行为不一致app-plus.distributemanifest.json App 部分安卓/iOS 模块权限App 端定位、NFC、蓝牙都要在此声明安卓应用市场上架时很多审核失败是因为manifest.json里的权限声明过多——你声明了短信读取但代码里根本没用到。上架前把用不到的权限在可视化界面里关掉比写一堆申述邮件有效得多。4. 联调阶段跨域、错误恢复和 Docker 镜像4.1 CORS 中间件H5 端联调时最常见的现象是前端uni.request成功了但浏览器上报跨域错误。小程序端没有同源策略限制H5 有所以后端必须加 CORS 中间件func CORS() gin.HandlerFunc { return func(c *gin.Context) { c.Header(Access-Control-Allow-Origin, *) c.Header(Access-Control-Allow-Methods, GET,POST,PUT,DELETE,OPTIONS) c.Header(Access-Control-Allow-Headers, Content-Type,Authorization) if c.Request.Method http.MethodOptions { c.AbortWithStatus(http.StatusNoContent) return } c.Next() } }Access-Control-Allow-Origin设为*时浏览器不允许同时携带Authorization这种非简单头一旦前端带上 token 就会直接拦截。稳妥做法是配置成白名单地址数组从config/app.yaml读取。还有一个隐蔽问题OPTIONS预检必须走AbortWithStatus(http.StatusNoContent)如果继续调c.Next()handler 会因为请求体为空报 EOF日志里出现一串EOF错误。4.2 统一 recover 和错误码转换商城系统跑在公网上panic 崩掉可不行。Gin 自带gin.Recovery()返回 500但响应格式不是code/message/data前端拦截器会把message读成空字符串。项目里应该有一个自定义 recover 中间件func Recovery() gin.HandlerFunc { return func(c *gin.Context) { defer func() { if err : recover(); err ! nil { ginLogger(c.Request.Context()).Error(panic, zap.Any(err, err)) c.JSON(http.StatusInternalServerError, gin.H{ code: 500, message: internal error, data: nil, }) c.Abort() } }() c.Next() } }日志要带上请求 ID 或用户 ID否则线上一个 panic 出现你对着堆栈根本不知道是谁在什么时候触发的。此外 GORM 查不到数据时返回gorm.ErrRecordNotFound别直接透传 500应在 service 层把它转成response.Fail(c, 404, 商品不存在)前端才能给用户一个友好的提示。常见误用是在 handler 里写if errors.Is(err, gorm.ErrRecordNotFound)但 service 已经把错误包装过一层errors.Is失效所以要么统一包装要么统一在 service 层转换。4.3 Dockerfile 多阶段构建别把前端和 tmp 打进去压缩包里那个Dockerfile理想状态是一个多阶段构建# 构建阶段 FROM golang:1.22-alpine AS builder WORKDIR /app COPY go.mod go.sum ./ RUN go mod download COPY . . RUN CGO_ENABLED0 GOOSlinux go build -o /app/shop . # 运行阶段 FROM alpine:3.20 WORKDIR /app COPY --frombuilder /app/shop . COPY config/ ./config/ EXPOSE 8080 CMD [./shop]CGO_ENABLED0保证编译出的二进制能在 alpine 里直接跑不需要 gcc。但注意COPY . .会把frontend/、tmp/、.git/全拷进构建上下文镜像体积能做 500MB。正确做法是加一个.dockerignorefrontend/ tmp/ .git/ *.log .air.conf.air.conf不进去因为它是开发期工具tmp/不进去因为那是 Air 的产物。镜像最终只留二进制和配置文件体积会小很多启动也更干净。如果前端静态文件也需要后端托管那就得另写一个 Nginx 阶段把 H5 的dist/拷进去后端 API 同域部署这样 H5 连跨域问题都省了。4.4 关于go env和g env的排错联调时有人会问go env和g env是不是一个东西。go env是 Go 官方命令g在多数环境里不是 Go 的别名只是某些人.zshrc里写了alias ggo。所以执行g env报command not found不代表 Go 环境配置有问题去掉 alias 试试就知道。如果你在用装了 Go 插件但没装 gopls 的编辑器也会看到类似gopls command is not available的提示那是语言服务器没装不是go env的问题跑一遍go install -v golang.org/x/tools/goplslatest就能解决。这类问题在团队协作时特别容易互相误导分清「语言环境」和「工具链」两个层面。5. 落地技巧健康检查、curl 验证与脚手架文件的取舍5.1 用 curl 快速验证接口和 CORS不要每次联调都打开浏览器 F12先在后端起服务后直接 curlcurl -i -X POST http://localhost:8080/api/v1/user/login \ -H Content-Type: application/json \ -d {username:admin,password:123456}-i会把响应头打出来。你重点看两个东西响应体里的code是不是 0以及Access-Control-Allow-Origin是否存在。如果 H5 前端报跨域但 curl 里已经看到 CORS 头说明是前端请求头带了Authorization而白名单没放行如果 curl 里根本没有 CORS 头说明你没注册 CORS 中间件。再进一步验证登录态curl -i -X GET http://localhost:8080/api/v1/products \ -H Authorization: Bearer token对于商品列表这种高频接口响应时间超过 200ms 就要考虑是不是 GORM 没加索引别急着甩锅给网络。5.2 给 Docker 配上 healthcheck生产环境用 Docker Compose 或 K8s 时容器能不能提供服务不能只看进程在不在。给商城后端加一个/health接口再在 Compose 里声明健康检查# main.go 里注册 r.GET(/health, func(c *gin.Context) { c.JSON(200, gin.H{code: 0, message: ok}) })services: shop: build: . ports: - 8080:8080 healthcheck: test: [CMD, wget, -qO-, http://localhost:8080/health] interval: 30s timeout: 3s retries: 3alpine 里没有 curl所以 healthcheck 用 wget。如果你的运行镜像没有 wget 也没有 curlhealthcheck 会一直失败容器被编排系统杀掉后重启日志里反复出现unhealthy状态。这是一个非常实际但容易漏掉的细节。5.3 解压后先保留下这几个文件.air.conf、Dockerfile、.gitignore、iconfont.css这四个文件在项目里分别代表开发环境、部署环境、仓库规范和前端资源基础。很多人解压后第一件事就是删掉配置想自己重写实际上只要把.air.conf的cmd路径改成自己的模块名把Dockerfile里的COPY . .改成COPY --frombuilder整套脚手架直接能用。最后分享一个判断解压完整性的小技巧看.gitignore的数量和内容。如果根目录和frontend/下各有一个说明仓库结构正常如果解压后发现有五六个同名.gitignore堆在一起说明 zip 包是在多个嵌套目录下分别打包的此时先去理清目录层级不要贸然跑go mod tidy否则模块路径会和你的工作目录对不上go build报一堆package xxx is not in GOROOT那不是代码问题只是根目录找错了。本文还有配套的精品资源点击获取