微信小程序服装商城实战：架构设计、核心模块与完整交付指南

服装商城是微信小程序实战里最经典的一道菜我做这个选题带过好几轮新人源码、文档、调试都摸过一遍。说句实话真正劝退新手的往往不是写页面而是三件事接口请求没有统一封装代码越写越乱购物车缓存逻辑草率用户清掉小程序重进后数据直接消失辛辛苦苦写完页面真机一跑就白屏或者样式错位。这篇文章就把这套服装商城从零到交付的完整思路拆开讲重点放在项目结构怎么设计、核心模块怎么实现、调试时哪些坑要提前躲开以及文档怎么写才能让这个项目在答辩或面试时拿得出手。1. 项目整体设计需求拆解与技术选型1.1 功能边界先理清拿到这个题目第一件事不是启动开发者工具而是把需求完整列出来。商城项目最大的坑就是想到哪做到哪写了一天代码才发现购物车和订单状态对不上。我一般会把功能拆成三层主链路第一层是用户核心链路从首页逛商品、分类筛选、商品详情、选规格加购物车、确认订单、支付、查看订单列表这套流程必须完整第二层是账号相关能力包括微信登录、收货地址维护、订单状态流转第三层是后台支撑练手项目可以做得简洁用云开发云函数或本地 Node 接口管理商品与订单即可。具体到服装品类还要单独考虑多规格问题。服装商品几乎都有颜色、尺码两种规格详情页通常要放模特图、细节图这些直接影响数据库字段设计。项目的数据表至少要有用户表、商品表、商品SKU表、购物车表、订单表、订单明细表六张订单和明细拆开是为了后面统计销量、退款、改状态都方便。1.2 为什么小程序是服装商城的好载体服装商城的用户行为有几个特点图片浏览量大、购买决策前会反复比较、用户希望随手分享给朋友。这三件事小程序恰好都擅长。H5 商城虽然也能做但打开速度和登录态的统一程度不如小程序用户分享后还需要重新登录App 的分发成本和审核成本对练手项目来说又太高了。小程序嵌在微信生态里扫码即用、授权登录、支付链路完整做完后演示起来也方便面试官手机扫个码就能看效果。开发框架方面原生小程序和 uni-app 都行。如果目标是做一套代码多处跑选 uni-app如果就是想把微信小程序这个题目做深做透原生小程序最稳妥微信官方文档全、调试工具强、遇到问题随便搜都有答案踩坑成本最低。1.3 数据模型设计数据模型是需求落地的第一步设计的标准是页面上需要展示什么字段就提前留好。商品表建议包含商品ID、标题、主图、轮播图列表、价格区间、分类ID、库存总量、销量、上架状态。SKU表单独建一张记录规格组合如红色-L、价格、库存、商品ID。订单表记录订单号、用户ID、总金额、状态、收货信息、支付时间订单明细表记录每个订单下的商品快照避免商品后续改价影响历史订单展示。价格字段这里要提醒一句数据库里存整数分前端展示时再除以100转成元千万不要直接存浮点数。电商项目最怕金额精度问题存分是最稳妥的做法。2. 源码组织与基础设施2.1 目录结构是项目的门面源码组织得好不好一眼就能看出项目是否规范。我常用的结构是页面、组件、接口、工具四层分离。miniprogram/ ├── app.js ├── app.json ├── app.wxss ├── pages/ │ ├── index/ // 首页 │ ├── category/ // 分类 │ ├── goods/ // 商品详情 │ ├── cart/ // 购物车 │ ├── checkOrder/ // 订单确认 │ ├── order/ // 订单列表 │ └── mine/ // 我的 ├── components/ │ ├── goods-card/ // 商品卡片 │ ├── sku-panel/ // 规格选择 │ └── empty-view/ // 空状态 ├── api/ │ ├── index.js // 接口路径汇总 │ ├── goods.js // 商品接口 │ └── order.js // 订单接口 ├── utils/ │ ├── request.js // 请求封装 │ ├── storage.js // 缓存封装 │ └── auth.js // 登录授权 └── styles/ └── common.wxss // 全局公共样式这个目录最重要的设计原则是把接口层从页面里抽离出来。页面里不直接出现 wx.request 字样所有请求通过 api 目录下的模块调用。这样接口地址变了只改一处页面代码干净也方便统一做埋点和错误上报。app.json 配置时要注意 tabBar 页面必须填在 pages 数组里而且 tabBar 的 icon 图片路径不支持网络地址只能放本地文件。新手经常在这里踩坑表现为 tabBar 图标不显示或者页面跳转时 tabBar 消失。2.2 统一请求封装请求封装是整个项目的基础设施值得多花一点心思。我的封装包含三件事统一拼接域名、统一注入 token 和 Content-Type、统一处理响应状态。// utils/request.js const BASE_URL https://api.example.com function request({ url, method GET, data {}, header {} }) { return new Promise((resolve, reject) { const token wx.getStorageSync(token) wx.request({ url: ${BASE_URL}${url}, method, data, header: { Content-Type: application/json, Authorization: token ? Bearer ${token} : , ...header }, success(res) { if (res.statusCode 200) { resolve(res.data) } else if (res.statusCode 401) { wx.removeStorageSync(token) wx.navigateTo({ url: /pages/login/index }) reject(new Error(未登录)) } else { reject(new Error(res.data.message || 请求失败)) } }, fail(err) { reject(err) } }) }) } module.exports request这里把网络请求包成 Promise页面里用 async/await 调用可读性比原本的 success 回调好很多。另一个容易被忽略的点是 wx.request 存在并发数量限制页面里一次性发起大量请求时后面的会被阻塞实际项目里我会把请求封装再包一层队列或优先依赖分页接口减少请求次数。需要注意开发阶段可以在开发者工具的本地设置里勾选不校验合法域名但提交审核前必须配置服务器域名白名单同时接口必须是 HTTPS。2.3 登录态与缓存设计小程序的登录流程是 wx.login 拿到 code把 code 发给后端后端调用微信接口换取 openid 和 session_key然后生成自己的登录态 token 返回给前端。前端把 token 存进 storage后续请求在 header 里带上。现在的微信对用户隐私收紧头像昵称建议使用官方头像昵称填写能力组件不要用老旧的 wx.getUserInfo 流程。缓存这块我建议单独封装一个 storage.js核心能力是支持过期时间。热搜词里有个微信小程序设置缓存时间实际指的就是这个场景首页商品数据不必用户每次打开都重新拉接口缓存三五分钟可以明显提升体验。// utils/storage.js const PREFIX mall_ function set(key, value, expires 0) { const data { value, expireAt: expires ? Date.now() expires * 1000 : 0 } wx.setStorageSync(PREFIX key, data) } function get(key) { const data wx.getStorageSync(PREFIX key) if (!data) return null if (data.expireAt Date.now() data.expireAt) { wx.removeStorageSync(PREFIX key) return null } return data.value } module.exports { set, get }比如首页数据就可以这样调用storage.set(home_cache, data, 300)读取时用 storage.get 判断是否命中。这样代码里不再出现散落的 wx.setStorageSync所有缓存策略集中管理排查问题时也只需要盯这一个文件。3. 核心模块实现与细节3.1 首页商品流与分类筛选首页一般由顶部搜索框、轮播图、金刚区导航、商品瀑布流四块组成。轮播图用 swiper 组件要注意设置图片的固定宽高比否则图片变形。商品列表推荐采用触底分页加载而不是一次性拉全部数据。分页实现依赖两个东西onReachBottom 生命周期监听触底page/pageSize 参数控制数据量。页面 data 里维护一个 page 变量每次触底让 page 加 1请求新数据后追加到商品数组末尾。还要加一个 isFinished 标志当返回的数据少于 pageSize 时表示没有更多了避免重复发请求。分类筛选页可以用左侧分类列表、右侧商品列表的布局。左侧滚动切换分类时右侧重新加载商品。注意在使用 scroll-view 组件时要给 scroll-view 设置明确的高度否则滚动无法触发。这是新手最容易忽略的点。商品图片记得开启懒加载模式image 组件加 lazy-load 属性服装商城图片多一条商品流动辄二三十张图不懒加载会出现明显卡顿。3.2 商品详情与SKU联动商品详情页展示的信息比较重轮播图、商品名、价格、销量、规格选择、图文详情。图文详情部分一般用富文本或长图列表渲染小程序的 rich-text 组件需要注意图片宽度的样式处理。SKU 选择是服装商城的核心难点。页面里用一个半屏弹层承载规格选择区域点击选择规格按钮弹出。弹层内维护两个选中状态当前选中的颜色、当前选中的尺码。每次点击规格项都要做库存校验没有库存的规格置灰处理。加入购物车或直接购买前必须做一次校验规格是否已经选完整。很多新手忽略这一步用户没选尺码就把商品加进购物车后续下单时才发现没法确定价格字段。我的做法是弹层里默认不选中任何规格只有颜色和尺码都选定后底部按钮才从请选择规格变成加入购物车或者立即购买。3.3 购物车与本地缓存策略购物车数据的存储建议采用本地缓存为主、服务端同步为辅的策略。本地存储保证用户关闭小程序再进入购物车还能恢复服务端同步保证多端登录时数据一致。练手项目通常只做本地存储就够了。购物车的数据结构可以这样定义一个数组每个元素包含商品ID、SKU ID、商品标题、主图、单价、数量、选中状态。选中状态单独存在字段里全选和单选都是修改这个字段结算时再过滤出选中项。价格计算要特别谨慎页面展示的价格由单价乘以数量得出但所有计算都用整数分完成JavaScript 浮点运算容易出现 0.1 0.2 不等于 0.3 的问题。我会在工具函数里封装一个 formatPrice 方法把分转成元的字符串比如 1290 转成 12.90。3.4 订单流程与支付对接订单确认页需要做的事情展示收货地址、列出商品清单、计算总金额、选择支付方式。地址可以做成一个独立页面用户从地址列表里选择当前订单使用的收货地址。创建订单时前端调用后端接口后端返回订单号和支付参数。支付参数包括 timeStamp、nonceStr、package、signType、paySign 五件套这些参数必须由后端生成前端拿到的是一份已经签好的支付凭证。前端拿到后调用 wx.requestPayment 拉起微信支付面板。支付成功回调里不要急着跳转页面先调用查询订单接口确认订单状态已经变成待发货再跳转订单列表。这样避免微信支付返回成功但后端回调延迟导致页面状态不一致的问题。订单状态建议用数字枚举表示0待付款、1待发货、2待收货、3已完成、4已取消前端展示时再转成对应的文字状态。4. 调试实战工具、真机与常见报错4.1 开发者工具面板使用技巧微信开发者工具自带的面板其实非常能打很多问题根本不用上真机就能定位。我把它们的用途整理成一个使用场景速查表。面板适合排查的问题使用要点ConsoleJS 报错、打印日志看报错堆栈定位到具体文件和行号Network请求失败、返回数据不符查看请求URL、请求方法、状态码、响应体Storage缓存数据异常直接增删改本地缓存验证缓存逻辑WXML样式不对、组件层级错乱实时修改样式观察页面变化Sources断点调试打断点逐步执行适合排查复杂逻辑排查接口问题我一定是先开 Network 面板看真实请求状态。小程序的 wx.request 报错有时候会显示 request:fail 这样比较模糊的信息此时要配合 Console 面板看完整错误。注意Network 面板里能清晰地看到请求是否携带了 Authorization 头token 注入是否正确这个信息对定位 401 问题非常有帮助。4.2 顶部导航栏与安全区适配热搜词里有微信小程序顶部导航栏高度这是一个非常典型的适配问题。使用自定义导航栏时如果直接用一个固定高度在 iPhone 刘海屏上内容会被状态栏遮挡。获取导航栏高度不能靠猜要利用官方提供的 APIconst info wx.getWindowInfo() const menuRect wx.getMenuButtonBoundingClientRect() const statusBarHeight info.statusBarHeight const navBarHeight (menuRect.top - statusBarHeight) * 2 menuRect.heightstatusBarHeight 是状态栏高度menuRect 是右上角胶囊按钮的位置信息计算出来的 navBarHeight 就是自定义导航栏需要的总高度。不同机型的数值会不同但按这套公式算出来基本都能适配。底部安全区的处理同样重要。iPhone 上使用自定义 tabBar 或底部操作栏时要给底部 padding 增加安全区高度可以读取 safeArea 的 bottom 值或者用环境变量 env(safe-area-inset-bottom)。忽略这个细节就会出现底部按钮被 Home 条挡住的问题。4.3 常见错误速查表把实操中遇过的典型问题整理成下面这张速查表基本覆盖了服装商城项目 80% 的调试场景。报错现象可能原因处理方式request:fail url not in domain list域名未配置白名单开发环境关闭域名校验上线前配置合法域名真机白屏页面 JS 报错、路径大小写错误看 Console 报错核对 app.json 页面路径下拉刷新无反应未开启 enablePullDownRefresh页面 json 配置开启该字段接口返回 401token 失效或未携带重新登录检查请求封装 header 注入缓存数据一直不更新key 固定且无过期时间给缓存 key 加版本号或使用过期机制图片加载失败图片域名不在白名单配置 downloadFile 合法域名开发期关闭校验商品列表重复加载onReachBottom 频繁触发加 isFinished 标志防止重复请求iOS 上 input 框高度异常样式适配问题用固定高度避免仅靠 padding 撑开真机上如果遇到工具里复现不了的样式差异优先怀疑三件事安全区适配、scroll-view 滚动链、图片加载策略。这三类问题在开发者工具里经常看不出来必须真机验证。4.4 真机预览与体验版发布开发者工具顶部工具栏点预览会生成一个二维码手机微信扫码后就能在真机上运行。这一步不是给手机装上小程序而是通过真机环境验证代码重点观察网络请求、缓存读写、交互流畅度。真机远程调试是很实用的功能手机扫码后开发者工具会同步显示手机上的 Console 日志和页面结构可以像调试模拟器一样查问题。遇到真机独有的问题比如网络请求失败、缓存读取异常远程调试能直接定位。如果项目要提交审核先在开发者工具上传代码再到微信公众平台提交体验版。体验版主要用于给团队内部或答辩评委预览提交审核的版本需要满足微信的规范要求比如必须有完整的功能流程、不能有测试数据残留、接口地址不能是本地 localhost。5. 文档与交付让项目拿得出手5.1 文档应该写什么很多同学的课程设计或练手项目代码写完了文档却随便凑几百字这其实相当可惜。文档是答辩和面试时的第一道门面它传达的信息量甚至超过代码本身。我建议一个项目至少包含五份文档。第一份是 README写清楚项目简介、功能清单、技术栈、目录结构、启动方式务必让人照着 README 就能把项目跑起来环境版本号、依赖安装命令、数据库初始化脚本都要写全。第二份是数据库设计文档列出每张表的字段说明配合 ER 图更佳。第三份是接口文档每个接口写明请求方法、请求参数、响应示例。第四份是测试记录列出测试过的功能点和已知问题。第五份是演示说明写清楚演示路径和注意事项比如用测试账号登录或支付使用模拟支付。写文档有个技巧先写接口文档再写 README。接口文档帮助你梳理前后端交互往往能反过来发现代码里的逻辑漏洞。5.2 源码交付注意事项源码交付时最容易扣分的是环境依赖和敏感信息清理。项目里不要出现 node_modules、编译产物、本地调试日志用 .gitignore 提前排除这些目录。小程序配置文件 appid 和个人 secret 绝对不能进仓库appid 可以保留但 secret 是后端持有的前端只需要配置 appid。接口地址方面我会区分开发环境和生产环境至少提供一个配置文件集中管理 BASE_URL不要写死在每个页面里。默认情况下跑起来应该指向一个可用的测试环境如果必须本地起后端README 要把启动步骤写得足够详细。版本管理用 git功能完成后打 tag。比如 v1.0.0 表示完整可演示版本这样答辩时能快速切回正常状态避免演示前手忙脚乱改代码。5.3 演示时的加分细节演示服装商城这类项目时有几个细节很加分提前准备好看的商品图和数据不要拿测试商品1这种占位数据凑数下单支付流程准备好一个可用的模拟支付环境或者提前备好演示账密如果现场网络不稳定提前准备好一份关键页面的截图作为兜底。这些小事看起来不起眼但直接影响项目的完成度和专业感。我个人在实际项目演示里体会最深的一点是先跑通主流程再谈细节优化。很多同学喜欢在边角功能上花大量时间结果主流程演示时翻车。正确的做法是核心链路每天跑一遍保证随时可以演示其他功能有余力再做。最后把这套服装商城做完后值得扩展的方向其实很多优惠券系统、商品搜索、订单状态机、消息订阅通知每个都是可以单独展开的好题目。先把手头这套源码和文档沉淀好后边的路会顺畅很多。