一提到“跑步打卡”类App很多初学者第一反应是“这不就是个计步器吗”。真上手做过一遍你就会发现里面的坑比想象中多得多定位漂移、后台被杀、距离不准、连续打卡状态管理……这些才是项目真正有价值的地方。我这次把一个完整的安卓跑步打卡项目从零到一做了拆解源码和文档都在手边正好把整个开发过程、核心模块的实现思路、以及文档怎么写才不糊弄人一次性讲透。这个项目适合正在学安卓开发的初中级工程师也适合想做课程设计、毕设或者单纯想在简历上放一个有完整闭环的项目的人。看完这篇你不仅能看懂源码还能自己动手把每个模块讲清楚面试的时候也说得上路。1. 整体设计思路与功能模块拆解1.1 从需求反推项目结构跑步打卡项目的核心需求其实就三件事记录一次跑步过程、把结果存下来、展示历史记录并形成打卡状态。听起来简单但“记录一次跑步过程”这句话展开就很复杂——你需要持续获取GPS位置、计算实时配速、在地图上绘制轨迹、防止App被系统回收、合理处理前后台切换……我设计这个项目时先画了一张功能脑图把需求拆成了五个模块用户模块简单的本地登录/注册不接后端数据存SQLite或SharedPreferences主要是为了让项目有一个完整的“个人中心”闭环。运动模块核心模块负责启动/暂停/结束跑步实时采集GPS坐标计算距离、配速、时长、卡路里。轨迹模块将采集到的经纬度点绘制到地图上用Google Maps或高德地图SDK实现。打卡与统计模块根据每日运动记录生成打卡日历统计周/月跑步里程、次数、总时长。数据存储模块使用Room数据库保存历史运动记录按日期、时长、距离等维度查询。这样拆完整个项目的代码组织就有了骨架。我在实际开发中特别强调一件事模块边界一定要清晰。很多新手喜欢在一个Activity里写完GPS监听、写数据库、画地图最后代码膨胀到几千行改一个bug崩三处。你拆成独立的类和管理器后面调试会轻松得多。1.2 技术选型为什么用Room ViewModel 前台服务技术选型这件事我吃过不少亏。早期做类似项目时图省事直接用SQLiteOpenHelper手搓数据库结果字段一多、查询一复杂代码简直没法看。这回我换成了Room理由很直接编译期SQL检查写错的SQL语句在编译阶段就会报错而不是等运行时才崩溃这能省下大量调试时间。与LiveData/Flow天然搭配数据库变化能自动通知UI刷新省去手动刷新列表的麻烦。代码量少DAO接口定义好基本CRUD就是几行注解的事。UI架构上我用了经典的MVVMActivity/Fragment只负责展示和交互业务逻辑放在ViewModel里数据层由Repository统一管理。GPS采集器单独封装成一个服务类这样运动过程中的状态管理和界面生命周期完全解耦。这里有一个特别关键的决策——运动过程中必须用前台服务Foreground Service。跑步App和普通App不一样用户很可能锁屏、切到别的应用甚至清掉后台任务。如果只是Activity里开个监听屏幕一关系统为了省电可能直接把你的进程杀掉GPS数据哗啦啦断掉一次跑步记录就废了。前台服务配合常驻通知栏可以极大降低被系统回收的概率这也是市面上所有运动类App的通用做法。所以我的结论是技术选型不追求酷炫只追求稳定和好维护。Room ViewModel 前台服务就是这个项目最踏实的组合。2. 核心模块的代码实现与关键技术细节2.1 GPS定位采集不只是拿个经纬度那么简单跑步打卡的灵魂是轨迹和距离而这两个都依赖高质量、高频率的GPS数据。我在项目里封装了一个LocationTracker类核心逻辑如下class LocationTracker( private val context: Context, private val callback: (Location) - Unit ) { private val fusedLocationClient: FusedLocationProviderClient LocationServices.getFusedLocationProviderClient(context) private val locationCallback object : LocationCallback() { override fun onLocationResult(locationResult: LocationResult) { locationResult.locations.forEach { location - callback(location) } } } fun startTracking() { val request LocationRequest.Builder( Priority.PRIORITY_HIGH_ACCURACY, 2000L // 每2秒获取一次位置 ).apply { setMinUpdateIntervalMillis(1000L) setMaxUpdateDelayMillis(5000L) }.build() if (checkPermission()) { fusedLocationClient.requestLocationUpdates( request, locationCallback, Looper.getMainLooper() ) } } fun stopTracking() { fusedLocationClient.removeLocationUpdates(locationCallback) } }这里有几个参数值得认真说更新频率我设为2秒一次。太频繁耗电严重太稀疏轨迹会飘。实测下来跑步场景下2秒一次足够画出平滑路线同时也不至于让手机热得像暖手宝。PRIORITY_HIGH_ACCURACY这个优先级会同时开启GPS和网络定位。在户外跑步场景中必须用这个只用网络定位的话轨迹能歪到隔壁小区去。最小更新间隔和最大延迟设置这些参数是为了在设备支持的情况下让定位服务有一定的灵活性避免系统无脑频繁回调平衡精度与功耗。采集到的所有坐标点我会同时做两个动作实时计算距离增量以及把点串起来等待绘制轨迹。2.2 距离与配速计算这里全是细节距离计算我选用Haversine公式而不是直接调用Location的distanceTo()——虽然系统提供了现成方法但如果你需要自己控制算法逻辑或者想把数据发给后端统一处理手写公式反而更灵活。核心代码fun calculateDistance(lat1: Double, lon1: Double, lat2: Double, lon2: Double): Float { val earthRadius 6371000.0 val dLat Math.toRadians(lat2 - lat1) val dLon Math.toRadians(lon2 - lon1) val a sin(dLat / 2) * sin(dLat / 2) cos(Math.toRadians(lat1)) * cos(Math.toRadians(lat2)) * sin(dLon / 2) * sin(dLon / 2) val c 2 * atan2(sqrt(a), sqrt(1 - a)) return (earthRadius * c).toFloat() }配速公式也很简单配速 运动耗时 / 运动距离单位是分钟每公里。举个例子跑了5.2公里耗时31分12秒配速就是31.2 / 5.2 6分钟/公里显示为600。但真正的坑在于精度处理。GPS信号在城市里会受到高楼、立交桥、天气等多种因素干扰经常会出现“跳点”——明明在直道上跑坐标突然歪到旁边建筑物上距离一下子多了好几十米。所以我在采集点入队之前加了一道过滤逻辑新点的速度如果超过某个阈值比如每秒20米也就是72公里/小时直接丢弃新点与上一个点的距离小于1米时忽略防止原地抖动累计误差如果用户在原地停留比如等红绿灯不继续累加距离。这些规则就是轨迹精准的“隐藏机关”。没有它们你会看到App记录的距离比实际多出20%用户跑完一看数据觉得不靠谱转身就卸载。2.3 前台服务与通知栏保活的正确姿势前台服务这块我踩过最大的坑是忘记处理Android 13API 33的通知权限。旧代码在低于API 33的版本上跑得好好的升级到新版本后服务一启动直接崩溃或者通知栏没有任何显示系统过一会儿就把进程回收了。正确的姿势分两步第一步在AndroidManifest.xml中声明权限uses-permission android:nameandroid.permission.FOREGROUND_SERVICE / uses-permission android:nameandroid.permission.FOREGROUND_SERVICE_LOCATION / uses-permission android:nameandroid.permission.POST_NOTIFICATIONS /第二步运行时动态申请通知权限针对API 33if (Build.VERSION.SDK_INT Build.VERSION_CODES.TIRAMISU) { val permission Manifest.permission.POST_NOTIFICATIONS if (ContextCompat.checkSelfPermission(this, permission) ! PackageManager.PERMISSION_GRANTED) { ActivityCompat.requestPermissions( this, arrayOf(permission), REQUEST_CODE_NOTIFICATION ) } }启动前台服务的代码核心部分长这样val channelId running_channel val channelName 跑步运动服务 if (Build.VERSION.SDK_INT Build.VERSION_CODES.O) { val channel NotificationChannel( channelId, channelName, NotificationManager.IMPORTANCE_LOW ) notificationManager.createNotificationChannel(channel) } val notification NotificationCompat.Builder(this, channelId) .setContentTitle(正在跑步打卡) .setContentText(当前配速${currentPace}) .setSmallIcon(R.drawable.ic_running) .setOngoing(true) .build() startForeground(RUNNING_SERVICE_ID, notification)注意这里设置setOngoing(true)让通知不可被用户手动滑动删除防止误触导致服务停止。同时通知栏实时刷新当前配速和距离这个小细节能让用户体验提升一大截。另一个重要心得在Android 14API 34上前台服务类型是强制的必须用ServiceInfo.FOREGROUND_SERVICE_TYPE_LOCATION或connected等具体类型。如果漏了启动服务时系统会直接抛ForegroundServiceStartNotAllowedException这个坑网上讨论很多但新手往往要撞一次才知道。3. 数据持久化与打卡逻辑的实现思路3.1 Room数据库设计与DAO层跑步记录需要持久化我设计了这样一张表Entity(tableName running_records) data class RunningRecord( PrimaryKey(autoGenerate true) val id: Long 0, val date: Long, // 开始日期时间戳 val duration: Long, // 运动时长毫秒 val distance: Float, // 距离米 val avgPace: String, // 平均配速如 605\ val calories: Int, // 消耗卡路里千卡 val trackPoints: String // 轨迹点JSON串 )这里trackPoints用JSON字符串存储是为了简化数据库表结构。如果后续要做轨迹回放直接解析这段JSON就能重新绘制路线不用再做多表关联查询。DAO层我写了几个常用查询接口Dao interface RunningRecordDao { Insert suspend fun insert(record: RunningRecord): Long Query(SELECT * FROM running_records WHERE date BETWEEN :startMillis AND :endMillis) suspend fun getRecordsBetween(startMillis: Long, endMillis: Long): ListRunningRecord Query(SELECT * FROM running_records ORDER BY date DESC LIMIT 1) suspend fun getLatestRecord(): RunningRecord? Query(SELECT COUNT(*) FROM running_records WHERE date BETWEEN :startMillis AND :endMillis) suspend fun getRecordCountBetween(startMillis: Long, endMillis: Long): Int Query(SELECT COALESCE(SUM(distance), 0) FROM running_records WHERE date BETWEEN :startMillis AND :endMillis) suspend fun getTotalDistanceBetween(startMillis: Long, endMillis: Long): Float }这里我特别推荐用suspend函数。Room对Kotlin协程的支持非常成熟用suspend修饰的DAO方法会自动放到IO线程执行不会卡UI线程。早期的回调式和RxJava式写法都麻烦现在新项目直接用协程才是正道。3.2 打卡状态如何判定打卡这件事核心逻辑很清晰当天是否有一次有效的跑步记录。但“有效”怎么定义我设了一个规则——单次跑步距离不低于1公里、时长不少于5分钟才视为一次有效打卡。这样能过滤掉那种“打开App跑了三分钟就关掉”的测试数据保持打卡记录的含金量。实现打卡日历的核心代码如下fun getMonthCheckInStatusList( year: Int, month: Int, records: ListRunningRecord ): ListBoolean { val calendar Calendar.getInstance() val daysInMonth calendar.getActualMaximum(Calendar.DAY_OF_MONTH) // 先按日期归组 val recordGroup records.groupBy { record - val c Calendar.getInstance().apply { timeInMillis record.date } c.get(Calendar.DAY_OF_MONTH) } return (1..daysInMonth).map { day - recordGroup[day]?.any { record - record.distance 1000 record.duration 5 * 60 * 1000 } ?: false } }这个List返回后RecyclerView的Adapter直接按天渲染打卡日为深色高亮未打卡为浅色背景连续打卡的连击数字在日历头部展示。连续打卡的统计也是个容易写bug的细节。我的做法是从今天往前遍历每一天遇到断档就停止计数。如果你“今天还没跑”那连续打卡不应该算今天失败需要特殊处理——判断昨天的状态是否满足满足则显示连续天数1因为今天正在进行中。这种边界处理不写测试真的容易翻车。3.3 轨迹保存与简单回放轨迹保存用JSON数组结构很简单[{lat:39.9042,lng:116.4074,time:1695000000}, ...]。保存之后我实现了两个功能一是跑步结束后展示本次轨迹二是在历史记录页面的详情里加载上次轨迹并绘制。高德地图SDK的绘制代码大致是这样的private fun drawTrackOnMap(points: ListLatLng) { val polyline PolylineOptions() .addAll(points) .width(16f) .color(ContextCompat.getColor(this, R.color.track_blue)) .geodesic(true) aMap.addPolyline(polyline) aMap.moveCamera( CameraUpdateFactory.newLatLngBounds( LatLngBounds.fromLatLngs(points), 120 ) ) }绘制本身不难难的是轨迹点太多导致卡顿。如果一次跑步记录采集了3000个点全部画上去地图操作会掉帧。我做了一个降采样处理每隔5个点取一个或者丢弃距离上一步小于2米的点。这样轨迹看起来依然平滑性能却好了很多。4. 权限管理、配置项与多版本适配4.1 运行时权限的完整申请流程安卓的定位权限有ACCESS_FINE_LOCATION精确定位和ACCESS_COARSE_LOCATION粗略定位两种。在API 31Android 12之后定位权限还和“大致位置”绑定不申请精确定位就只能拿到模糊位置跑步轨迹根本没法看。我在项目里写了一个统一的权限工具类PermissionUtils负责一次性请求一组相关权限fun requestRunningPermissions(activity: Activity) { val permissions mutableListOf( Manifest.permission.ACCESS_FINE_LOCATION, Manifest.permission.ACCESS_COARSE_LOCATION ) if (Build.VERSION.SDK_INT Build.VERSION_CODES.TIRAMISU) { permissions.add(Manifest.permission.POST_NOTIFICATIONS) } ActivityCompat.requestPermissions( activity, permissions.toTypedArray(), REQUEST_CODE_PERMISSIONS ) }申请的结果回调里我做了这样几个判断如果定位权限被拒绝直接提示“无法使用跑步功能”并引导去设置页手动开启。如果仅拒绝了通知权限则允许继续跑步但提醒“后台可能被系统回收”。如果用户勾选了“不再询问”就必须跳转到系统设置页让用户手动开启。权限这块代码不复杂但交互细节很影响用户体验。我的建议是不要一次性把所有权限堆在一起申请按需申请、分步引导用户反感度会低很多。4.2 Android 12 独有的“大致位置”选项Android 12引入了“大致位置”选项用户在权限弹窗里可以选择只提供近似位置。如果你的App没有适配系统会默认用户只能拿到模糊位置跑步轨迹变得一塌糊涂。适配方法是在Manifest里显式声明uses-permission android:nameandroid.permission.ACCESS_COARSE_LOCATION /然后在代码中用locationManager.isProviderEnabled(LocationManager.GPS_PROVIDER)或FusedLocation中的location.hasAccuracy()判断当前拿到的是不是精准位置。如果精度超过50米就给用户一个弱提示“当前定位精度较低请到开阔地带运动以保证轨迹准确”。这个小交互在很多商业App里都有自己实现起来也就多几行代码但对项目完整性来说是检验你是不是“只想交作业”的分水岭。4.3 屏幕常亮与电池优化跑步过程中用户一般会盯着界面或把手机放在臂包里。如果屏幕自动熄灭了UI上的配速、时长就看不到体验很糟糕。我在运动页加了一个简单的屏幕常亮window.addFlags(WindowManager.LayoutParams.FLAG_KEEP_SCREEN_ON)这个Flag在页面销毁时会自动移除比用WakeLock省心得多——WakeLock稍不注意就会忘记释放导致整晚耗电。另外为了省电我在运动开始前检测了电池优化白名单状态引导用户将本App加入“不受电池优化限制”的列表。这样系统在后台清理App时会“手下留情”。这个引导不是强制的用户跳过后App依然能跑但保活概率会降低。如实告知用户即可不要搞威胁式弹窗。5. 项目文档与源码规范决定你能不能“拿得出手”5.1 项目文档怎么组织才专业很多人的项目源码写得不错但一到写文档就拉胯。总目录三行文字“这是跑步App用了高德地图数据库用的Room。”这样交上去面试官扫一眼就扔一边了。我这次写了一份比较完整的项目文档包含这样几个章节项目背景与目标简单介绍项目解决什么问题、面向什么用户。技术栈与版本说明记录SDK版本、开发工具版本、依赖库版本——这个特别重要因为很多长期维护的项目升级一个依赖库可能引发连锁崩溃没有版本记录就无从排查。模块架构设计画出模块关系图说明每个模块的职责与依赖方向。核心功能实现说明针对运动录制、轨迹绘制、打卡统计这三个核心功能写清楚实现逻辑和关键算法。接口与常量定义列出重要常量如更新间隔、有效打卡阈值以及DAO接口。常见问题与调试方法记录开发过程中遇到的崩溃和解决方案。后续优化方向例如增加室内跑步模式、运动历史云同步、社交排行榜等。写文档的过程本质上是逼自己把代码想透的过程。很多逻辑你以为自己懂了真到了要用文字解释清楚的时候才发现有些地方经不起推敲。5.2 源码命名的规范与自检清单看一个安卓项目的地基先看包名和类名。我的项目包结构如下com.example.running ├── activity/ // 主界面、运动界面、历史界面 ├── adapter/ // RecyclerView适配器 ├── database/ // Room数据库相关Entity、Dao、Database ├── service/ // 前台运动服务 ├── location/ // GPS定位封装 ├── utils/ // 工具类权限、时间、距离计算 ├── viewmodel/ // ViewModel层 └── model/ // 数据模型类名尽量做到“见名知意”RunningRecord、LocationTracker、RecordDetailViewModel。方法名用动词开头startTracking()、calculateDistance()、buildNotification()。有两点我特别想强调避免过长的Activity。如果你发现MainActivity超过600行说明该拆了。把逻辑挪到ViewModel或工具类中Activity只做两件事绑定视图、响应事件。注释要写“为什么”而不是“是什么”。例如写// 过滤掉跳点防止距离虚增就比// 过滤跳点有价值得多。代码自己说明“是什么”注释负责解释“为什么这么做”。5.3 从源码到可展示的Demo这四件事不能省源码写完了文档也写完了并不代表项目就是“完成态”。我建议你务必亲自走一遍这四个流程才算真正交付Clean Rebuild确保没有残留的脏编译产物一键能跑起来。真机测试运动全流程模拟器只能验证UI逻辑定位轨迹必须在真机户外测试。我实测过同一套代码在模拟器和真机上的表现差异巨大——模拟器几乎拿不到稳定的GPS点。试一次后台切回与锁屏跑步途中切到微信回消息、锁屏10分钟再打开轨迹是否连续、服务是否还活着这个是保活机制的核心验证场景。数据清理与重复验证卸载App重新安装确认数据库重建和权限重新申请流程都正常。很多团队项目代码质量很高但就是“交付”这个环节粗糙。Demo演示到一半定位权限没弹出来、通知栏没显示、历史记录加载失败场面非常尴尬。提前走一遍流程这些问题都能提前暴露。6. 开发过程中频繁踩坑的三个问题排查实录6.1 问题一为什么我的轨迹断成了好几段这个现象我在测试中遇到好几次排查了很久。最终定位的根因是后台运行时定位回调被系统抑制。Android 8.0之后系统对后台定位有严格的限制——如果App处于后台定位更新频率会被大幅降低甚至完全停止。解决方案就是在运动开始后立即启动前台服务让App以“前台运行”的姿势继续接收定位更新。另外我还注意到部分国产手机厂商的系统对后台限制更激进即使有了前台服务也需要在用户认可的前提下引导用户将App加入“自启动白名单”。这个属于厂商层级的限制单纯靠代码很难完全绕开只能尽量引导和兼容。6.2 问题二计算出的距离比实际多了500米怎么回事排除掉GPS跳点后我发现还有一个隐蔽的坑坐标点排序乱序。LocationCallback的回调并不是严格按时间顺序送的偶尔会出现一个时间戳很旧但稍后才到达的点。如果直接拿它和最新的点计算距离等于在轨迹上画了一条无序的“时间穿越”线距离自然虚增。我的解决办法是在数据入队时增加一道判断新点的时间戳必须大于等于最后一个点的时间戳否则丢弃。这个判断只增加了一行代码但效果立竿见影。6.3 问题三通知栏权限申请后API 33以下的手机不弹通知这个问题的根源是版本条件判断写得不严谨。我想当然地以为目标SDK版本、手机系统版本和代码里的Build.VERSION.SDK_INT是同一个概念实际上Build.VERSION.SDK_INT只代表系统版本。在API 33以下的系统上POST_NOTIFICATIONS权限从未存在过也不需要在Manifest中声明。所以正确的写法是只在TIRAMISU以上的系统上动态申请通知权限低版本直接跳过。这个适配逻辑如果写错轻则多一个无意义的权限请求重则导致旧机型崩溃。排查这类问题我推荐一个方法分版本测试。不要只在最新的Pixel模拟器上跑一遍就算完用Android Studio的Device Manager创建几个不同API级别的虚拟设备把低版本如API 26、API 28和高版本如API 34都过一遍主流程很多兼容性问题就会无处遁形。7. 进阶方向这个项目还能怎么扩展跑步打卡项目做到这个程度已经是一个“完整闭环”的个人项目了。但如果想再往上走我总结了几条可以落地的扩展方向。接入运动健康平台比如接入Google Fit或华为Health Kit同步步数、心率和睡眠数据能极大提升数据的丰富度和可玩性。增加运动计划与目标用户设定每周跑步里程目标后App自动在打卡页显示进度条和预估完成时间形成更强的任务感。室内跑步模式在没有GPS的室内场景下用手机加速度计估算步频再结合身高体重推算距离。这个估算算法的调优空间很大很适合作为算法研究的切入点。云端同步与社交排行接入后端服务把运动记录同步到云端支持好友排行榜或加入跑团。这一块能延伸出账号体系、鉴权、数据加密等多个后端方向。我个人的经验是做项目不要贪多先把一个闭环做扎实再逐步扩展。跑步打卡看似小但牵扯到定位、地图、数据库、多线程、生命周期、通知体系、版本适配几乎覆盖了安卓客户端开发最核心的知识面。把一个项目吃透比稀里糊涂刷十个半成品Demo强太多。最后再分享一个小建议。如果你打算把这个项目写进简历不要只写“开发了跑步打卡App”而要写清楚“独立完成运动记录模块通过前台服务与GPS过滤机制实现轨迹连续性与距离精度优化数据库层使用Room实现运动记录的持久化与周月统计”。一句话里同时体现了功能、技术点和结果面试官看到才会有继续问下去的兴趣。