企业官网建设流程全解析

简介：这是一份基于Java与Vue前后端分离架构的云上健步走微信小程序设计源码，面向需要学习微信小程序开发、运动健康类项目或红色文化主题应用的学生与开发者。项目围绕微信步数兑换里程积分、关卡解锁、红色文化知识学习及个人/队伍/团队排行榜、勋章机制等核心功能展开，适合作为课程设计、毕业设计或实际项目参考。压缩包共831个文件，包含322个Java后端源文件、140个XML配置、102个SVG图形、101个Vue组件、88个JavaScript文件，以及jpg、vm、scss、html等辅助资源，整体约9.27MB。资源目录结构清晰，涵盖前后端分离的开发环境配置、构建脚本和静态资源，便于快速导入与二次开发。已有545人学习下载。通过阅读源码，可掌握Java后端接口设计、Vue组件化开发、微信小程序交互逻辑及项目工程化组织方式，并借鉴其融合运动健康与红色文化传播的产品设计思路。

1. 为什么云上健步走先从 wx.getWeRunData 看起

拿到这套源码，我第一反应不是看 Java 写了多少，而是先找 wx.getWeRunData 的调用位置。云上健步走这类微信小程序，技术难点从来不在页面，而在把微信步数安全地变成后端可信任的业务数据。项目里 322 个 Java 源文件、101 个 Vue 组件、102 个 SVG 图标，说穿了都在服务一件事：用步数换里程、换关卡、换排行。这套源码适合两类人：一类是准备做运动健康类小程序但不知道怎么处理步数授权与积分的 Java 工程师，另一类是接手了带管理端和用户端的多角色项目，想研究前后端分离工程怎么拆分的人。接下来我按源码骨架、步数链路、排行模型、Vue 联调四条线拆着讲。

2. 833 个文件里的分工：Java、Vue、SVG 和 XML 的源码骨架

2.1 先看统计：这 833 个文件是怎么分配的

一眼能看出这是个典型的「小程序原生端 + Vue 管理后台 + Java 接口层」三件套。322 个 Java 源文件说明后端不是简单把 CRUD 堆在一起，而是按controller / service / mapper / model做了分包，XML 里会有相当一部分是 MyBatis 的 SQL 映射，而不是纯 Spring 配置。140 个 XML 配 322 个 Java 文件，这个比例意味着很多查询是手写 SQL 而不是 JPA 自动生成的，手写 SQL 的好处是排行榜和里程汇总这类聚合查询能精确控制索引和临时表行为。

102 个 SVG 是个容易被忽略的信号。项目没有把图标做成雪碧图或 PNG 切片，而是走矢量图标方案。前端把 SVG 作为组件引入，主题色替换只改 fill 属性，不同分辨率下也不会模糊。缺点是如果某张 SVG 是直接从设计稿导出的，路径里可能会带style="fill:#f00"这种内联样式，组件里想覆盖颜色时就失效了。后面接手的同学如果发现勋章颜色改不动，先查 SVG 文件的根节点里有没有写死 fill。

2.2 启动脚本 package.bat / build.bat / run-web.bat 里的门道

项目正文里列了三个 Windows 批处理文件，它们的分工很清楚：package.bat 做全量打包，build.bat 只编后端，run-web.bat 管前端本地开发。常见做法是长这样：

@echo off chcp 65001 >nul rem ====== package.bat：先打后端 jar，再打前端 dist ====== call mvn -f pom.xml clean package -DskipTests -q if errorlevel 1 ( echo [package] backend build failed exit /b 1 ) cd web call npm install if errorlevel 1 goto :frontend_failed call npm run build cd .. echo [package] all done exit /b 0 :frontend_failed cd .. echo [package] frontend build failed exit /b 1

这个脚本里最有用的参数是-DskipTests。云上健步走这类项目里通常有单元测试，但如果是接手别人的代码仓，测试用例往往依赖本地数据库，直接mvn clean package大概率会挂在测试环境连不上。-DskipTests跳过测试执行但保留编译，适合先验证代码能不能跑通。注意它不是-Dmaven.test.skip=true，后者连测试代码编译都跳过，在需要跑测试时才用。

build.bat 我只留一行核心逻辑的话，会是call mvn clean package -pl . -DskipTests，它的作用是快速验证后端改动。而 run-web.bat 会做两件事：先cd web，然后npm install && npm run dev。这里有个 Windows 下常见坑：如果 web 目录下已经存在 node_modules 且是旧版本，npm install 会按 package-lock.json 增量更新，但偶尔会有 package-lock.json 与 package.json 不一致导致依赖版本错乱。我一般出问题就直接删掉 node_modules 和 lock 文件重装，比逐层排查快。

2.3 .gitignore 与 .editorconfig 在多人协作里的实际作用

.gitignore 被列了三次，说明项目在根目录、后端目录、前端目录各放了一份。前端那份通常长这样：

node_modules/ dist/ *.log .env.local .env.*.local

.env.development这类文件最容易踩坑：如果它没被忽略，本地联调的接口地址就会被提交到代码库。云上健步走管理后端开发时，开发机上用的是http://127.0.0.1:8080，一旦被提交，其他人拉下来直接 npm run dev，请求全打到这台开发机内网地址上，表现就是页面 401 或者请求超时。所以.env.development可以提交，但.env.development.local必须忽略，后者才是本地私有配置的落点。

.editorconfig 则是给团队省事的：

root = true [*] charset = utf-8 indent_style = space indent_size = 2 end_of_line = lf insert_final_newline = true

Java 项目多数用 4 空格缩进，前端 Vue 项目习惯 2 空格，这个文件让 IDE 在跨目录时自动切换缩进风格。如果发现 Vue 文件里缩进一会儿两格一会儿四格，先看.editorconfig 是不是被 IDE 忽略了，再检查是不是有人用 Tab 提交过代码。云上健步走这类多模块项目，这一项直接影响代码 diff 的干净程度。

3. 步数换里程的完整数据链路：wx.getWeRunData、解密与积分防刷

3.1 小程序端授权与步数读取

微信步数读取的前置条件是用户授权 scope.werun，这一步要放在用户进入首页时做。如果用户拒绝授权，后期几乎不可能再通过wx.authorize直接弹窗，只能引导到设置页手动打开。所以在健步走这类项目里，我会把授权弹窗放在「点击开始健步走」之后，而不是一进小程序就弹。

// pages/index/index.js Page({ onShow() { wx.getSetting({ success: (res) => { if (res.authSetting['scope.werun']) { this.fetchStepData() } } }) }, handleStartWalking() { wx.getSetting({ success: (res) => { if (res.authSetting['scope.werun'] === false) { wx.openSetting({ success: () => this.fetchStepData() }) } else { wx.authorize({ scope: 'scope.werun', success: () => this.fetchStepData(), fail: () => wx.showToast({ title: '需要微信运动授权', icon: 'none' }) }) } } }) }, fetchStepData() { wx.getWeRunData({ success: ({ encryptedData, iv }) => { wx.request({ url: 'https://api.example.com/walk/convert', method: 'POST', data: { encryptedData, iv }, success: (res) => this.refreshRankAndMileage(res.data) }) } }) } })

这段代码里最关键的决策是把 encryptedData 原样交给后端。因为解密需要微信的 session_key，而 session_key 只能通过 code 换 session_key 的接口拿到，前端拿到 session_key 本身就是安全隐患。所以正确链条是：wx.login 拿 code，后端用 code 换 session_key，再接住 encryptedData 和 iv 做解密。wx.getWeRunData返回的 encryptedData 里包含步数列表和水印信息，watermark 里的 timestamp 可以校验数据是否为最近时段生成，防止旧数据重放。

3.2 Java 后端解密与今日步数提取

后端收到 encryptedData 和 iv 之后，先查 openId，再取 sessionKey 解密。解密算法是 AES-128-CBC，PKCS5Padding，密钥和 IV 都是 sessionKey 和 iv 的 Base64 解码结果：

public WeRunData decryptWeRunData(String sessionKey, String encryptedData, String iv) throws Exception { byte[] keyBytes = Base64.getDecoder().decode(sessionKey); byte[] ivBytes = Base64.getDecoder().decode(iv); byte[] encryptedBytes = Base64.getDecoder().decode(encryptedData); Cipher cipher = Cipher.getInstance("AES/CBC/PKCS5Padding"); cipher.init(Cipher.DECRYPT_MODE, new SecretKeySpec(keyBytes, "AES"), new IvParameterSpec(ivBytes)); String json = new String(cipher.doFinal(encryptedBytes), StandardCharsets.UTF_8); return JSON.parseObject(json, WeRunData.class); }

解密之后拿到的结构里，stepInfoList是一个按时间排序的数组，每个元素包含timestamp和step，step 是到该时间点为止的累计步数，不是增量步数。很多新手在这里会写sum，把同一用户一天内的四条记录全加起来，得到的结果是真实步数的三到四倍。正确做法是取当天时间戳对应条目里 step 最大值，也就是最后一次上报的快照：

public int getTodaySteps(WeRunData data) { long startOfDay = LocalDate.now().atStartOfDay(ZoneId.systemDefault()).toEpochSecond(); return data.getStepInfoList().stream() .filter(item -> item.getTimestamp() >= startOfDay) .mapToInt(StepInfo::getStep) .max() .orElse(0); }

至于步数怎么换算里程和积分，我建议把比率参数放进配置表而不是写死在代码里。常见做法是 2 步折算 1 米，10 米折算 1 积分，这两个数在运营配置里随时调。如果写死在 service 里，每次调整都要重新发布后端，而且团队榜和个人榜的换算口径还可能被不小心改成两套逻辑。

3.3 幂等键与 Redis 的 increment 陷阱

步数数据的核心门槛是防重复兑换。用户每次进小程序都会触发一次 getWeRunData，同一份 encryptedData 如果不做幂等校验，积分会被重复发放。最简单的方案是把 encryptedData 做 SHA-256 取哈希，用 Redis setIfAbsent 写入，十分钟或一小时过期：

String digest = DigestUtils.sha256Hex(encryptedData); String key = "walk:dedup:" + digest; Boolean first = redisTemplate.opsForValue().setIfAbsent(key, "1", Duration.ofHours(1)); if (!Boolean.TRUE.equals(first)) { throw new BizException("重复提交，请稍后再试"); }

这里不建议用redisTemplate.opsForValue().increment(key)做计数器，原因很具体：当 key 不存在时 increment 会返回 1，这个行为看起来没问题，但如果你先 set 了字符串类型的值，再执行 increment，Spring Data Redis 会抛RedisCallbackReturnTypeMismatchException，错误信息就是那句很常见的 "value is not an integer or out of range"。类似这种排查在 java 面试和日常开发里都属于高频问题，本质都是没搞清楚 Redis 底层 value 编码。幂等场景下 setIfAbsent 一次写入就够了，不需要 increment。

里程兑换走的是「先校验幂等，再写流水，再更新日汇总」三步。日汇总表应该对 (open_id, stat_date) 建唯一索引，每天的步数和里程只保留一条记录，更新的 SQL 用INSERT ... ON DUPLICATE KEY UPDATE完成：

INSERT INTO user_step_daily (open_id, stat_date, steps, mileage, points, update_time) VALUES (?, CURRENT_DATE, ?, ?, ?, NOW()) ON DUPLICATE KEY UPDATE steps = VALUES(steps), mileage = VALUES(mileage), points = VALUES(points), update_time = NOW();

这样保证一天只有一行，排行榜直接 sum 这张表，不需要再靠明细表实时聚合。

4. 关卡解锁、三项排行榜与勋章机制的表结构设计

4.1 关卡表：累计里程解锁而不是碎步数解锁

云上健步走的关卡设计和普通答题小程序不一样，它强调的是「走到一定里程才能进入下一个学习节点」。这里我建议用累计里程做门槛，而不是当日步数。如果按当日步数解锁，用户只要某天暴走一万步就能把所有关卡打通，运营设计的节奏感就没了；按累计里程，用户必须连续参与。

关卡表最小集合是这几个字段：

CREATE TABLE walk_stage ( id BIGINT PRIMARY KEY AUTO_INCREMENT, stage_no INT NOT NULL COMMENT '关卡序号', stage_name VARCHAR(64) NOT NULL COMMENT '关卡名称', need_mileage INT NOT NULL COMMENT '解锁所需累计里程，单位：米', knowledge_id BIGINT COMMENT '绑定的知识卡片ID', reward_points INT DEFAULT 0 COMMENT '首次通关奖励积分', sort_order INT DEFAULT 0, created_at DATETIME DEFAULT CURRENT_TIMESTAMP, UNIQUE KEY uk_stage_no (stage_no) );

用户进度则单独建表：

CREATE TABLE walk_user_stage ( id BIGINT PRIMARY KEY AUTO_INCREMENT, open_id VARCHAR(64) NOT NULL, stage_no INT NOT NULL, unlocked_at DATETIME NOT NULL, finished_at DATETIME DEFAULT NULL COMMENT '知识学习完成时间', UNIQUE KEY uk_openid_stage (open_id, stage_no) );

解锁判断可以等步数兑换成功后在事务里做：先 sum user_step_daily 里该用户的累计里程，再查出当前最大已解锁关卡，如果里程达到下一关门槛就插入 walk_user_stage。这个逻辑放在 Java service 里比在存储过程里好维护，因为解锁的同时可能还要发消息、记录勋章，Java 侧能直接编排。

4.2 个人、队伍、团队三个排行榜：维度不同，存储口径也不同

项目里三个排行榜别搞成一张表三个字段打天下。个人榜关心的是单个 open_id 的里程，队伍榜关心的是一个小队合起来的里程，团队榜则是按组织维度聚合，时间窗口都不一样。

个人榜 SQL 是最直接的教学样本：

SELECT open_id, SUM(mileage) AS total_mileage, ROW_NUMBER() OVER (ORDER BY SUM(mileage) DESC) AS rank_no FROM user_step_daily WHERE stat_date BETWEEN :startDate AND :endDate GROUP BY open_id ORDER BY total_mileage DESC LIMIT 100;

MySQL 8.0 以上支持窗口函数，ROW_NUMBER 可以稳定地给相同里程排出先后顺序。如果后端用的是 5.7，就只能用@rownum := @rownum + 1这种变量写法，但并发和分页时容易出现排名错位，建议直接升 8.0。

队伍榜和团队榜不要在 SQL 里实时 join，因为数据量上来之后，几次联表+sum 会把接口拖慢。更常见的做法是每天凌晨跑一个统计任务，把队伍、团队的日里程写入一张 rank_daily 汇总表，页面只查汇总表。个人榜如果也要支撑大流量，同样可以把 TOP 100 结果缓存到 Redis，用 ZSET 存储，score 是里程数，member 是 open_id 或 team_id，每次步数兑换成功后 ZADD 一下，查询走 ZREVRANGE。

redis-cli ZADD walk:rank:team:202506 12800 team_01 redis-cli ZREVRANGE walk:rank:team:202506 0 99 WITHSCORES

ZADD 在同一个 key 上反复执行不会重复插入，而是更新分数，天然适配里程叠加的场景。这就是为什么排行榜场景很少直接查 MySQL。

4.3 勋章解锁：规则引擎还是定时扫描

勋章机制本质上是一组条件判断。条件类型可能是「累计里程达到 X」「连续打卡 7 天」「队伍周榜进入前 10」。在代码里用 if else 写会越写越臭，后期加一个勋章就要重新改 Service。我倾向于把勋章规则也做成一张表：

CREATE TABLE walk_medal_rule ( id BIGINT PRIMARY KEY AUTO_INCREMENT, medal_code VARCHAR(32) NOT NULL, medal_name VARCHAR(64) NOT NULL, condition_type VARCHAR(32) NOT NULL COMMENT 'mileage / consecutive_days / rank_top', condition_value VARCHAR(64) NOT NULL COMMENT '条件数值或配置JSON', svg_path VARCHAR(255) COMMENT '勋章图标SVG路径', UNIQUE KEY uk_medal_code (medal_code) );

判断发放的时机有两种：一种是事件驱动，步数兑换完成后立刻检查；另一种是每日定时全量扫描。事件驱动响应快但耦合重，每个业务动作里都得插一段勋章检查代码；定时扫描实现简单但勋章发放会延迟一天。我一般会折中：主要结算逻辑走定时任务，特殊勋章走事件驱动。核心判断方法写成一个 MedalEngine，不直接依赖具体业务表：

@Component public class MedalEngine { private final MedalRuleMapper ruleMapper; private final UserMedalMapper userMedalMapper; @Transactional public void checkAndUnlock(String openId, WalkSummary summary) { List<MedalRule> rules = ruleMapper.selectAllEnabled(); for (MedalRule rule : rules) { if (userMedalMapper.exists(openId, rule.getMedalCode())) { continue; } boolean matched = switch (rule.getConditionType()) { case "mileage" -> summary.getTotalMileage() >= Integer.parseInt(rule.getConditionValue()); case "consecutive_days" -> summary.getConsecutiveDays() >= Integer.parseInt(rule.getConditionValue()); case "rank_top" -> summary.getBestRank() <= Integer.parseInt(rule.getConditionValue()); default -> false; }; if (matched) { userMedalMapper.insert(new UserMedal(openId, rule.getMedalCode())); } } } }

这套写法的好处是新加勋章只需要在 walk_medal_rule 插一条记录，代码不用改。102 个 SVG 里很大一部分就是给这些勋章准备的，图标路径存 SVG 的路径文件名，前端通过svg_path拼出图片地址。

4.4 小程序端首屏渲染与顶部导航栏高度适配

健步走小程序使用自定义导航栏时，要么用navigationStyle: custom全权接管，要么只调节页面布局的 padding-top。最常见的做法是把状态栏高度和右上角胶囊按钮高度算出来，动态给顶部占位视图设高度，避免刚进入的小程序页面顶栏把「微信步数」主按钮顶下去：

// 兼容基础库版本，获取顶部安全距离 const win = wx.getWindowInfo ? wx.getWindowInfo() : wx.getSystemInfoSync() const statusBarHeight = win.statusBarHeight || 20 const capsule = wx.getMenuButtonBoundingClientRect() const navBarHeight = capsule.height + (capsule.top - statusBarHeight) * 2 + statusBarHeight Page({ data: { navBarHeight }, onLoad() { // 先从本地缓存渲染步数，再异步刷新，避免首屏白屏 const cached = wx.getStorageSync('lastStepCount') this.setData({ stepCount: cached || '--' }) } })

首屏加载策略是：先读本地缓存渲染一次，同步请求后端拿最新数据后再覆盖。这样即使接口慢，用户刚进入时也不会看到空白加载层。也顺手把「修改刚进入的加载页面」这类需求局限在 index 页自己的生命周期里，而不是去改小程序根配置的全局 loading 行为。

5. run-web.bat 起 Vue 管理端：环境变量、转发规则与联调避坑

5.1 .env.development 决定 Vue 管理端往哪里发请求

Vue 管理端是独立的 web 工程，它和后端 Java 服务之间通过 HTTP 接口通信。本地开发时最常出问题的就是.env.development里的接口基地址配错。Vite 项目里常见配置是：

# web/.env.development VITE_APP_BASE_URL=/api VITE_APP_UPLOAD_URL=/upload VITE_DEV_SERVER_PORT=5173

如果管理端和后端都在本机，VITE_APP_BASE_URL写成/api，再配合 vite.config.js 里的转发规则，把/api开头的请求转发到 Java 服务的 8080 端口：

// web/vite.config.js import { defineConfig } from 'vite' import vue from '@vitejs/plugin-vue' export default defineConfig({ plugins: [vue()], server: { port: 5173, proxy: { '/api': { target: 'http://127.0.0.1:8080', changeOrigin: true } } } })

这里把VITE_APP_BASE_URL设置为绝对地址http://127.0.0.1:8080也能跑，但上线前必须改成相对路径。我见过不少项目本地联调没问题，打包后接口 404，就是因为.env.production 里还留着 localhost。用相对路径 + 转发规则是更稳的做法，生产环境由 Nginx 统一转发。

run-web.bat 里的核心命令就几行：

cd /d %~dp0web npm install npm run dev

%~dp0取的是批处理文件所在目录，这样不管在哪个路径下执行都不会跑错目录。

5.2 联调验证顺序与常见失败点

跑起来之后别急着点页面，先按这个顺序验证链路：

:: 1. 确认后端健康检查 curl http://127.0.0.1:8080/health :: 2. 确认 Vue 转发是否生效，能看到登录接口 JSON 返回即是通 curl http://127.0.0.1:5173/api/health :: 3. 静态资源配置是否正常 curl -I http://127.0.0.1:5173/favicon.ico

第一条通了说明 Java 服务正常，第二条通了说明转发链路正常。如果第一步 200、第二步 404，基本是 vite 转发规则里的 target 端口写错，或者后端接口前缀不是 /api。第二步如果返回 HTML 而不是 JSON，检查是不是后端返回了 404 页面，转发逻辑本身没有错。

微信小程序端的联调不要依赖外部抓包工具，微信开发者工具自带的 Network 面板已经能看到每个请求的域名、header、返回体。真正要注意的是 request 合法域名校验：开发环境下要关掉 URL 校验，或者把接口域名加到开发白名单。如果小程序里wx.request用的是 IP 加端口，开发者工具会拦截；真机预览更严格，只能填 app.json 里配置过的域名。跑管理端和跑小程序端是两套环境，别混着看，小程序接口出问题先看 Network 面板里是errno还是invalid url，前者是后端逻辑，后者是域名配置。

本文还有配套的精品资源，点击获取