做这个“全民健身App”项目的时候，我们当时的情况是：后端一个人、Android端一个人，两周要交出可演示的版本。所以从一开始，我就把“协议先行、前后端并行、接口尽量简单”定成了项目铁律。整个系统基于SpringBoot搭建服务端，Android端用原生开发，核心功能覆盖用户注册登录、运动轨迹记录、健身计划管理、社区帖子和数据统计，是一个典型的移动互联网全栈小项目。这篇记录不打算抄官方文档，而是把我实际做这个项目时踩过的坑、想过的问题、最后敲定的方案，全部按真实流程讲一遍。如果你正准备做类似的运动健康类应用，或者正在带一个前后端并行的小团队，这篇文章应该能帮你省下不少试错时间。
1. 项目全貌与核心需求拆解
1.1 全民健身App到底在解决什么问题
先说说需求。全民健身这个概念听起来很大，落到App功能上其实可以收敛成四个核心闭环。
第一个是“运动记录闭环”。用户跑步、健走、骑行的时候，App要能记录时长、里程、配速、消耗卡路里，最好还能把运动轨迹画出来。第二个是“计划执行闭环”。用户能看到训练计划，比如一周跑三次、每次三十分钟，跑完打卡，系统给反馈。第三个是“社交激励闭环”，这也是全民健身App和普通计步器最不一样的地方——用户发动态、晒成绩、点赞评论，用社交比较来提升运动黏性。第四个是“数据洞察闭环”，把历史运动数据按周、月聚合，让用户看到自己的变化趋势。
这四个闭环表面上各自独立，实际上共享同一个数据底座：用户、运动记录、计划、帖子。所以在设计阶段，我们没有按“页面”去反推表结构，而是先按领域对象把核心实体定下来。这也是我把后端数据库设计看作整个项目地基的原因——表结构一旦定得别扭，后面每加一个功能都要带着“历史包袱”改代码，那种酸爽谁改谁知道。
1.2 技术选型：为什么是SpringBoot + Android原生
这个组合放到今天来看不算新，但对这类项目恰恰是最稳的选择。后端用SpringBoot，好处是生态成熟、起步快、可参考案例多，一个Maven工程拉起来，内嵌Tomcat，部署不用额外配置外部容器。我们用的是SpringBoot 2.7.x + MyBatis-Plus + MySQL 8.0 + Redis，这套组合在中小型业务系统里被验证过无数次，遇到问题网上答案一搜一大把，这对小团队来说太重要了。
Android端没有选跨平台方案，原因有几个。第一，运动类App对系统定位服务的依赖非常重，Android原生访问LocationManager、前台服务、后台定位权限都更直接，跨平台框架在这些地方虽然有封装，但遇到不同手机厂商的Rom差异化适配时，最终还是要回到原生API去补丁。第二，当时团队里没人写过跨平台，没必要为了“潮流”引入学习成本。第三，轨迹绘制和图表渲染需要跟Canvas、自定义View深度配合，原生写起来最顺手。
所以这个选择本质上不是“技术对比谁更好”，而是“在给定资源和时间下谁更稳”。如果团队本身是前端背景，选跨平台也完全合理，但“选最熟的工具”永远比“选最热的技术”更接近项目成功。这是我的一个很深的体会。
2. 后端架构与数据库设计
2.1 SpringBoot工程结构与分层设计
工程结构我直接放一个可以复制的案例出来。标准做法是按“功能模块 + 技术分层”双维度组织，包名用com.example.fitness开头，下面分controller、service、mapper、entity、dto、config、common。实际写的时候我建议entity和dto分开，别图省事直接用实体类接收请求参数，否则前后端字段一旦不一致，接口联调的时候你会在“为什么这个字段是null”上浪费大量时间。
这是我当时controller层的一个简化样例：
@RestController @RequestMapping("/api/record") public class RecordController { @Resource private RecordService recordService; /** * 上传一条运动记录 */ @PostMapping("/upload") public Result<?> upload(@RequestBody @Valid RecordUploadDTO dto) { recordService.upload(dto); return Result.success(); } /** * 查询我的运动历史（分页） */ @GetMapping("/list") public Result<PageResult<RecordVO>> list(@RequestParam(defaultValue = "1") Integer page, @RequestParam(defaultValue = "20") Integer size) { return Result.success(recordService.pageList(page, size)); } }有几个细节值得强调。第一，所有接口返回统一包装结构Result，用code/message/data三段式，前端拿到后先判断code再解析data，而不是靠HTTP状态码，因为业务错误（比如“手机号已注册”）返回200配合业务code，对客户端处理更友好。第二，参数校验用javax.validation的注解，比如@NotBlank、@NotNull，直接标到DTO字段上，比自己在service里写一坨if判断干净太多。
service层我习惯把“事务操作”放在这里。比如上传运动记录时要同时写主表和轨迹明细表，就用@Transactional(rollbackFor = Exception.class)包住，保证两条SQL要么都成功要么都回滚。mapper层就是MyBatis-Plus的BaseMapper，简单CRUD基本不用写SQL，复杂聚合查询再手写XML，分工很清晰。
2.2 核心表结构与索引设计
数据库我们用了6张核心业务表：t_user用户表、t_record运动记录主表、t_track_point轨迹点表、t_plan健身计划表、t_plan_record打卡表、t_post帖子表，外加t_comment和t_like做评论和点赞。别小看这种“看着挺普通”的设计，后面跑统计SQL的时候你会发现，越是普通的表结构，越不容易写出冗余和性能问题。
运动记录的建表语句大概是这样的，我做了精简：
CREATE TABLE `t_record` ( `id` bigint NOT NULL AUTO_INCREMENT COMMENT '主键', `user_id` bigint NOT NULL COMMENT '用户ID', `sport_type` tinyint NOT NULL COMMENT '1跑步 2健走 3骑行', `distance_m` int NOT NULL DEFAULT 0 COMMENT '里程(米)', `duration_s` int NOT NULL DEFAULT 0 COMMENT '时长(秒)', `calorie` int NOT NULL DEFAULT 0 COMMENT '消耗千卡', `start_time` datetime NOT NULL COMMENT '开始时间', `end_time` datetime NOT NULL COMMENT '结束时间', `track_count` int NOT NULL DEFAULT 0 COMMENT '轨迹点数量', `create_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP, PRIMARY KEY (`id`), KEY `idx_user_start` (`user_id`, `start_time`) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;索引这块我踩过一次明显的坑。最开始我在t_record上只建了user_id一个索引，数据量上到几万之后，“查某用户某月运动记录”这种语句直接慢到800毫秒。后来把(user_id, start_time)建成联合索引，同样的查询降到30毫秒以下。原因很简单：MySQL的联合索引可以同时过滤用户和区间范围，避免“先查出该用户所有记录再排序筛时间”的低效路径。运动类业务最核心的查询就是“按人+按时间”，所以这组联合索引是必备的。
轨迹点表t_track_point要注意别把每个点存成VARCHAR的“经纬度字符串”，那会让统计和抽稀都非常痛苦。我拆成lat（DECIMAL(10,7)）、lng（DECIMAL(10,7)）两个字段，并且用record_id建索引，查询某条记录的轨迹时走索引拉全部点，按时间顺序排列即可。DECIMAL精度选7位已经能覆盖厘米级定位精度，存成FLOAT反而会有小数点漂移的问题。
2.3 统一认证与接口安全
登录认证我们没有上厚重的Spring Security全家桶，而是用了JWT + 自定义拦截器。对这类项目来说，Spring Security的过滤器链配置成本比它带来的安全收益要高，属于杀鸡用牛刀。JWT方案的思路是：用户登录成功后，后端签发一个带过期时间的Token，客户端保存并在后续请求头里带上Authorization: Bearer xxx，后端用一个拦截器校验Token并解析出userId，放到ThreadLocal里供业务使用。
签发和校验我封装成了一个JwtUtil，核心逻辑用jjwt库，大概这样：
public class JwtUtil { private static final SecretKey KEY = Keys.hmacShaKeyFor( "please-replace-with-random-secret-key-at-least-32-bytes".getBytes()); public static String createToken(Long userId, String phone) { return Jwts.builder() .claim("userId", userId) .claim("phone", phone) .setExpiration(new Date(System.currentTimeMillis() + 7 * 24 * 3600 * 1000L)) .signWith(KEY, SignatureAlgorithm.HS256) .compact(); } public static Claims parseToken(String token) { return Jwts.parserBuilder().setSigningKey(KEY).build() .parseClaimsJws(token).getBody(); } }注意：这里用的是jjwt 0.11.x的API，0.12.x版本里parserBuilder改成了verifyWith，升级的时候别照着老博客抄，否则编译都过不去。另外，生产环境的secret key绝不能硬编码在代码里，要放到环境变量或配置中心，一旦泄露就等于所有用户的Token都能被伪造。
这里还有几个藏得比较深的坑。第一，JWT过期时间我设了7天，App这种长驻场景太短会频繁踢用户下线，太长又有安全风险，实际可以做成“7天有效 + 请求时刷新”的策略。第二，拦截器里解析完Token后，要记得在finally里清理ThreadLocal，不然线程池复用线程的时候，下一个请求可能读到上一个用户的ID，这是非常隐蔽的越权Bug，一旦线上出现“用户A看到用户B数据”的问题，十有八九就是这里。
3. 核心功能接口的落地细节
3.1 运动记录与轨迹处理
运动记录上传是数据入口，也是整个App最核心的接口，它的设计直接决定了数据质量。Android端在运动结束后，会把一次运动汇总成两部分提交：一个是RecordUploadDTO，包含运动类型、总里程、总时长、总卡路里、开始结束时间；另一个是轨迹点数组，可能几百到上千个点。如果一次性把上千个点塞进一个JSON，接口体积会非常大，所以我们做了两次传输：先传汇总信息拿回recordId，再分批上传轨迹点。
这个设计除了降低单次请求大小，还有一个明显的好处：就算轨迹点上传到一半失败了，运动汇总数据已经落库，用户至少能看到“今天跑了一次”，不至于因为网络抖动整条数据丢失。这一点对运动类App的体验非常重要——运动记录是最不能丢的数据。
轨迹点还有一个必要处理，叫“抽稀”，也就是用道格拉斯-普克这类算法去掉冗余点。用户在跑步时，定位SDK每秒会回一个点，走一条直线的时候其实每100米存一个点就够了，否则运动一小时能产生3600个点，一个月下来轨迹表数据量非常可观。我们当时在Android端做了简单抽稀，规则是“时间间隔超过5秒，或者距离上次已存点超过10米，才保存当前点”，实测数据量能压缩到原来的30%左右，而轨迹画出来几乎没有肉眼可见的区别。
3.2 运动统计报表的聚合查询
统计接口是另一个让后端头疼的地方。我们要给用户展示“本周运动次数、总里程、总时长、热力趋势”，如果每次都实时去扫t_record全表聚合，数据量上来后性能会越来越难看。我们的方案是“汇总表 + 累加更新”：建一张t_daily_stat表，按每个用户每天一条记录，存当天的运动次数、总里程、总时长和卡路里。运动记录上传成功后，在同一个事务里更新当天对应的汇总行（没有就插入）。查询周报表时，只需要按user_id和时间范围扫7行汇总数据，聚合操作直接变成内存计算，速度从几百毫秒降到个位数毫秒。
这里面的关键点：汇总更新别用先select后update的方式，要直接写累加式SQL，避免并发丢更新：
INSERT INTO t_daily_stat (user_id, stat_date, sport_count, total_distance, total_duration, total_calorie) VALUES (?, ?, 1, ?, ?, ?) ON DUPLICATE KEY UPDATE sport_count = sport_count + 1, total_distance = total_distance + VALUES(total_distance), total_duration = total_duration + VALUES(total_duration), total_calorie = total_calorie + VALUES(total_calorie);(user_id, stat_date)做成唯一索引，这样同一用户同一天的运动数据不管怎么并发更新，最终都是累加而不是互相覆盖。这个“预聚合”思路，比起依赖复杂的统计SQL来实现报表简单太多，也稳太多。后来我们给排行榜、周报、月报都复用了这张汇总表，等于一份数据多处受益，维护成本反而更低了。
3.3 社区模块的接口设计
社区模块本质上就是一个轻量级社交系统，我们把它拆成帖子列表、发帖、点赞、评论四组接口。帖子列表支持按最新和按热门排序，热门排序的简化做法是“点赞数 + 评论数*3”算一个热度分，然后按热度分倒序。不引入复杂推荐算法，对全民健身的社区场景完全够用。
点赞功能这里有个经典的选择题：用Redis的Set还是直接数据库计数？我们最终用了数据库“点赞表 + 帖子表冗余点赞数字段”的方案。点赞时先insert点赞表（唯一约束防重复），成功再对帖子表的like_count做自增。这个方案在高并发下不如Redis精确，但这个项目的量级远没到那个程度，而且用Redis的话还要解决数据落库一致性问题，维护成本更高。做技术选型的时候一定要考虑业务量级，别为了一百年后的并发，把今天的开发复杂度和稳定性都搭进去。
评论接口相对简单，按帖子ID加分页查询，字段就是评论人、内容、时间。唯一要注意的是评论和帖子内容要做XSS过滤和敏感词拦截，不然社区很容易变成垃圾信息场。我们在后端接了一个简单敏感词工具类，发布评论和帖子时都过一遍，命中就直接拦截返回提示，效果比事后人工删帖好太多了。
4. Android客户端的实现要点
4.1 网络层封装与生命周期管理
Android端我们用的Kotlin + Retrofit + OkHttp + 协程。Retrofit负责接口定义，OkHttp负责拦截器，协程负责异步切换。这里给一个当时ApiService的简化写法：
interface ApiService { @POST("/api/user/login") suspend fun login(@Body body: LoginRequest): Result<LoginData> @POST("/api/record/upload") suspend fun uploadRecord(@Body body: RecordUploadRequest): Result<Long> }所有接口返回统一用Result 包装，后端结构是code/message/data，Android这边解析的时候先判断code，只有code为0才认为成功。这里有个编码习惯，如果你让前端根据HTTP状态码判断成功失败，后端一旦配置了全局异常处理把所有异常都转成200返回，前端就会把错误数据当成正常数据处理。所以协议从一开始就要约定好“以业务状态码为准”。
Token的携带我们用OkHttp的Interceptor统一处理，在拦截器里读取本地存的Token，加到请求头；响应拦截器里判断401，就触发“重新登录”或者跳转登录页。这里要特别注意，拦截器里不能直接做弹窗或者跳页面，跨层操作容易导致内存泄漏，正确做法是抛出一个特殊异常，由ViewModel层捕获后统一发事件，把UI操作收敛到页面层。
4.2 定位与运动轨迹采集
运动轨迹采集是Android端技术含量最高的部分，要点有两个：一是怎么稳定地拿定位，二是怎么把定位点“画”出来。定位我们用的是系统LocationManager配合前台服务（Foreground Service）。Android 8以上，应用在后台必须依赖前台服务才能持续定位，这个不做的话应用一到后台就被系统杀掉，轨迹直接断掉。
前台服务需要配套一个常驻通知，不然系统会判定为“异常后台行为”。建议参考官方文档配置notification渠道，然后把定位逻辑放到服务里，用START_STICKY保证服务异常被系统回收后能自动重建。权限方面要注意：Android 10以上要单独申请后台定位权限（ACCESS_BACKGROUND_LOCATION），Android 11以上系统不再允许应用在首次安装后直接申请后台定位，必须引导用户去设置页手动打开；Android 12以上还多了“大致定位”和“精确位置”的区分。这个权限不是弹一次就能给，所以设计功能引导的时候要给用户讲清楚为什么要开后台定位，不然用户没开就直接以为功能坏了，这是我们的一个深刻教训。
轨迹绘制我们用的是自定义View加Canvas，把经纬度点经过简单的等距投影换算成屏幕坐标后画线。如果你用了第三方地图SDK，它有现成的Polyline接口，会省很多事。但自己画的优势是包体小、不依赖地图厂商的key和服务，适合不需要卫星图、路网底图的场景。全民健身App只需要把轨迹画在简易背景上，完全没有必要引一个体积很大的地图SDK。
4.3 本地缓存与弱网体验
运动数据是用户最在意的资产，所以本地缓存策略直接决定了App的可用性。我们的策略是三级思路：第一，运动记录先写本地数据库再从网络上传，上传成功打标记；第二，列表页数据默认读缓存，后台静默刷新；第三，用户信息和Token存到加密的SharedPreferences。
本地数据库用的是Room，存一张本地运动记录表，字段和远端基本对齐，多加一个uploadStatus字段标记“未上传/上传中/已上传”。每次运动结束，先落本地、置为未上传，然后启动上传；上传失败不删数据，下次App启动或者网络恢复时，通过WorkManager触发补传。这一个机制做完，用户即使在信号不好的地方跑步、在地下停车场结束运动，记录也不会丢，口碑一下就上来了。
注意：Room的数据库升级一定要写Migration，版本号加一就必须提供对应的迁移逻辑，否则用户升级App后打开就直接崩溃。这是Android本地存储最容易踩的雷，没有之一。
移动端开发永远别假设网络是可靠的，这个假设省下来的开发量，最后都会变成用户差评找回来。我见过太多App因为“想当然觉得上传会成功”把用户数据弄丢，这种错误一旦发生就很难挽回。
5. 联调、部署与性能优化
5.1 前后端联调踩坑实录
前后端并行开发，最怕的就是“接口约好了，但两边对字段的理解不一样”。我们当时犯过一个很典型的错误：后端的LocalDateTime默认序列化格式是带T的ISO格式，比如“2025-06-01T20:30:00”，而Android端解析器默认期望“yyyy-MM-dd HH:mm:ss”，结果所有时间字段全部解析失败，页面上一排时间全是null。排查了快半天才发现是序列化格式不一致。后来统一在后端配置了Jackson的全局时间格式，这个问题才彻底解决。
另外几个常见联调坑也一并说下：第一，图片上传接口要约定好返回完整URL还是相对路径，我们当时返回了相对路径，前端又没拼域名，导致图片全部裂图。第二，分页参数命名要完全一致，后端用page和size，前端就别用pageNum和pageSize。第三，错误信息的展示策略要提前约定，后端返回中文错误提示后，前端是直接弹Toast还是做表单校验展示，两边要统一，不然用户看到的就是“系统异常”这种毫无信息量的提示。
提示：这次项目里最值钱的经验就是“先写接口文档再写代码”。我们前期图省事没写，联调第二周就花了两天处理字段不一致的问题。哪怕用简单的表格列清每个字段的名称、类型、示例值，都能省下大量时间。
这些看起来都是小问题，但在联调阶段会消耗大量时间，最好的办法是让文档走在代码前面，靠文档而不是靠嘴对需求。
5.2 服务端打包部署
后端部署我们用了最传统的“Maven打包 + 云服务器 + 外部Nginx”组合。SpringBoot内嵌Tomcat，直接java -jar跑就行。关键点是要把配置外置化：数据库密码、Redis地址、Token密钥等不写死在application.yml里，用application-prod.yml覆盖，或者直接从环境变量读取，这样代码仓库即使被看光，别人也拿不到生产环境的敏感信息。
部署步骤简单梳理一下：本地mvn clean package打出jar包，scp上传到服务器，再用systemd写一个服务文件实现开机自启和崩溃重启，最后用Nginx做反向代理，把/api路径转发到应用监听的8080端口，同时配置HTTPS证书。有个细节，Android 9以上默认禁止明文HTTP，开发环境要么在network_security_config里临时放行，要么干脆让后端配好HTTPS再联调。现在SSL证书申请已经不那么麻烦，直接上HTTPS是正路，别在明文HTTP上花功夫。
关于服务器配置，我们当时用的是一台2核4G的云主机，MySQL和Redis和应用都放在同一台上，初期完全够用。数据库连接池用HikariCP默认配置，加了一个关键参数：maxLifetime比数据库wait_timeout稍短，避免连接被MySQL服务端回收后客户端还在用的“死连接”问题。这个参数不调，运行几天后会出现偶发SQL异常，特别隐蔽，属于那种“不查日志根本不知道发生了什么”的问题。
5.3 性能与体验优化
性能优化这件事，我跟团队定的原则是“先量后调”。Android端先用自己的Profile工具看卡顿帧率，后端看慢SQL日志定位查询瓶颈，谁慢先解决谁。我们实际优化的几个点很有代表性。
第一个是接口返回体积。运动列表接口当时把轨迹点也一并返回了，一条记录几千个点，接口体积直接奔着几兆去，列表当然卡。后来改成轨迹点单独接口，列表只返回汇总字段，列表体积缩到原来的百分之一，流畅度一下就上来了。第二个是图片优化。帖子里的图片如果不压缩，一张原图可能5M，列表页加载一堆5M图，流量和内存都受不了。我们后端上传接口统一做了缩略图处理，Android端用Glide的override尺寸配合内存缓存，图片加载瞬间轻了很多。第三个是冷启动优化。Android端启动时不要同步做网络请求和数据库初始化，用协程把这些任务分流到不同线程，启动页保持轻量，体感启动时间从3秒降到1.5秒以内。
这些优化没有一个用了高深的技术，全是工程上最基本的取舍，但组合起来效果非常明显。性能优化最怕一上来就搞各种“黑科技”，最后发现瓶颈根本不在这，白白浪费时间。
6. 常见问题排查与实战心得
6.1 高频问题速查表
把项目过程中最常遇到的问题整理成一张表，方便你直接对照排查：
| 现象 | 可能原因 | 解决办法 |
|---|---|---|
| 登录接口报400 | 请求体字段和后端DTO不匹配 | 检查JSON字段名是否完全一致，确认前后端字段命名规范统一 |
| 时间字段解析为null | 前后端日期格式不一致 | 后端统一返回固定格式或时间戳，前端按约定解析 |
| 运动轨迹突然中断 | 后台被系统杀死或权限未开 | 前台服务 + 常驻通知 + 引导用户开启后台定位 |
| 列表图片加载很慢 | 原图太大且未做缩略图 | 上传时生成缩略图，客户端按控件尺寸加载 |
| 偶发“连接被重置” | 数据库连接池死连接 | 调短HikariCP maxLifetime参数 |
| 统计数字不对 | 并发下先查后更新丢更新 | 改成累加式SQL + 唯一索引 |
| 帖子评论出现乱码 | 表字符集不是utf8mb4 | 建库建表统一用utf8mb4，连接串加characterEncoding=UTF-8 |
| 上传轨迹点太慢 | 一次性上传上千个点 | 抽稀 + 分批上传 |
这张表看着简单，但每一条都是真实项目里花过时间换来的。我最想强调的还是那条“统计数字不对”：如果做的是先select旧值再update新值，两个请求并发的时候后写的覆盖先写的，数字就神秘地“差一点”。改成累加SQL之后，这个问题从根上消失，再也不用半夜被报警电话叫醒。
6.2 项目复盘与个人体会
做完这个项目，我最大的体会是：这类“常规”项目的难点从来不在某个单点技术上，而在“怎么把一堆常规技术可靠地串起来”。SpringBoot、Android、MySQL、Redis，每一个单独拎出来都有大量教程，但真正决定项目质量的，是那些没人写进教程的细节：Token密钥怎么管、时间格式怎么统一、轨迹要不要抽稀、统计怎么预聚合、后台定位怎么保活、弱网下数据怎么不丢。
如果让我再做一遍，我会在项目第一天就把接口文档用工具管理起来，而不是等人问“这个字段叫什么”才去补。我还会给Android端更早引入崩溃上报和日志采集，因为很多问题在开发机上根本复现不了，只有线上日志能还原真相。另外，测试一定要覆盖不同品牌、不同安卓版本的手机，我们被某厂商的激进杀后台策略坑了好几次，最后是在真机上反复调试才摸清规律。
最后再分享一个具体的经验：运动记录上传失败重试的时候，一定要做幂等处理。我们在record表加了业务唯一键（user_id + start_time + sport_type），重复上传时用INSERT ... ON DUPLICATE KEY UPDATE保证只产生一条记录。这个设计在用户手动重试、断网续传、多端同步的时候都救了命。做个运动类项目，数据可靠性永远比花哨功能更能留住用户。
