1. 为什么是SpringBoot加小程序这套智能瘦身系统的选型逻辑先交代背景。我手头这个项目是一套完整的“智能瘦身”微信小程序系统后端基于SpringBoot前端是原生微信小程序附带全套源码、部署文档和逐模块的代码讲解。整个项目从设计到落地再到整理成可交付的源码包前后折腾了不少时间。这篇文章不打算教你怎么从零写一个瘦身App而是把整套系统里最容易被忽略、又最影响交付质量的部分拆开聊聊选型、模块划分、小程序端适配、部署文档怎么写、代码讲解怎么讲。先回答一个很多人会问的问题为什么用SpringBoot而不是Node.js、Go或者Python后端原因很简单也很有代表性。做这种面向C端用户的小程序系统核心诉求是稳定、生态成熟、招人容易、排错方便。SpringBoot在这四点上的综合得分是最高的。瘦身类应用不是高并发直播系统也不是IM实时通讯它就是典型的CRUD加业务计算用户注册登录、记录饮食、上传体重、生成统计报表、管理食谱库。这种业务场景SpringBoot的约定优于配置能极大压缩起步成本而且Spring生态里现成的轮子——Spring Data JPA、MyBatis-Plus、Spring Security、Redis缓存——每一件都是被几十万项目验证过的不需要自己造。再来说为什么选微信小程序而不是H5或独立App。做瘦身产品获客成本是关键。微信小程序即点即用不需要下载安装用户从公众号文章、微信群、搜索入口都能直接进来。这个产品的目标用户是“想减肥但不想装App的人”小程序是他们心理门槛最低的使用方式。加上微信生态里的运动步数微信运动能直接对接省去了自己搞硬件或SDK的麻烦。这套系统最终实现的功能清单大致是这样的微信授权登录 手机号绑定后台维护用户档案身高、体重、年龄、性别每日饮食记录支持从内置食物库中选择并自动计算热量运动打卡支持手动录入也可同步微信运动步数体重曲线追踪按周/月维度生成趋势图智能目标设定根据基础代谢率BMR和活动系数动态调整每日热量摄入建议管理后台食物库管理、用户管理、内容公告管理技术上后端用SpringBoot 2.7.x持久层用MyBatis-Plus数据库MySQL 8.0缓存Redis鉴权用JWT接口风格走RESTful。小程序端原生开发没上uni-app或Taro就是考虑到当前项目的规模和维护成本原生是最稳的。这套选型组合里有几个点是经过对比后定下来的下面逐个说。1.1 为什么不用微服务架构很多教程一上来就Spring Cloud全家桶好像不拆几个服务就不好意思说自己是SpringBoot项目。实际做单体应用的时候我强烈建议不要微服务化。这个瘦身小程序系统初期预估日活不过几千单机部署绰绰有余。微服务带来的服务注册、配置中心、链路追踪、分布式事务这些复杂度对项目交付是纯粹的成本不是价值。再说了瘦身系统的业务边界没有那么清晰。用户、饮食、运动、统计这几个模块之间频繁互相调用硬拆成独立的微服务反而会把简单问题复杂化。我见过不少项目代码层面微服务拆得很漂亮部署的时候一跑光启动依赖就绕晕了。单体应用不是不先进而是要认清场景。我的做法是单体内部分层分包保持模块间通过Service接口交互为将来确实需要拆分时留好边界。代码层面是com.xxx.fit下面按业务分包user、diet、sport、report、admin。分工清晰目录结构一目了然。1.2 小程序原生和跨端框架的取舍原生微信小程序和uni-app、Taro这些跨端框架之间我选择了原生。客观讲跨端框架的强项是一次编写多端复用如果你的产品要同时出微信小程序、支付宝小程序、H5那跨端值得考虑。但这个瘦身系统第一阶段只锁微信生态原生开发的性能更好调试工具链最完整微信最新的API能力也能第一时间用上不会有框架适配的滞后。单说一个点微信小程序的wx.getMenuButtonBoundingClientRect()获取胶囊按钮位置以及自定义导航栏高度的适配原生写起来很直接。换成uni-app你要做条件编译要在不同平台跑不同逻辑反而是给自己挖坑。做小程序开发最忌讳的就是“为了框架而框架”。2. 后端核心模块拆分与数据模型设计瘦身业务的计算逻辑不在前端后端是整个系统的重头。智能瘦身这四个字核心不在“记录”而在“计算”和“建议”。如果只是让用户手动记饮食、记体重然后展示几条曲线那不叫智能叫表单工具。所以我在后端模块设计上把业务计算下沉到了服务层前端只负责展示和采集。2.1 数据模型设计用户、食物、记录三张核心表数据库表设计是整个系统的地基。我拆一下最重要的三张核心表的设计思路。第一张是user_profile用户档案表。除了微信侧的openid和unionid还需要存用户的生理参数身高、体重、出生日期、性别。为什么这些字段必须有因为后面算基础代谢率BMR要用。BMR的公式常用的是Mifflin-St Jeor方程男性是10×体重(kg) 6.25×身高(cm) - 5×年龄 5女性是10×体重(kg) 6.25×身高(cm) - 5×年龄 - 161两个式子只差末尾常数。这些字段全部得存原始值而不能只存一个计算好的BMR结果因为用户体重每周都在变BMR需要跟着动态重算。第二张是food食物库表。里面存食物名称、别名、每100克热量、蛋白质、脂肪、碳水、膳食纤维、单位重量。这张表是系统里数据量最大也最需要运营维护的表。食物库的数据来源可以是从公开的营养数据库中导入前期先准备500到800条常见食物数据覆盖日常饮食场景。注意一个细节一定要有food_code这样的唯一编码字段将来对接第三方营养数据API时做映射用不要直接用自增主键。第三张是diet_record饮食记录表。每条记录关联用户、关联食物、记录用餐类型早餐/午餐/晚餐/加餐、摄入量克、食物当时的热量快照。为什么要有“热量快照”字段因为食物库里的热量值会被运营修改如果某条食物从每100克200大卡改成了250大卡没有快照的用户记录就会整体失真历史统计就全错了。这是一个特别容易踩坑的设计数据建模时一定要想到“记录的是当时的事实而不是当前的值”。运动记录表exercise_record保存运动类型、时长、消耗热量估算值。体重记录表weight_record只存三个字段用户ID、体重值、记录日期但因为有频繁的“最近一条”“一个月趋势”查询我在user_id record_date上建了联合索引查询速度提升非常明显。2.2 服务层设计热量计算与目标动态调整的业务逻辑智能推荐是本系统的灵魂。设计它的核心业务逻辑时我参考了营养学里“能量平衡”模型简单说就是减重 摄入热量 消耗热量。服务层里有一个DietPlanService核心方法是generateDailySuggestion(userId)它做三件事根据用户最新的身高体重年龄性别用Mifflin-St Jeor公式算出BMR乘上活动系数久坐1.2、轻度活动1.375、中度活动1.55、高强度1.725得到每日总消耗能量TDEE根据用户设定的减重目标每周减0.5kg还是1kg在TDEE基础上减去500或1000大卡的热量缺口得到每日推荐摄入热量然后前端展示的“今日还可摄入xxx大卡”进度条并不是每天用固定值而是服务端根据当天已有记录实时算出来的。这样做的好处是用户早饭吃多了午饭后的剩余额度会自动变少动态反馈让“智能感”直接就出来了。这个服务里还需要处理一个边界即便用户目标很激进每天推荐摄入热量不得低于基础安全值——女性1200大卡男性1500大卡。低于这个值短期可能瘦得快但容易引发营养不良和反弹产品上不能让用户去冒这个险。2.3 微信登录与JWT鉴权小程序接口安全的关键细节微信小程序用户第一次打开需要走wx.login()拿到临时code后端用这个code去微信的code2Session接口换openid和session_key。整个流程如果只做“换到了就放行”会留下一个很大的安全隐患任何拿到你code的人都能登录。我在具体实现上做了三层防护第一层code2Session拿到的openid必须和当前用户的微信号一一对应伪造不了。第二层登录成功后签发JWT设置合理的过期时间我定为7天并把token存在小程序端的Storage里每次请求通过Authorization请求头带上。第三层结合Redis做token的“续签踢人”机制。用户修改密码或后台强制下线时删除Redis里对应的token键就能立刻让旧token失效这是纯JWT方案做不到的。// 小程序登录接口核心代码精简版 PostMapping(/wx/login) public Result login(RequestBody WxLoginRequest request) { // 1. 用code换取openid WxSession session wxService.code2Session(request.getCode()); // 2. 查数据库没注册就自动注册 User user userService.findOrCreate(session.getOpenid()); // 3. 生成JWT String token jwtUtil.generateToken(user.getId(), user.getOpenid()); // 4. 写入Redis设置过期时间 redisTemplate.opsForValue().set( login:token: user.getId(), token, 7, TimeUnit.DAYS ); return Result.ok(new LoginResponse(token, user)); }这段代码看着不长但每一行都有讲究。第一步的code2Session是微信要求的标准动作没有第二步的话每次登录都会新建一个用户数据全乱了第三步生成JWT是让前端后续请求能带上身份凭证第四步是对JWT的补充相当于在服务端保留了“回收凭证”的能力。3. 小程序端的适配细节导航栏高度、动态标题和支付降级方案小程序端我负责的部分主要集中在几个细节上这些细节不处理的话用户体验差而且很难定位问题。3.1 自定义导航栏高度适配不同手机上的胶囊按钮位置小程序默认自带导航栏但如果你想做得更有设计感就需要自定义导航栏这时候必须处理一个经典的适配问题胶囊按钮在不同机型上的高度位置不一样。iPhone X的刘海屏和普通iPhone的顶部安全区域不同安卓各家机型的底部导航高度也不同。如果写死一个像素值在部分手机上就会出现自定义标题栏把胶囊按钮顶出去或者互相重叠的翻车现象。我做适配用的是微信官方提供的能力wx.getMenuButtonBoundingClientRect()获取胶囊按钮的位置wx.getSystemInfoSync()获取系统信息用两者的差值来动态计算导航栏高度。// 小程序端导航栏高度适配 const getNavBarHeight () { const menuButton wx.getMenuButtonBoundingClientRect(); const systemInfo wx.getSystemInfoSync(); // 状态栏高度也就是刘海屏顶部安全区域 const statusBarHeight systemInfo.statusBarHeight; // 导航栏高度 (胶囊顶部 - 状态栏高度) * 2 胶囊高度 const navBarHeight (menuButton.top - statusBarHeight) * 2 menuButton.height; return { statusBarHeight, navBarHeight, menuButton }; };这个公式是社区里经过大量真机验证的结果。道理很简单胶囊按钮通常垂直居中于导航栏所以导航栏高度就是“胶囊到状态栏的距离”加上“胶囊自身高度”再加上“胶囊到导航栏底部的距离”。胶囊上下间距基本对称所以乘2。这样算出来的值你在真机上调试基本不会出偏差。3.2 动态设置页面标题wx.setNavigationBarTitle的正确用法瘦身小程序里有不少页面是“详情页”比如食物详情、运动教程详情。这种页面的标题如果全部在app.json里写死打开十个食物详情页标题全叫“食物详情”页面一多就分不清谁是谁了。这时候就要用到wx.setNavigationBarTitle接口动态设置。// 在食物详情页onLoad时动态设置标题 Page({ onLoad(options) { const foodName decodeURIComponent(options.foodName || 食物详情); wx.setNavigationBarTitle({ title: foodName }); } });这个接口很简单但有一个容易坑到的点options里的参数如果是中文需要先encodeURIComponent跳转后再decodeURIComponent解码。不然从列表页跳详情页时标题里的中文会变成一串%E7%B3%AF%E7%B1%B3%E5%9B%A2之类的乱码。还有一个细节如果小程序页面配置里设置了navigationStyle: custom即用了自定义导航栏wx.setNavigationBarTitle是不生效的。这时候你得自己维护一个标题状态然后在自定义导航栏的组件里动态渲染。这又是一个“自定义导航栏虽然好看但配套要处理的事情变多”的典型例子。3.3 微信支付V3对接与支付不可用时的优雅降级瘦身小程序里有一个合理的付费场景用户订阅更详细的饮食计划或解锁高级食材库。这就涉及微信支付V3的接入。微信支付V3和以前的V2版本最大的区别是API风格统一成了RESTful并且全面要求证书和敏感信息加密。接入时需要准备商户号、商户API私钥、APIv3密钥、商户证书序列号还有回调通知的验签逻辑。这一套流程我直接在服务端封装了一个WechatPayService把下单、回调验签、查询订单、退款都包进去。先在pom.xml引入官方SDK依赖dependency groupIdcom.github.wechatpay-apiv3/groupId artifactIdwechatpay-java/artifactId version0.2.11/version /dependency然后配置文件中放商户参数这里用配置类读取wechat: pay: merchant-id: your_merchant_id private-key-path: /path/to/apiclient_key.pem merchant-serial-number: your_cert_serial api-v3-key: your_api_v3_key notify-url: https://api.example.com/api/pay/notify下单核心流程小程序端调用wx.requestPayment前需要先请求后端拿到支付参数。后端要做的事是按照微信支付V3的规范构建下单请求用商户私钥对请求签名POST到微信支付接口拿到prepay_id后再生成小程序端需要的timeStamp、nonceStr、package、signType等参数。这里尤其要小心签名算法。V3的签名是先用待签名串拼接规则生成字符串再用商户私钥做SHA256withRSA签名。第一次对接时十有八九会卡在“签名错误”我的建议是先用官方给的Postman示例请求调试通了再把参数搬到代码里直接Java调通后再联调小程序端。不过在这个项目里有一段插曲——小程序因为平台违规支付功能暂时不可用。这里的“违规”不一定是你的代码或者业务有问题有时是平台审核层面的问题处理需要时间和申诉流程。作为开发你需要做的不是干等而是在产品层面做优雅降级。我的做法是支付入口在支付功能不可用期间自动隐藏或置灰同时把原本付费才能看的高级食谱检测为“新用户可免费体验3天”。等到支付申请解封后服务端只要改一个配置开关就能自动恢复付费功能。这样既不影响整个产品的核心体验也不会因为支付有毛病就把整个小程序给拖死了。4. 部署文档里那些“写了但没人细看”的关键点从环境搭建到Nginx转发部署文档是源码交付包中和源码同等重要的组成部分。一套源码如果部署文档写不清楚用户拿到手基本只能干瞪眼。但部署文档又恰恰是所有交付物里最容易糊弄的——因为写文档的人自己已经部署过几十遍了觉得“这还用写”结果第一次接手的人能在这个地方卡三天。我在交付这套瘦身系统的部署文档时刻意把下面这几个关键环节写得非常细。4.1 环境准备和版本坑位SpringBoot 3.x和JDK 17的兼容性雷区先列环境清单组件版本要求说明JDK1.8或11项目基于SpringBoot 2.7.x不要用JDK 17跑Maven3.6.3以上构建工具MySQL8.0数据库Redis6.x缓存与token管理Nginx1.18反向代理与HTTPS终结微信小程序开发者工具最新稳定版前端调试这里有一个必须写进文档的坑SpringBoot 2.7.x不兼容JDK 17及以上版本。SpringBoot 2.x官方支持到JDK 11如果你本机装的是JDK 17运行时会报UnsupportedClassVersionError或者一系列奇怪的反射异常。而SpringBoot 3.x虽然支持JDK 17但它要求javax迁移到jakarta命名空间依赖坐标也随之变化不是简单改个版本号就能升级的。所以如果下载的源码是SpringBoot 2.7.x请务必安装JDK 11。这是部署文档里我用醒目标注写下来的第一件事没有之一。很多人栽在这一步不是代码问题是环境版本不匹配。4.2 数据库初始化和一套数据初始化SQL脚本的关键性部署文档里数据库部分最核心的不是“创建一个数据库”而是初始化数据。瘦身系统如果没有食物库数据用户进来连热量都没法记整个核心功能是瘫痪的。所以我在docs/sql/目录下放了三份脚本schema.sql建表语句data_food.sql食物库初始数据800条data_admin.sql默认管理员账号用户名admin初始密码加密存储部署文档里明确写了执行顺序先schema.sql建表再data_food.sql灌数据最后data_admin.sql造管理员。有人说这三份脚本为什么不合成一份因为实际运维时你很可能需要只重置食物数据而保留用户数据分开是有意为之。同时application.yml里数据库连接配置需要用户自己改的地方我都用${DB_HOST}这种占位符标出来并在文档里给了完整的替换示例避免用户拿默认配置连半天连不上结果发现是数据库密码不对这种低级错误。4.3 Nginx配置HTTPS与反向代理微信小程序接口白名单的前提微信小程序正式版要求所有请求域名必须是HTTPS且已在后台配置合法域名。所以部署文档里Nginx配置就成了一道必答题。我的Nginx配置核心片段如下server { listen 443 ssl; server_name api.example.com; ssl_certificate /etc/nginx/cert/your_cert.pem; ssl_certificate_key /etc/nginx/cert/your_cert.key; ssl_protocols TLSv1.2 TLSv1.3; ssl_ciphers HIGH:!aNULL:!MD5; location / { proxy_pass http://127.0.0.1:8080; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; } }这里有个细节proxy_set_header X-Forwarded-Proto $scheme一定要写。这是为了让后端能拿到原始请求是HTTPS还是HTTP。否则在生成微信支付回调、拼接绝对地址等场景时后端拿到的协议会是http回调地址不对整个支付链路就断了。部署文档里我还专门写了一段“上线前检查清单”包括HTTPS证书有效期、小程序后台域名白名单request合法域名必须是https://api.example.com这种形状、服务器安全组是否放行443端口、Redis是否设置了访问密码生产环境绝对不允许无密码Redis裸奔。4.4 Docker Compose一键部署从手动配置到标准化交付为了让部署文档的实操门槛进一步降低我把整套系统组装成了Docker Compose编排。用户只要装了Docker和Docker Compose理论上一条命令就能把所有依赖拉起来。version: 3.8 services: mysql: image: mysql:8.0 container_name: fit-mysql environment: MYSQL_ROOT_PASSWORD: your_root_password MYSQL_DATABASE: fit_db ports: - 3306:3306 volumes: - ./sql:/docker-entrypoint-initdb.d command: --default-authentication-pluginmysql_native_password redis: image: redis:6.2 container_name: fit-redis ports: - 6379:6379 command: redis-server --requirepass your_redis_password app: build: . container_name: fit-app depends_on: - mysql - redis ports: - 8080:8080 environment: SPRING_PROFILES_ACTIVE: prod DB_HOST: mysql DB_PASSWORD: your_root_password REDIS_HOST: redis REDIS_PASSWORD: your_redis_password注意./sql:/docker-entrypoint-initdb.d这个挂载Docker官方镜像在第一次启动时会自动执行该目录下的.sql脚本完成数据库初始化。整套服务直接一条docker compose up -d就起来了比手动装MySQL、Redis再一个个启动省了至少一个下午的时间。当然Docker部署也有它的坑比如容器网络模式要选bridge默认容器之间通过服务名访问localhost在容器内部指向自己连127.0.0.1:3306是连不上的。这些内容我在部署文档里都单独做了小节并在旁边标注“如果是单机部署看不懂这段可以跳过不影响你跑起来”。5. 代码讲解不能只讲语法以登录接口和饮食记录为例拆解讲解思路源码交付包里“代码讲解”部分最容易做成流水账。很多人误以为代码讲解就是把代码贴一遍然后在旁边注释“这行是定义变量”“这行是调方法”。这种讲解对使用者一点帮助都没有。我整理这套系统的代码讲解文档时用的思路是**“从业务问题出发倒推代码设计”**每一段讲解都回答三个问题这段代码要解决什么业务问题为什么这样设计而不是那样设计如果要改动或扩展应该从哪入手5.1 登录接口的代码讲解不是讲语法是讲“登录为什么这样设计”以第一节提到的/wx/login接口为例我的讲解文档是这样拆解的首先说明业务背景微信小程序有一个特性它没有传统的账号密码输入框而是通过微信统一的授权体系来识别用户。小程序端调用wx.login()拿到的是一个短时效的code这个code只能使用一次有效期五分钟且必须配合小程序的AppID和AppSecret才能换取openid。然后解释为什么后端要拿code去换openid而不是直接用前端传过来的任何标识因为code是一次性的而openid是用户在当前小程序下的唯一标识。如果前端伪造一个用户ID直接传过来后端无法辨别身份真假整个系统的用户数据就不可信了。所以后端必须自己完成和微信服务器的通信拿到可信的openid。接着讲为什么用JWT而不是Session小程序不是浏览器没有Cookie机制。如果硬要模拟Session需要在每个请求头里手动传sessionId然后在服务端内存或Redis里存Session数据。JWT则是把用户标识和过期时间放在一个自包含的加密Token里客户端只管存服务端只管验不依赖服务端会话状态天然适合小程序这种“无状态接口”场景。最后讲扩展如果未来要支持多端登录互踢只需要在Redis里记录每个用户ID对应的Token列表每次请求时检查当前Token是不是“最新”的那个如果不是就拒绝访问。此时JWT的“自包含”特性和Redis的“集中检查”结合得非常默契。5.2 饮食记录热量计算的代码讲解把“业务规则”讲透另一个重点讲解的对象是饮食记录模块中“热量同步计算”的逻辑。用户每新增一条饮食记录系统的“今日剩余热量”就要同步更新。这个听起来简单的功能实现时有一个关键决策剩余热量是在前端算还是后端算我选择在后端算并把口径写死在服务里今日剩余热量 每日推荐摄入热量 - 当天已记录的所有饮食热量之和前端只在展示层做一件事拉取“今日总结”接口接口返回已摄入、推荐摄入、剩余热量三个值前端直接用。为什么不前端算因为同一天用户可能在小程序端记录也可能在管理后台代录或者以后接入了第三方同步。统计口径如果分散在前端一个端改了算法其他端不升级就会出现数据不一致这是做业务系统的大忌。统一在后端算所有端共享一套逻辑出问题也只有一个排查点。5.3 讲解文档的呈现方式流程图级别的调用链 标注版本差异除了文字拆解我还在代码讲解文档里对通知回调、支付退款这类长链路功能用了“ASCII示意”说明调用顺序而不是放截图或者复杂图件。比如wx.login的整体调用链我用一个简化版的时序描述小程序端 后端 微信服务器 |--- wx.login() --- | | | |--- code2Session(code) --- | | |-- openid session_key --- | | |--- 查/建用户 - 签JWT - 存Redis | |---------- token 用户信息 ---- | |这种“伪时序图”在Markdown文档里非常实用纯文本可搜索、可复制、不依赖任何渲染工具放在Git仓库里任何设备上打开都不变形。比贴一张PPT画的流程图更符合开发者的阅读习惯。与此同时讲解文档里每块代码都标注了“适用于SpringBoot 2.7.x”因为网上能搜到的很多代码是SpringBoot 2.2或2.3时代的接口签名已经变了。比如WebSecurityConfigurerAdapter在Spring Security新版本里被弃用很多人照着老教程写一启动就报错。标注版本差异是我在这份讲解文档里特别看重的一点能帮使用者省掉大量“对着教程却跑不起来”的痛苦。6. 实际项目交付中的血泪经验整理的源码包和文档如何真正帮到使用者这部分是我最想对准备做源码交付、技术文档输出的人说的。6.1 源码目录结构要“一眼看懂”而不是“按照Maven默认结构一扔”很多开源项目交付源码时直接整个工程压缩包往外发目录结构混乱到连原作者自己都得找半天才能定位到一个Controller。我做这套交付时刻意在根目录明确分层fit-miniapp/ ├── backend/ # SpringBoot后端工程 │ ├── src/main/java │ ├── src/main/resources │ └── pom.xml ├── miniprogram/ # 微信小程序前端工程 │ ├── pages/ │ ├── components/ │ ├── utils/ │ └── app.json ├── docs/ │ ├── deployment.md # 部署文档 │ ├── api.md # 接口文档 │ ├── code-guide.md # 代码讲解 │ └── sql/ # 数据库初始化脚本 ├── docker-compose.yml └── README.md后端内部按user / diet / sport / report分模块前端pages和components对应业务页面和复用组件docs里三类文档各司其职。使用者拿到包后第一眼就能知道该看什么、入口在哪这才是效率。6.2 不同交付对象需要不同的“讲解深度”源码交付的使用者分三种纯部署用户、二次开发用户、源码学习用户。这三类人的需求完全不同一份文档根本不可能通吃。纯部署用户他们只关心怎么把它跑起来。给他们看代码讲解是浪费时间。部署文档必须写得像一个“傻瓜式向导”——从装JDK到启动完小程序开发者工具每一步都编号、都说明预期输出最好再附一屏可能的报错及解法。二次开发用户他们更关注代码结构、接口约定、如何在这个基础上增加自己的业务模块。接口文档和数据库表结构说明对他们来说比什么都重要。源码学习用户他们要的是设计思路和演进过程。代码讲解文档就是为他们准备的要把“为什么这样写”讲透彻落到前因后果。我在这套交付包的README.md开头就写明了“如果你只是想跑起来请看部署文档如果你想二次开发请看接口文档如果你想深入学习请看代码讲解”。三句话让使用者自己定位省得他们翻半天文档觉得无从下手。6.3 常见部署故障排查表把你能想到的报错全部写进文档部署文档的最后一节我放了一个“常见故障排查表”收录了实际部署过程中遇到过的和预判可能发生的报错。这里列几个最高频的现象原因解法启动报Port 8080 was already in use端口被占用Linux执行netstat -tlnp | grep 8080找到进程杀掉接口返回Whitelabel Error Page后端未启动成功或路径错误检查启动日志确认Started字样微信开发者工具请求失败不校验合法域名没开开发环境在详情-本地设置勾选“不校验合法域名”登录返回errcode 40029code无效或已过期确认是否重复使用同一个code调用登录MySQL连接报Public Key Retrieval is not allowed连接串缺少allowPublicKeyRetrievaltrueJDBC URL加上该参数这张表是文档里被翻得最多的一页远超过原理讲解部分。为什么因为用户遇到问题的第一时间最需要的就是“对症下药”而不是从原理学起。6.4 个人体会文档质量决定源码交付的评分写到最后说点实在的。技术圈子里有不少人觉得“源码交付包 源码压缩包 一个README”这种想法害人不浅。我做过甲方也做过乙方站在使用者的角度一次源码交付体验好不好60%取决于文档质量40%才取决于代码本身的健壮性。代码再漂亮部署文档写得含糊使用者卡在一个环境变量上报错三天他对整个项目的评价就会直线下降反过来就算代码有瑕疵如果文档里明确写清了“已知问题和临时规避方案”使用者的体验依然可以是正面的。我在整理这套智能瘦身小程序系统的文档时最大的心得是写文档的时候要假设读者是一个“比你更没耐心、更不熟悉项目、更可能在半夜两点部署”的人。只有这样你才会愿意把“别忘了改Redis密码”“证书路径别写绝对路径”“Docker容器里连数据库别用localhost”这些细节事无巨细地写进去。回看这套系统本身SpringBoot加微信小程序的组合足够应对瘦身类业务场景的绝大多数需求。虽然项目规模不大但涉及用户鉴权、数据建模、业务计算、支付对接、部署上线、文档交付这些完整链路麻雀虽小五脏俱全。如果你正在做类似的小程序系统希望这篇分享中关于数据模型设计、导航栏适配、部署文档编写和代码讲解组织的内容能帮你少走几步弯路。 SpringBoot+微信小程序实战：智能瘦身系统设计与部署全解析
1. 为什么是SpringBoot加小程序这套智能瘦身系统的选型逻辑先交代背景。我手头这个项目是一套完整的“智能瘦身”微信小程序系统后端基于SpringBoot前端是原生微信小程序附带全套源码、部署文档和逐模块的代码讲解。整个项目从设计到落地再到整理成可交付的源码包前后折腾了不少时间。这篇文章不打算教你怎么从零写一个瘦身App而是把整套系统里最容易被忽略、又最影响交付质量的部分拆开聊聊选型、模块划分、小程序端适配、部署文档怎么写、代码讲解怎么讲。先回答一个很多人会问的问题为什么用SpringBoot而不是Node.js、Go或者Python后端原因很简单也很有代表性。做这种面向C端用户的小程序系统核心诉求是稳定、生态成熟、招人容易、排错方便。SpringBoot在这四点上的综合得分是最高的。瘦身类应用不是高并发直播系统也不是IM实时通讯它就是典型的CRUD加业务计算用户注册登录、记录饮食、上传体重、生成统计报表、管理食谱库。这种业务场景SpringBoot的约定优于配置能极大压缩起步成本而且Spring生态里现成的轮子——Spring Data JPA、MyBatis-Plus、Spring Security、Redis缓存——每一件都是被几十万项目验证过的不需要自己造。再来说为什么选微信小程序而不是H5或独立App。做瘦身产品获客成本是关键。微信小程序即点即用不需要下载安装用户从公众号文章、微信群、搜索入口都能直接进来。这个产品的目标用户是“想减肥但不想装App的人”小程序是他们心理门槛最低的使用方式。加上微信生态里的运动步数微信运动能直接对接省去了自己搞硬件或SDK的麻烦。这套系统最终实现的功能清单大致是这样的微信授权登录 手机号绑定后台维护用户档案身高、体重、年龄、性别每日饮食记录支持从内置食物库中选择并自动计算热量运动打卡支持手动录入也可同步微信运动步数体重曲线追踪按周/月维度生成趋势图智能目标设定根据基础代谢率BMR和活动系数动态调整每日热量摄入建议管理后台食物库管理、用户管理、内容公告管理技术上后端用SpringBoot 2.7.x持久层用MyBatis-Plus数据库MySQL 8.0缓存Redis鉴权用JWT接口风格走RESTful。小程序端原生开发没上uni-app或Taro就是考虑到当前项目的规模和维护成本原生是最稳的。这套选型组合里有几个点是经过对比后定下来的下面逐个说。1.1 为什么不用微服务架构很多教程一上来就Spring Cloud全家桶好像不拆几个服务就不好意思说自己是SpringBoot项目。实际做单体应用的时候我强烈建议不要微服务化。这个瘦身小程序系统初期预估日活不过几千单机部署绰绰有余。微服务带来的服务注册、配置中心、链路追踪、分布式事务这些复杂度对项目交付是纯粹的成本不是价值。再说了瘦身系统的业务边界没有那么清晰。用户、饮食、运动、统计这几个模块之间频繁互相调用硬拆成独立的微服务反而会把简单问题复杂化。我见过不少项目代码层面微服务拆得很漂亮部署的时候一跑光启动依赖就绕晕了。单体应用不是不先进而是要认清场景。我的做法是单体内部分层分包保持模块间通过Service接口交互为将来确实需要拆分时留好边界。代码层面是com.xxx.fit下面按业务分包user、diet、sport、report、admin。分工清晰目录结构一目了然。1.2 小程序原生和跨端框架的取舍原生微信小程序和uni-app、Taro这些跨端框架之间我选择了原生。客观讲跨端框架的强项是一次编写多端复用如果你的产品要同时出微信小程序、支付宝小程序、H5那跨端值得考虑。但这个瘦身系统第一阶段只锁微信生态原生开发的性能更好调试工具链最完整微信最新的API能力也能第一时间用上不会有框架适配的滞后。单说一个点微信小程序的wx.getMenuButtonBoundingClientRect()获取胶囊按钮位置以及自定义导航栏高度的适配原生写起来很直接。换成uni-app你要做条件编译要在不同平台跑不同逻辑反而是给自己挖坑。做小程序开发最忌讳的就是“为了框架而框架”。2. 后端核心模块拆分与数据模型设计瘦身业务的计算逻辑不在前端后端是整个系统的重头。智能瘦身这四个字核心不在“记录”而在“计算”和“建议”。如果只是让用户手动记饮食、记体重然后展示几条曲线那不叫智能叫表单工具。所以我在后端模块设计上把业务计算下沉到了服务层前端只负责展示和采集。2.1 数据模型设计用户、食物、记录三张核心表数据库表设计是整个系统的地基。我拆一下最重要的三张核心表的设计思路。第一张是user_profile用户档案表。除了微信侧的openid和unionid还需要存用户的生理参数身高、体重、出生日期、性别。为什么这些字段必须有因为后面算基础代谢率BMR要用。BMR的公式常用的是Mifflin-St Jeor方程男性是10×体重(kg) 6.25×身高(cm) - 5×年龄 5女性是10×体重(kg) 6.25×身高(cm) - 5×年龄 - 161两个式子只差末尾常数。这些字段全部得存原始值而不能只存一个计算好的BMR结果因为用户体重每周都在变BMR需要跟着动态重算。第二张是food食物库表。里面存食物名称、别名、每100克热量、蛋白质、脂肪、碳水、膳食纤维、单位重量。这张表是系统里数据量最大也最需要运营维护的表。食物库的数据来源可以是从公开的营养数据库中导入前期先准备500到800条常见食物数据覆盖日常饮食场景。注意一个细节一定要有food_code这样的唯一编码字段将来对接第三方营养数据API时做映射用不要直接用自增主键。第三张是diet_record饮食记录表。每条记录关联用户、关联食物、记录用餐类型早餐/午餐/晚餐/加餐、摄入量克、食物当时的热量快照。为什么要有“热量快照”字段因为食物库里的热量值会被运营修改如果某条食物从每100克200大卡改成了250大卡没有快照的用户记录就会整体失真历史统计就全错了。这是一个特别容易踩坑的设计数据建模时一定要想到“记录的是当时的事实而不是当前的值”。运动记录表exercise_record保存运动类型、时长、消耗热量估算值。体重记录表weight_record只存三个字段用户ID、体重值、记录日期但因为有频繁的“最近一条”“一个月趋势”查询我在user_id record_date上建了联合索引查询速度提升非常明显。2.2 服务层设计热量计算与目标动态调整的业务逻辑智能推荐是本系统的灵魂。设计它的核心业务逻辑时我参考了营养学里“能量平衡”模型简单说就是减重 摄入热量 消耗热量。服务层里有一个DietPlanService核心方法是generateDailySuggestion(userId)它做三件事根据用户最新的身高体重年龄性别用Mifflin-St Jeor公式算出BMR乘上活动系数久坐1.2、轻度活动1.375、中度活动1.55、高强度1.725得到每日总消耗能量TDEE根据用户设定的减重目标每周减0.5kg还是1kg在TDEE基础上减去500或1000大卡的热量缺口得到每日推荐摄入热量然后前端展示的“今日还可摄入xxx大卡”进度条并不是每天用固定值而是服务端根据当天已有记录实时算出来的。这样做的好处是用户早饭吃多了午饭后的剩余额度会自动变少动态反馈让“智能感”直接就出来了。这个服务里还需要处理一个边界即便用户目标很激进每天推荐摄入热量不得低于基础安全值——女性1200大卡男性1500大卡。低于这个值短期可能瘦得快但容易引发营养不良和反弹产品上不能让用户去冒这个险。2.3 微信登录与JWT鉴权小程序接口安全的关键细节微信小程序用户第一次打开需要走wx.login()拿到临时code后端用这个code去微信的code2Session接口换openid和session_key。整个流程如果只做“换到了就放行”会留下一个很大的安全隐患任何拿到你code的人都能登录。我在具体实现上做了三层防护第一层code2Session拿到的openid必须和当前用户的微信号一一对应伪造不了。第二层登录成功后签发JWT设置合理的过期时间我定为7天并把token存在小程序端的Storage里每次请求通过Authorization请求头带上。第三层结合Redis做token的“续签踢人”机制。用户修改密码或后台强制下线时删除Redis里对应的token键就能立刻让旧token失效这是纯JWT方案做不到的。// 小程序登录接口核心代码精简版 PostMapping(/wx/login) public Result login(RequestBody WxLoginRequest request) { // 1. 用code换取openid WxSession session wxService.code2Session(request.getCode()); // 2. 查数据库没注册就自动注册 User user userService.findOrCreate(session.getOpenid()); // 3. 生成JWT String token jwtUtil.generateToken(user.getId(), user.getOpenid()); // 4. 写入Redis设置过期时间 redisTemplate.opsForValue().set( login:token: user.getId(), token, 7, TimeUnit.DAYS ); return Result.ok(new LoginResponse(token, user)); }这段代码看着不长但每一行都有讲究。第一步的code2Session是微信要求的标准动作没有第二步的话每次登录都会新建一个用户数据全乱了第三步生成JWT是让前端后续请求能带上身份凭证第四步是对JWT的补充相当于在服务端保留了“回收凭证”的能力。3. 小程序端的适配细节导航栏高度、动态标题和支付降级方案小程序端我负责的部分主要集中在几个细节上这些细节不处理的话用户体验差而且很难定位问题。3.1 自定义导航栏高度适配不同手机上的胶囊按钮位置小程序默认自带导航栏但如果你想做得更有设计感就需要自定义导航栏这时候必须处理一个经典的适配问题胶囊按钮在不同机型上的高度位置不一样。iPhone X的刘海屏和普通iPhone的顶部安全区域不同安卓各家机型的底部导航高度也不同。如果写死一个像素值在部分手机上就会出现自定义标题栏把胶囊按钮顶出去或者互相重叠的翻车现象。我做适配用的是微信官方提供的能力wx.getMenuButtonBoundingClientRect()获取胶囊按钮的位置wx.getSystemInfoSync()获取系统信息用两者的差值来动态计算导航栏高度。// 小程序端导航栏高度适配 const getNavBarHeight () { const menuButton wx.getMenuButtonBoundingClientRect(); const systemInfo wx.getSystemInfoSync(); // 状态栏高度也就是刘海屏顶部安全区域 const statusBarHeight systemInfo.statusBarHeight; // 导航栏高度 (胶囊顶部 - 状态栏高度) * 2 胶囊高度 const navBarHeight (menuButton.top - statusBarHeight) * 2 menuButton.height; return { statusBarHeight, navBarHeight, menuButton }; };这个公式是社区里经过大量真机验证的结果。道理很简单胶囊按钮通常垂直居中于导航栏所以导航栏高度就是“胶囊到状态栏的距离”加上“胶囊自身高度”再加上“胶囊到导航栏底部的距离”。胶囊上下间距基本对称所以乘2。这样算出来的值你在真机上调试基本不会出偏差。3.2 动态设置页面标题wx.setNavigationBarTitle的正确用法瘦身小程序里有不少页面是“详情页”比如食物详情、运动教程详情。这种页面的标题如果全部在app.json里写死打开十个食物详情页标题全叫“食物详情”页面一多就分不清谁是谁了。这时候就要用到wx.setNavigationBarTitle接口动态设置。// 在食物详情页onLoad时动态设置标题 Page({ onLoad(options) { const foodName decodeURIComponent(options.foodName || 食物详情); wx.setNavigationBarTitle({ title: foodName }); } });这个接口很简单但有一个容易坑到的点options里的参数如果是中文需要先encodeURIComponent跳转后再decodeURIComponent解码。不然从列表页跳详情页时标题里的中文会变成一串%E7%B3%AF%E7%B1%B3%E5%9B%A2之类的乱码。还有一个细节如果小程序页面配置里设置了navigationStyle: custom即用了自定义导航栏wx.setNavigationBarTitle是不生效的。这时候你得自己维护一个标题状态然后在自定义导航栏的组件里动态渲染。这又是一个“自定义导航栏虽然好看但配套要处理的事情变多”的典型例子。3.3 微信支付V3对接与支付不可用时的优雅降级瘦身小程序里有一个合理的付费场景用户订阅更详细的饮食计划或解锁高级食材库。这就涉及微信支付V3的接入。微信支付V3和以前的V2版本最大的区别是API风格统一成了RESTful并且全面要求证书和敏感信息加密。接入时需要准备商户号、商户API私钥、APIv3密钥、商户证书序列号还有回调通知的验签逻辑。这一套流程我直接在服务端封装了一个WechatPayService把下单、回调验签、查询订单、退款都包进去。先在pom.xml引入官方SDK依赖dependency groupIdcom.github.wechatpay-apiv3/groupId artifactIdwechatpay-java/artifactId version0.2.11/version /dependency然后配置文件中放商户参数这里用配置类读取wechat: pay: merchant-id: your_merchant_id private-key-path: /path/to/apiclient_key.pem merchant-serial-number: your_cert_serial api-v3-key: your_api_v3_key notify-url: https://api.example.com/api/pay/notify下单核心流程小程序端调用wx.requestPayment前需要先请求后端拿到支付参数。后端要做的事是按照微信支付V3的规范构建下单请求用商户私钥对请求签名POST到微信支付接口拿到prepay_id后再生成小程序端需要的timeStamp、nonceStr、package、signType等参数。这里尤其要小心签名算法。V3的签名是先用待签名串拼接规则生成字符串再用商户私钥做SHA256withRSA签名。第一次对接时十有八九会卡在“签名错误”我的建议是先用官方给的Postman示例请求调试通了再把参数搬到代码里直接Java调通后再联调小程序端。不过在这个项目里有一段插曲——小程序因为平台违规支付功能暂时不可用。这里的“违规”不一定是你的代码或者业务有问题有时是平台审核层面的问题处理需要时间和申诉流程。作为开发你需要做的不是干等而是在产品层面做优雅降级。我的做法是支付入口在支付功能不可用期间自动隐藏或置灰同时把原本付费才能看的高级食谱检测为“新用户可免费体验3天”。等到支付申请解封后服务端只要改一个配置开关就能自动恢复付费功能。这样既不影响整个产品的核心体验也不会因为支付有毛病就把整个小程序给拖死了。4. 部署文档里那些“写了但没人细看”的关键点从环境搭建到Nginx转发部署文档是源码交付包中和源码同等重要的组成部分。一套源码如果部署文档写不清楚用户拿到手基本只能干瞪眼。但部署文档又恰恰是所有交付物里最容易糊弄的——因为写文档的人自己已经部署过几十遍了觉得“这还用写”结果第一次接手的人能在这个地方卡三天。我在交付这套瘦身系统的部署文档时刻意把下面这几个关键环节写得非常细。4.1 环境准备和版本坑位SpringBoot 3.x和JDK 17的兼容性雷区先列环境清单组件版本要求说明JDK1.8或11项目基于SpringBoot 2.7.x不要用JDK 17跑Maven3.6.3以上构建工具MySQL8.0数据库Redis6.x缓存与token管理Nginx1.18反向代理与HTTPS终结微信小程序开发者工具最新稳定版前端调试这里有一个必须写进文档的坑SpringBoot 2.7.x不兼容JDK 17及以上版本。SpringBoot 2.x官方支持到JDK 11如果你本机装的是JDK 17运行时会报UnsupportedClassVersionError或者一系列奇怪的反射异常。而SpringBoot 3.x虽然支持JDK 17但它要求javax迁移到jakarta命名空间依赖坐标也随之变化不是简单改个版本号就能升级的。所以如果下载的源码是SpringBoot 2.7.x请务必安装JDK 11。这是部署文档里我用醒目标注写下来的第一件事没有之一。很多人栽在这一步不是代码问题是环境版本不匹配。4.2 数据库初始化和一套数据初始化SQL脚本的关键性部署文档里数据库部分最核心的不是“创建一个数据库”而是初始化数据。瘦身系统如果没有食物库数据用户进来连热量都没法记整个核心功能是瘫痪的。所以我在docs/sql/目录下放了三份脚本schema.sql建表语句data_food.sql食物库初始数据800条data_admin.sql默认管理员账号用户名admin初始密码加密存储部署文档里明确写了执行顺序先schema.sql建表再data_food.sql灌数据最后data_admin.sql造管理员。有人说这三份脚本为什么不合成一份因为实际运维时你很可能需要只重置食物数据而保留用户数据分开是有意为之。同时application.yml里数据库连接配置需要用户自己改的地方我都用${DB_HOST}这种占位符标出来并在文档里给了完整的替换示例避免用户拿默认配置连半天连不上结果发现是数据库密码不对这种低级错误。4.3 Nginx配置HTTPS与反向代理微信小程序接口白名单的前提微信小程序正式版要求所有请求域名必须是HTTPS且已在后台配置合法域名。所以部署文档里Nginx配置就成了一道必答题。我的Nginx配置核心片段如下server { listen 443 ssl; server_name api.example.com; ssl_certificate /etc/nginx/cert/your_cert.pem; ssl_certificate_key /etc/nginx/cert/your_cert.key; ssl_protocols TLSv1.2 TLSv1.3; ssl_ciphers HIGH:!aNULL:!MD5; location / { proxy_pass http://127.0.0.1:8080; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; } }这里有个细节proxy_set_header X-Forwarded-Proto $scheme一定要写。这是为了让后端能拿到原始请求是HTTPS还是HTTP。否则在生成微信支付回调、拼接绝对地址等场景时后端拿到的协议会是http回调地址不对整个支付链路就断了。部署文档里我还专门写了一段“上线前检查清单”包括HTTPS证书有效期、小程序后台域名白名单request合法域名必须是https://api.example.com这种形状、服务器安全组是否放行443端口、Redis是否设置了访问密码生产环境绝对不允许无密码Redis裸奔。4.4 Docker Compose一键部署从手动配置到标准化交付为了让部署文档的实操门槛进一步降低我把整套系统组装成了Docker Compose编排。用户只要装了Docker和Docker Compose理论上一条命令就能把所有依赖拉起来。version: 3.8 services: mysql: image: mysql:8.0 container_name: fit-mysql environment: MYSQL_ROOT_PASSWORD: your_root_password MYSQL_DATABASE: fit_db ports: - 3306:3306 volumes: - ./sql:/docker-entrypoint-initdb.d command: --default-authentication-pluginmysql_native_password redis: image: redis:6.2 container_name: fit-redis ports: - 6379:6379 command: redis-server --requirepass your_redis_password app: build: . container_name: fit-app depends_on: - mysql - redis ports: - 8080:8080 environment: SPRING_PROFILES_ACTIVE: prod DB_HOST: mysql DB_PASSWORD: your_root_password REDIS_HOST: redis REDIS_PASSWORD: your_redis_password注意./sql:/docker-entrypoint-initdb.d这个挂载Docker官方镜像在第一次启动时会自动执行该目录下的.sql脚本完成数据库初始化。整套服务直接一条docker compose up -d就起来了比手动装MySQL、Redis再一个个启动省了至少一个下午的时间。当然Docker部署也有它的坑比如容器网络模式要选bridge默认容器之间通过服务名访问localhost在容器内部指向自己连127.0.0.1:3306是连不上的。这些内容我在部署文档里都单独做了小节并在旁边标注“如果是单机部署看不懂这段可以跳过不影响你跑起来”。5. 代码讲解不能只讲语法以登录接口和饮食记录为例拆解讲解思路源码交付包里“代码讲解”部分最容易做成流水账。很多人误以为代码讲解就是把代码贴一遍然后在旁边注释“这行是定义变量”“这行是调方法”。这种讲解对使用者一点帮助都没有。我整理这套系统的代码讲解文档时用的思路是**“从业务问题出发倒推代码设计”**每一段讲解都回答三个问题这段代码要解决什么业务问题为什么这样设计而不是那样设计如果要改动或扩展应该从哪入手5.1 登录接口的代码讲解不是讲语法是讲“登录为什么这样设计”以第一节提到的/wx/login接口为例我的讲解文档是这样拆解的首先说明业务背景微信小程序有一个特性它没有传统的账号密码输入框而是通过微信统一的授权体系来识别用户。小程序端调用wx.login()拿到的是一个短时效的code这个code只能使用一次有效期五分钟且必须配合小程序的AppID和AppSecret才能换取openid。然后解释为什么后端要拿code去换openid而不是直接用前端传过来的任何标识因为code是一次性的而openid是用户在当前小程序下的唯一标识。如果前端伪造一个用户ID直接传过来后端无法辨别身份真假整个系统的用户数据就不可信了。所以后端必须自己完成和微信服务器的通信拿到可信的openid。接着讲为什么用JWT而不是Session小程序不是浏览器没有Cookie机制。如果硬要模拟Session需要在每个请求头里手动传sessionId然后在服务端内存或Redis里存Session数据。JWT则是把用户标识和过期时间放在一个自包含的加密Token里客户端只管存服务端只管验不依赖服务端会话状态天然适合小程序这种“无状态接口”场景。最后讲扩展如果未来要支持多端登录互踢只需要在Redis里记录每个用户ID对应的Token列表每次请求时检查当前Token是不是“最新”的那个如果不是就拒绝访问。此时JWT的“自包含”特性和Redis的“集中检查”结合得非常默契。5.2 饮食记录热量计算的代码讲解把“业务规则”讲透另一个重点讲解的对象是饮食记录模块中“热量同步计算”的逻辑。用户每新增一条饮食记录系统的“今日剩余热量”就要同步更新。这个听起来简单的功能实现时有一个关键决策剩余热量是在前端算还是后端算我选择在后端算并把口径写死在服务里今日剩余热量 每日推荐摄入热量 - 当天已记录的所有饮食热量之和前端只在展示层做一件事拉取“今日总结”接口接口返回已摄入、推荐摄入、剩余热量三个值前端直接用。为什么不前端算因为同一天用户可能在小程序端记录也可能在管理后台代录或者以后接入了第三方同步。统计口径如果分散在前端一个端改了算法其他端不升级就会出现数据不一致这是做业务系统的大忌。统一在后端算所有端共享一套逻辑出问题也只有一个排查点。5.3 讲解文档的呈现方式流程图级别的调用链 标注版本差异除了文字拆解我还在代码讲解文档里对通知回调、支付退款这类长链路功能用了“ASCII示意”说明调用顺序而不是放截图或者复杂图件。比如wx.login的整体调用链我用一个简化版的时序描述小程序端 后端 微信服务器 |--- wx.login() --- | | | |--- code2Session(code) --- | | |-- openid session_key --- | | |--- 查/建用户 - 签JWT - 存Redis | |---------- token 用户信息 ---- | |这种“伪时序图”在Markdown文档里非常实用纯文本可搜索、可复制、不依赖任何渲染工具放在Git仓库里任何设备上打开都不变形。比贴一张PPT画的流程图更符合开发者的阅读习惯。与此同时讲解文档里每块代码都标注了“适用于SpringBoot 2.7.x”因为网上能搜到的很多代码是SpringBoot 2.2或2.3时代的接口签名已经变了。比如WebSecurityConfigurerAdapter在Spring Security新版本里被弃用很多人照着老教程写一启动就报错。标注版本差异是我在这份讲解文档里特别看重的一点能帮使用者省掉大量“对着教程却跑不起来”的痛苦。6. 实际项目交付中的血泪经验整理的源码包和文档如何真正帮到使用者这部分是我最想对准备做源码交付、技术文档输出的人说的。6.1 源码目录结构要“一眼看懂”而不是“按照Maven默认结构一扔”很多开源项目交付源码时直接整个工程压缩包往外发目录结构混乱到连原作者自己都得找半天才能定位到一个Controller。我做这套交付时刻意在根目录明确分层fit-miniapp/ ├── backend/ # SpringBoot后端工程 │ ├── src/main/java │ ├── src/main/resources │ └── pom.xml ├── miniprogram/ # 微信小程序前端工程 │ ├── pages/ │ ├── components/ │ ├── utils/ │ └── app.json ├── docs/ │ ├── deployment.md # 部署文档 │ ├── api.md # 接口文档 │ ├── code-guide.md # 代码讲解 │ └── sql/ # 数据库初始化脚本 ├── docker-compose.yml └── README.md后端内部按user / diet / sport / report分模块前端pages和components对应业务页面和复用组件docs里三类文档各司其职。使用者拿到包后第一眼就能知道该看什么、入口在哪这才是效率。6.2 不同交付对象需要不同的“讲解深度”源码交付的使用者分三种纯部署用户、二次开发用户、源码学习用户。这三类人的需求完全不同一份文档根本不可能通吃。纯部署用户他们只关心怎么把它跑起来。给他们看代码讲解是浪费时间。部署文档必须写得像一个“傻瓜式向导”——从装JDK到启动完小程序开发者工具每一步都编号、都说明预期输出最好再附一屏可能的报错及解法。二次开发用户他们更关注代码结构、接口约定、如何在这个基础上增加自己的业务模块。接口文档和数据库表结构说明对他们来说比什么都重要。源码学习用户他们要的是设计思路和演进过程。代码讲解文档就是为他们准备的要把“为什么这样写”讲透彻落到前因后果。我在这套交付包的README.md开头就写明了“如果你只是想跑起来请看部署文档如果你想二次开发请看接口文档如果你想深入学习请看代码讲解”。三句话让使用者自己定位省得他们翻半天文档觉得无从下手。6.3 常见部署故障排查表把你能想到的报错全部写进文档部署文档的最后一节我放了一个“常见故障排查表”收录了实际部署过程中遇到过的和预判可能发生的报错。这里列几个最高频的现象原因解法启动报Port 8080 was already in use端口被占用Linux执行netstat -tlnp | grep 8080找到进程杀掉接口返回Whitelabel Error Page后端未启动成功或路径错误检查启动日志确认Started字样微信开发者工具请求失败不校验合法域名没开开发环境在详情-本地设置勾选“不校验合法域名”登录返回errcode 40029code无效或已过期确认是否重复使用同一个code调用登录MySQL连接报Public Key Retrieval is not allowed连接串缺少allowPublicKeyRetrievaltrueJDBC URL加上该参数这张表是文档里被翻得最多的一页远超过原理讲解部分。为什么因为用户遇到问题的第一时间最需要的就是“对症下药”而不是从原理学起。6.4 个人体会文档质量决定源码交付的评分写到最后说点实在的。技术圈子里有不少人觉得“源码交付包 源码压缩包 一个README”这种想法害人不浅。我做过甲方也做过乙方站在使用者的角度一次源码交付体验好不好60%取决于文档质量40%才取决于代码本身的健壮性。代码再漂亮部署文档写得含糊使用者卡在一个环境变量上报错三天他对整个项目的评价就会直线下降反过来就算代码有瑕疵如果文档里明确写清了“已知问题和临时规避方案”使用者的体验依然可以是正面的。我在整理这套智能瘦身小程序系统的文档时最大的心得是写文档的时候要假设读者是一个“比你更没耐心、更不熟悉项目、更可能在半夜两点部署”的人。只有这样你才会愿意把“别忘了改Redis密码”“证书路径别写绝对路径”“Docker容器里连数据库别用localhost”这些细节事无巨细地写进去。回看这套系统本身SpringBoot加微信小程序的组合足够应对瘦身类业务场景的绝大多数需求。虽然项目规模不大但涉及用户鉴权、数据建模、业务计算、支付对接、部署上线、文档交付这些完整链路麻雀虽小五脏俱全。如果你正在做类似的小程序系统希望这篇分享中关于数据模型设计、导航栏适配、部署文档编写和代码讲解组织的内容能帮你少走几步弯路。