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)，它做三件事：

1. 根据用户最新的身高体重年龄性别，用Mifflin-St Jeor公式算出BMR
2. 乘上活动系数（久坐1.2、轻度活动1.375、中度活动1.55、高强度1.725），得到每日总消耗能量（TDEE）
3. 根据用户设定的减重目标（每周减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> <groupId>com.github.wechatpay-apiv3</groupId> <artifactId>wechatpay-java</artifactId> <version>0.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的兼容性雷区

先列环境清单：

这里有一个必须写进文档的坑：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-plugin=mysql_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. 代码讲解不能只讲语法：以登录接口和饮食记录为例拆解讲解思路

源码交付包里，“代码讲解”部分最容易做成流水账。很多人误以为代码讲解就是把代码贴一遍，然后在旁边注释“这行是定义变量”“这行是调方法”。这种讲解对使用者一点帮助都没有。我整理这套系统的代码讲解文档时，用的思路是**“从业务问题出发，倒推代码设计”**，每一段讲解都回答三个问题：

1. 这段代码要解决什么业务问题？
2. 为什么这样设计而不是那样设计？
3. 如果要改动或扩展，应该从哪入手？

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 常见部署故障排查表：把你能想到的报错全部写进文档

部署文档的最后一节，我放了一个“常见故障排查表”，收录了实际部署过程中遇到过的和预判可能发生的报错。这里列几个最高频的：

这张表是文档里被翻得最多的一页，远超过原理讲解部分。为什么？因为用户遇到问题的第一时间最需要的就是“对症下药”，而不是从原理学起。

6.4 个人体会：文档质量决定源码交付的评分

写到最后说点实在的。技术圈子里有不少人觉得“源码交付包 = 源码压缩包 + 一个README”，这种想法害人不浅。我做过甲方也做过乙方，站在使用者的角度，一次源码交付体验好不好，60%取决于文档质量，40%才取决于代码本身的健壮性。代码再漂亮，部署文档写得含糊，使用者卡在一个环境变量上报错三天，他对整个项目的评价就会直线下降；反过来，就算代码有瑕疵，如果文档里明确写清了“已知问题和临时规避方案”，使用者的体验依然可以是正面的。

我在整理这套智能瘦身小程序系统的文档时，最大的心得是：写文档的时候，要假设读者是一个“比你更没耐心、更不熟悉项目、更可能在半夜两点部署”的人。只有这样，你才会愿意把“别忘了改Redis密码”“证书路径别写绝对路径”“Docker容器里连数据库别用localhost”这些细节事无巨细地写进去。

回看这套系统本身，SpringBoot加微信小程序的组合，足够应对瘦身类业务场景的绝大多数需求。虽然项目规模不大，但涉及用户鉴权、数据建模、业务计算、支付对接、部署上线、文档交付这些完整链路，麻雀虽小五脏俱全。如果你正在做类似的小程序系统，希望这篇分享中关于数据模型设计、导航栏适配、部署文档编写和代码讲解组织的内容，能帮你少走几步弯路。