简介基于安卓的景点导游毕业设计源码包面向高校计算机相关专业学生与安卓开发入门者帮助解决毕业设计选题与落地问题。客户端完整实现用户注册登录、景点上报、景点浏览、评论购票及在线沟通、景点推荐、我的订单、个人信息与密码修改等功能后台采用Java实现管理员端支持用户信息、景点信息、订单信息的查看与管理。压缩包为RAR格式体积约87.85MB文件总数未在详情中单独列出内容以安卓客户端和Java后台管理端的源码、配置文件及说明文档为主。已有311人学习适合作为毕设项目参考或安卓开发练手素材。通过这份资源读者可掌握安卓网络请求、数据存储、列表展示与后台交互等关键实现并基于完整的业务模块进行二次开发与功能扩展。1. Android 景点导游毕业设计别等到答辩才发现跑不起来屏幕前摆着“毕业设计源码-基于Android的景点导游”这个名字时大多数人下载解压、导入 Android Studio、等 Gradle 转完第一圈然后模拟器上白屏或崩溃——这才是拿到这份源码的真实起点。所谓景点导游不是给你一个装好的 App而是一个空的 Android 工程骨架地图要接入 SDK定位要申请权限景点数据要么写在本地要么现拉现用路线规划还得盯着高德地图的调用配额。这篇文章就把这套东西怎么落地讲清楚从地图 SDK 与数据源选型到工程搭建、POI 加载和路线绘制最后收在 adb 连真机排错与打包验证这些最容易翻车的细节上。它面向两类人准备拿它交毕业设计的学生以及想快速把 LBS 能力塞进自己项目的在职工程师。2. Android 景点导游怎么选型地图 SDK、数据来源与工程分层先定地图引擎。这个项目最重的第三方依赖就是地图国内可选空间其实很小主流就是高德地图 SDK 和百度地图 SDK我做技术选型时一般从下表的几个维度去卡对比项高德地图 SDK百度地图 SDKKey 申请控制台按包名签名指纹下发调试与发布各自独立同样按包名AK 绑定区分调试环境定位能力高德定位完全内置基站GPSWi-Fi 融合定位定位需额外集成百度定位组件多一层依赖路线规划步行、骑行、驾车接口齐全文档有现成 Demo接口类似但步行路线返回质量略粗糙包体积影响全量功能约 10MB可用 ABI 过滤裁剪全量更大需要同时裁 so 和资源社区活跃度毕业设计相关代码片段最多抄作业容易社区也有但搜索到的解法往往更旧我一般会选高德核心理由是“少一个依赖”。百度地图的定位能力不在主 SDK 里要多引一个定位包对只需要在学校周边几个景点做演示的毕业场景来说每多一个依赖答辩预演就多一个出问题的环节。顺着这个思路往下下一个要拍板的不是 UI 框架而是数据从哪来。2.1 景点数据不依赖服务器用本地 JSON 也能把架构讲圆毕业设计通常没有专职后端强行上 Spring Boot 反而增加部署风险。最常见的做法是把景点数据放在app/src/main/assets/spots.json中结构类似这样{ campus: { name: 东湖校区, center: [114.4155, 30.5255] }, spots: [ { id: s001, name: 樱花大道, latitude: 30.5261, longitude: 114.4168, description: 每年三月底盛花期全长约八百米, audioUrl: assets://audio/s001.mp3, tags: [花景, 拍照] } ] }数据格式定好之后代码里用 Gson 解析注意流要指定 UTF-8不然在 Windows 上编辑过的中文注释会直接乱码AssetManager am context.getAssets(); InputStream is am.open(spots.json); ListSpot spots new Gson().fromJson( new InputStreamReader(is, StandardCharsets.UTF_8), new TypeTokenListSpot() {}.getType());为什么不用后端一是答辩现场经常没有网络数据放 assets 里断网也能演示二是评审问“数据从哪来”你可以说当前版本走本地缓存同时补一句“网络层已预留 Retrofit 入口”这一句话就能把架构完整度拉起来。只把 Retrofit 依赖加好、Service 接口定义好业务代码不动等真有后端时切换数据源即可。把选型落进工程的方式就是直接敲进app/build.gradleimplementation com.amap.api:3dmap:latest.integration implementation com.amap.api:location:latest.integration implementation com.google.android.material:material:1.9.0 implementation androidx.constraintlayout:constraintlayout:2.1.4注意高德的 3dmap 和 location 要分两行声明写在同一行虽然不报错但后续单独升级定位 SDK 时容易互相覆盖。compileSdk 建议和 Android Studio 当前推荐的 targetSdk 对齐否则部分新接口会自动走兼容路径定位回调的字段会有细微差异。2.2 包结构分层决定你答辩时能不能说清楚代码我见过不少源码包把 Activity 全部堆在一个包下几百行一个文件评审问“代码结构”时只能支支吾吾。推荐按职责分五层com.example.guide ├── data // 本地 JSON 解析、Repository │ ├── model // Spot、Route、UserLocation │ └── source // SpotsRepository、JsonSource ├── map // 地图 Activity、定位回调、Marker 工具类 ├── ui // 景点列表 Fragment、详情 BottomSheet、Banner 适配器 ├── nav // 路线规划入口步行/骑行参数封装 └── utils // 经纬度距离计算、格式化工具分层意义不是代码洁癖而是把“导游”业务和“地图 SDK”解耦。MapActivity 只负责地图生命周期和 Marker 点击景点列表由 Fragment 自己加载数据两者通过一个SpotDetailBottomSheet通信。这样即使地图 SDK 升级后某个类被标记为 deprecated你只改 map 包数据层完全不受影响。配套的 Repository 也不复杂class SpotsRepository(private val context: Context) { fun loadFromAssets(): ListSpot { return JsonSource(context).load(spots.json) } }2.3 用 MVVM 还是 MVC对导游项目来说哪个更稳这种量级的项目我推荐用 MVVM而且直接用官方推荐的 ViewModel LiveData 组合。原因很具体模拟器旋转屏幕时Activity 会重建如果用 MVC 在 Activity 里直接解析 JSON转一次屏就读一次 assetsMVVM 让SpotsViewModel持有数据旋转后直接复用列表不闪烁。代码骨架class SpotsViewModel(application: Application) : AndroidViewModel(application) { private val repo SpotsRepository(application) val spots: LiveDataListSpot liveData { emit(repo.loadFromAssets()) } val selectedSpot MutableLiveDataSpot() fun onMarkerClick(spot: Spot) { selectedSpot.value spot } }提示ViewModel 里不要持有 MapView 或 Fragment 引用否则退出页面后内存泄漏。所有地图操作都放到 Activity 层用observe接收 LiveData 回调后再执行。写这块时顺手把 Kotlin 作为主力语言Android Studio 新建项目默认就是 Kotlin遇到问题你搜索到的攻略也基本是 Kotlin 片段抄作业成本最低。2.4 MapView 生命周期是整个地图模块的地基接入任何地图业务之前先把MapView的五个生命周期方法写成模板override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) mapView.onCreate(savedInstanceState) } override fun onResume() { super.onResume() mapView.onResume() } override fun onPause() { super.onPause() mapView.onPause() } override fun onDestroy() { super.onDestroy() mapView.onDestroy() }漏掉任何一个轻则地图黑屏重则内存泄漏而且日志只报GLSurfaceView相关异常很容易误导你去查 OpenGL 而不是生命周期。这五个方法的调用顺序不能调整onCreate里拿到aMap对象后先做初始配置再谈定位和 Marker。3. Android 景点导游工程搭建Gradle 校准、权限与主界面骨架这一章解决“工程能编译”到“骨架能跑”之间的问题。很多源码下载下来编译失败多半不是代码问题而是环境漂移Gradle 版本、JDK 版本、compileSdk 三者对不上。3.1 Android Studio、SDK 与 JDK 的前置校准Android Studio 本身安装不难难的是装完后 SDK 组件下载不动。国内网络下经常卡在 0%处理方式是在 Settings → SDK Location 里指定本地 SDK 路径并确保Android SDK Platform-Tools已勾选。这个目录里包含 adb 和 fastboot后面连小米真机调试时全靠它。建议的工程参数基准如下配置项推荐值理由compileSdk34追平新版本 androidx 编译要求minSdk24覆盖 Android 7.0高德 SDK 完全支持targetSdk34满足应用市场要求答辩演示不受影响JDK17随 Studio 自带Kotlin 与高德 SDK 均兼容Gradlewrapper 内置版本不要手动升级大版本容易触发兼容问题align 好之后app/build.gradle里的 defaultConfig 典型长这样android { compileSdk 34 defaultConfig { applicationId com.example.guide minSdk 24 targetSdk 34 versionCode 1 versionName 1.0 ndk { abiFilters armeabi-v7a, arm64-v8a } } }3.1.1 用 gradle 获取 SHA1比命令行省事申请高德 Key 必须用到 SHA1用 Gradle 自带任务查看cd android ./gradlew signingReportsigningReport会把 debug 与 release 变体的 SHA1、MD5、SHA256 全部打印出来。注意applicationId必须和高德控制台填写的包名一致很多同学改包名后 Key 失效不是 Key 错了而是包名变更导致签名指纹不匹配。高德把 Key 与“包名SHA1”绑定任何一项变化都要重新申请。3.2 AndroidManifest 权限与 Key 配置缺一项定位就废景点导游离不开定位权限最低权限集合是uses-permission android:nameandroid.permission.ACCESS_COARSE_LOCATION / uses-permission android:nameandroid.permission.ACCESS_FINE_LOCATION / uses-permission android:nameandroid.permission.INTERNET / uses-permission android:nameandroid.permission.ACCESS_NETWORK_STATE / uses-permission android:nameandroid.permission.ACCESS_WIFI_STATE / uses-permission android:nameandroid.permission.WRITE_EXTERNAL_STORAGE android:maxSdkVersion29 /然后在application标签内加高德 Keymeta-data android:namecom.amap.api.v2.apikey android:value你的高德Key /注意WRITE_EXTERNAL_STORAGE从 Android 10 开始被系统忽略但高德在写入定位缓存时仍会尝试读取保留声明但限制maxSdkVersion29可以避免 targetSdk 升级时的 lint 警告。Android 6.0 以上光声明权限不够还得动态请求。用 Activity Result API 比老式onRequestPermissionsResult简洁得多private val requestLocation registerForActivityResult(ActivityResultContracts.RequestMultiplePermissions()) { if (it[Manifest.permission.ACCESS_FINE_LOCATION] true) { startLocation() } else { Toast.makeText(this, 需要定位权限才能开展导游功能, Toast.LENGTH_LONG).show() } }动态权限不是形式主义用户第一次打开 App 时拒绝定位后续所有“基于当前位置的景点距离排序”都会失效所以要在用户点击“开始导游”时二次触发请求。3.3 底部导航 协调布局搭出景点与地图的切换骨架导游 App 的常规骨架是三个 tab景点、地图、我的。底部导航用BottomNavigationView中间用FragmentContainerView承载避免复杂的 Fragment 替换androidx.fragment.app.FragmentContainerView android:idid/fragment_container android:layout_widthmatch_parent android:layout_heightmatch_parent / com.google.android.material.bottomnavigation.BottomNavigationView android:idid/bottom_nav android:layout_widthmatch_parent android:layout_heightwrap_content android:layout_gravitybottom app:menumenu/bottom_nav_menu /菜单资源如下menu item android:idid/nav_list android:icondrawable/ic_list android:title景点 / item android:idid/nav_map android:icondrawable/ic_map android:title地图 / item android:idid/nav_profile android:icondrawable/ic_profile android:title我的 / /menu景点列表页推荐用CoordinatorLayout嵌套CollapsingToolbarLayout加RecyclerView列表下拉时顶部景点 Banner 收起、标题吸顶交互接近旅游 App 的详情页androidx.coordinatorlayout.widget.CoordinatorLayout com.google.android.material.appbar.AppBarLayout com.google.android.material.appbar.CollapsingToolbarLayout BannerView android:idid/banner / androidx.appcompat.widget.Toolbar ... / /CollapsingToolbarLayout /AppBarLayout androidx.recyclerview.widget.RecyclerView app:layout_behaviorstring/appbar_scrolling_view_behavior / /androidx.coordinatorlayout.widget.CoordinatorLayout这里的appbar_scrolling_view_behavior是系统内置值不要手改成自定义字符串否则 RecyclerView 会被 AppBar 盖住。Banner 轮播用 ViewPager2 加一个 Handler 定时切页二十行代码量级不引第三方库也能跑通。骨架搭完下一步就是把核心业务——地图、定位与景点展示——接进来。4. 核心功能实战定位、POI 加载、路线规划与列表联动这一章把地图真正的业务逻辑串起来。先看定位导游场景下定位是数据的锚点没有坐标景点距离和路线规划全部失去意义。4.1 高德定位回调与坐标参数直接决定演示效果val locationClient AMapLocationClient(this).apply { setLocationListener { loc - if (loc.errorCode 0) { currentLat loc.latitude currentLng loc.longitude aMap.moveCamera( CameraUpdateFactory.newLatLngZoom( LatLng(loc.latitude, loc.longitude), 16f ) ) } else { Log.e(Loc, location error: ${loc.errorCode}, ${loc.errorInfo}) } } } val option AMapLocationClientOption().apply { interval 5000 isNeedAddress true isOnceLocation false } locationClient.setLocationOption(option) locationClient.startLocation()interval是主动上报间隔不是 GPS 点收集间隔5 秒适合步行导游场景如果只打算在进入景区时定一次位把isOnceLocation设为 true 会省不少电。isNeedAddress开启后能在loc.getAddress()拿到文字地址列表页可以直接展示“武汉市东湖新技术开发区”这样的信息不用自己调逆地理编码接口。4.2 景点 POI 的 Marker 展示与点击别用 title 查对象解析完 JSON 后第一步不是直接aMap.addMarker而是维护一个 Marker 列表便于统一清理和刷新private val markers mutableListOfMarker() fun showSpots(spots: ListSpot) { markers.forEach { it.remove() } markers.clear() spots.forEach { spot - val marker aMap.addMarker( MarkerOptions() .position(LatLng(spot.latitude, spot.longitude)) .title(spot.name) .snippet(spot.description) .icon(BitmapDescriptorFactory.fromView(buildIcon(spot))) ) marker.obj spot markers.add(marker) } }marker.obj spot是高频写法比点击时遍历 Marker 集合按 title 查找效率高得多。点击回调里做两件事把 Marker 设为选中态并弹出详情卡片aMap.setOnMarkerClickListener { marker - val spot marker.obj as? Spot ?: returnsetOnMarkerClickListener false marker.showInfoWindow() binding.spotDetailBottomSheet.showSpot(spot) true }提示列表页和地图联动时点击列表项要走同一套逻辑。我的做法是让 Fragment 把 Spot 发给共享 ViewModelMapActivity 观察后调moveCamera并高亮对应 Marker避免两套重复代码维护两个状态源。4.3 路线规划从“看地图”升级成“带路”景点导游最有“干货感”的功能是点击详情页的“去这里”后绘制一条步行路线val routeSearch RouteSearch(this) val query RouteSearch.WalkRouteQuery( RouteSearch.FromAndTo( LatLng(currentLat, currentLng), LatLng(spot.latitude, spot.longitude) ), RouteSearch.WALK_DEFAULT ) routeSearch.calculateWalkRouteAsyn(query) routeSearch.setRouteSearchListener(object : RouteSearch.OnRouteSearchListener { override fun onWalkRouteSearched(result: RouteSearch.WalkRouteResult?, code: Int) { if (code ! 1000 || result?.paths.isNullOrEmpty()) return val walkPath result.paths[0] val list walkPath.steps.flatMap { it.polyline.map { p - LatLng(p.latitude, p.longitude) } } aMap.addPolyline( PolylineOptions() .addAll(list) .width(14f) .color(Color.parseColor(#1E88E5)) ) } })这里的坑在于步行路径是分 step 返回的如果直接拿result.paths[0]的坐标集合去画线会出现断线。上面用flatMap把每个 step 的 polyline 压平拼接成完整坐标链这是路线绘制最容易出错的地方。code ! 1000时九成原因是高德控制台没有给这个 Key 开通“路线规划”服务需要单独申请。4.4 景点列表加载进度条放对位置比样式重要加载 assets 里的 JSON 本身很快但景点语音包和图片在真机上首次读取会有卡顿列表无反馈会显得很“死”。加一个 Material 的CircularProgressIndicatorbinding.progressIndicator.visibility View.VISIBLE viewModel.spots.observe(viewLifecycleOwner) { result - binding.progressIndicator.visibility View.GONE binding.recyclerView.adapter SpotAdapter(result) }进度条放在ConstraintLayout中间位置数据到了就隐藏。除了加载态还要处理一个错误态JSON 解析失败时显示“加载失败重试按钮”而不是白屏。这个兜底在答辩演示时尤其重要机器临时抽风也是评审考察的一部分。4.5 列表与地图联动用最小粒度刷新避免掉帧联动时不要每次点击都重建整个 Adapter而是定位下标后局部刷新fun setSelectedSpot(spotId: String) { val index spots.indexOfFirst { it.id spotId } lastSelected?.let { notifyItemChanged(it) } notifyItemChanged(index) lastSelected index }细节Marker 点击回调在主线程moveCamera动画期间如果同步滚动列表会掉帧。我一般不做scrollToPosition只刷新选中状态用户视觉焦点已经在地图上列表停留在原位反而更自然。地图动画结束后再刷新列表选中态是体感最好的顺序。5. Android 景点导游打包验证混淆、签名与 adb 连真机排错最后一章收在验证环节。这里必须提前做一件事把 release 签名配好不要拿 debug 包去答辩。高德 Key 区分 debug 与 release两者签名指纹不一样你在控制台只申请了 debug Key发布包跑起来定位就会静默失败。用 release 之前先跑一遍./gradlew signingReport拿到发布变体的 SHA1到高德控制台补一个 Key。5.1 用 adb 连小米真机先查这三个位置很多同学开完“USB 调试”后发现adb devices列表还是空的第一反应是换线。排查顺序应该是先adb kill-server adb start-server再看手机上有没有授权弹窗最后查 USB 模式是不是“仅充电”。小米设备要额外打开“USB 安装”和“USB 调试安全设置”连接后常用命令adb devices adb shell dumpsys package com.example.guide第二条命令能确认当前安装包的签名信息、权限列表和目标 SDK比在设置里翻半天可靠。网上有些帖子会教你执行adb shell sh /storage/.../up.sh之类的脚本那是给特定模块用的不是通用操作遇到问题先看adb devices的输出状态是device还是unauthorized。5.2 定位失败现场先看 errorCode 再动代码高德定位失败时回调里的errorCode直接指向问题方向errorCode含义处理方式4Key 不正确或不存在核对包名与 SHA1重新生成 Key7签名验证失败确认 release 包使用独立 keystore重新签名12缺少定位权限检查动态权限是否真正勾选而不是只在 Manifest 声明遇到 7 的典型路径改过包名、换过电脑、或重新生成过 keystore 但忘记更新高德控制台。处理完 Key 后不要只点 Run要卸载旧包重装否则系统缓存里还是旧签名数据。5.3 混淆配置保住数据模型和高德 SDK打 release 包时要保活高德 SDK 和 Gson 要反射的数据模型-keep class com.amap.api.**{*;} -keep class com.autonavi.**{*;} -keep class com.example.guide.data.model.**{*;} -keepclassmembers class ** { android.webkit.JavascriptInterface methods; }data.model必须 keep原因很直接Gson 通过反射按字段名赋值混淆后Spot的latitude变成aJSON 解析出来的对象全为空。验证方式打 release 包后完整走一遍“景点列表 → 地图定位 → 路线规划”主链路再用adb shell dumpsys package核对安装包名与密钥配置。模拟器上定位不准是正常的但 API 调用链通不通、Marker 有没有加载、路线有没有画出一看便知。本文还有配套的精品资源点击获取
Android景点导游开发实践：高德地图SDK集成与定位路线规划
简介基于安卓的景点导游毕业设计源码包面向高校计算机相关专业学生与安卓开发入门者帮助解决毕业设计选题与落地问题。客户端完整实现用户注册登录、景点上报、景点浏览、评论购票及在线沟通、景点推荐、我的订单、个人信息与密码修改等功能后台采用Java实现管理员端支持用户信息、景点信息、订单信息的查看与管理。压缩包为RAR格式体积约87.85MB文件总数未在详情中单独列出内容以安卓客户端和Java后台管理端的源码、配置文件及说明文档为主。已有311人学习适合作为毕设项目参考或安卓开发练手素材。通过这份资源读者可掌握安卓网络请求、数据存储、列表展示与后台交互等关键实现并基于完整的业务模块进行二次开发与功能扩展。1. Android 景点导游毕业设计别等到答辩才发现跑不起来屏幕前摆着“毕业设计源码-基于Android的景点导游”这个名字时大多数人下载解压、导入 Android Studio、等 Gradle 转完第一圈然后模拟器上白屏或崩溃——这才是拿到这份源码的真实起点。所谓景点导游不是给你一个装好的 App而是一个空的 Android 工程骨架地图要接入 SDK定位要申请权限景点数据要么写在本地要么现拉现用路线规划还得盯着高德地图的调用配额。这篇文章就把这套东西怎么落地讲清楚从地图 SDK 与数据源选型到工程搭建、POI 加载和路线绘制最后收在 adb 连真机排错与打包验证这些最容易翻车的细节上。它面向两类人准备拿它交毕业设计的学生以及想快速把 LBS 能力塞进自己项目的在职工程师。2. Android 景点导游怎么选型地图 SDK、数据来源与工程分层先定地图引擎。这个项目最重的第三方依赖就是地图国内可选空间其实很小主流就是高德地图 SDK 和百度地图 SDK我做技术选型时一般从下表的几个维度去卡对比项高德地图 SDK百度地图 SDKKey 申请控制台按包名签名指纹下发调试与发布各自独立同样按包名AK 绑定区分调试环境定位能力高德定位完全内置基站GPSWi-Fi 融合定位定位需额外集成百度定位组件多一层依赖路线规划步行、骑行、驾车接口齐全文档有现成 Demo接口类似但步行路线返回质量略粗糙包体积影响全量功能约 10MB可用 ABI 过滤裁剪全量更大需要同时裁 so 和资源社区活跃度毕业设计相关代码片段最多抄作业容易社区也有但搜索到的解法往往更旧我一般会选高德核心理由是“少一个依赖”。百度地图的定位能力不在主 SDK 里要多引一个定位包对只需要在学校周边几个景点做演示的毕业场景来说每多一个依赖答辩预演就多一个出问题的环节。顺着这个思路往下下一个要拍板的不是 UI 框架而是数据从哪来。2.1 景点数据不依赖服务器用本地 JSON 也能把架构讲圆毕业设计通常没有专职后端强行上 Spring Boot 反而增加部署风险。最常见的做法是把景点数据放在app/src/main/assets/spots.json中结构类似这样{ campus: { name: 东湖校区, center: [114.4155, 30.5255] }, spots: [ { id: s001, name: 樱花大道, latitude: 30.5261, longitude: 114.4168, description: 每年三月底盛花期全长约八百米, audioUrl: assets://audio/s001.mp3, tags: [花景, 拍照] } ] }数据格式定好之后代码里用 Gson 解析注意流要指定 UTF-8不然在 Windows 上编辑过的中文注释会直接乱码AssetManager am context.getAssets(); InputStream is am.open(spots.json); ListSpot spots new Gson().fromJson( new InputStreamReader(is, StandardCharsets.UTF_8), new TypeTokenListSpot() {}.getType());为什么不用后端一是答辩现场经常没有网络数据放 assets 里断网也能演示二是评审问“数据从哪来”你可以说当前版本走本地缓存同时补一句“网络层已预留 Retrofit 入口”这一句话就能把架构完整度拉起来。只把 Retrofit 依赖加好、Service 接口定义好业务代码不动等真有后端时切换数据源即可。把选型落进工程的方式就是直接敲进app/build.gradleimplementation com.amap.api:3dmap:latest.integration implementation com.amap.api:location:latest.integration implementation com.google.android.material:material:1.9.0 implementation androidx.constraintlayout:constraintlayout:2.1.4注意高德的 3dmap 和 location 要分两行声明写在同一行虽然不报错但后续单独升级定位 SDK 时容易互相覆盖。compileSdk 建议和 Android Studio 当前推荐的 targetSdk 对齐否则部分新接口会自动走兼容路径定位回调的字段会有细微差异。2.2 包结构分层决定你答辩时能不能说清楚代码我见过不少源码包把 Activity 全部堆在一个包下几百行一个文件评审问“代码结构”时只能支支吾吾。推荐按职责分五层com.example.guide ├── data // 本地 JSON 解析、Repository │ ├── model // Spot、Route、UserLocation │ └── source // SpotsRepository、JsonSource ├── map // 地图 Activity、定位回调、Marker 工具类 ├── ui // 景点列表 Fragment、详情 BottomSheet、Banner 适配器 ├── nav // 路线规划入口步行/骑行参数封装 └── utils // 经纬度距离计算、格式化工具分层意义不是代码洁癖而是把“导游”业务和“地图 SDK”解耦。MapActivity 只负责地图生命周期和 Marker 点击景点列表由 Fragment 自己加载数据两者通过一个SpotDetailBottomSheet通信。这样即使地图 SDK 升级后某个类被标记为 deprecated你只改 map 包数据层完全不受影响。配套的 Repository 也不复杂class SpotsRepository(private val context: Context) { fun loadFromAssets(): ListSpot { return JsonSource(context).load(spots.json) } }2.3 用 MVVM 还是 MVC对导游项目来说哪个更稳这种量级的项目我推荐用 MVVM而且直接用官方推荐的 ViewModel LiveData 组合。原因很具体模拟器旋转屏幕时Activity 会重建如果用 MVC 在 Activity 里直接解析 JSON转一次屏就读一次 assetsMVVM 让SpotsViewModel持有数据旋转后直接复用列表不闪烁。代码骨架class SpotsViewModel(application: Application) : AndroidViewModel(application) { private val repo SpotsRepository(application) val spots: LiveDataListSpot liveData { emit(repo.loadFromAssets()) } val selectedSpot MutableLiveDataSpot() fun onMarkerClick(spot: Spot) { selectedSpot.value spot } }提示ViewModel 里不要持有 MapView 或 Fragment 引用否则退出页面后内存泄漏。所有地图操作都放到 Activity 层用observe接收 LiveData 回调后再执行。写这块时顺手把 Kotlin 作为主力语言Android Studio 新建项目默认就是 Kotlin遇到问题你搜索到的攻略也基本是 Kotlin 片段抄作业成本最低。2.4 MapView 生命周期是整个地图模块的地基接入任何地图业务之前先把MapView的五个生命周期方法写成模板override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) mapView.onCreate(savedInstanceState) } override fun onResume() { super.onResume() mapView.onResume() } override fun onPause() { super.onPause() mapView.onPause() } override fun onDestroy() { super.onDestroy() mapView.onDestroy() }漏掉任何一个轻则地图黑屏重则内存泄漏而且日志只报GLSurfaceView相关异常很容易误导你去查 OpenGL 而不是生命周期。这五个方法的调用顺序不能调整onCreate里拿到aMap对象后先做初始配置再谈定位和 Marker。3. Android 景点导游工程搭建Gradle 校准、权限与主界面骨架这一章解决“工程能编译”到“骨架能跑”之间的问题。很多源码下载下来编译失败多半不是代码问题而是环境漂移Gradle 版本、JDK 版本、compileSdk 三者对不上。3.1 Android Studio、SDK 与 JDK 的前置校准Android Studio 本身安装不难难的是装完后 SDK 组件下载不动。国内网络下经常卡在 0%处理方式是在 Settings → SDK Location 里指定本地 SDK 路径并确保Android SDK Platform-Tools已勾选。这个目录里包含 adb 和 fastboot后面连小米真机调试时全靠它。建议的工程参数基准如下配置项推荐值理由compileSdk34追平新版本 androidx 编译要求minSdk24覆盖 Android 7.0高德 SDK 完全支持targetSdk34满足应用市场要求答辩演示不受影响JDK17随 Studio 自带Kotlin 与高德 SDK 均兼容Gradlewrapper 内置版本不要手动升级大版本容易触发兼容问题align 好之后app/build.gradle里的 defaultConfig 典型长这样android { compileSdk 34 defaultConfig { applicationId com.example.guide minSdk 24 targetSdk 34 versionCode 1 versionName 1.0 ndk { abiFilters armeabi-v7a, arm64-v8a } } }3.1.1 用 gradle 获取 SHA1比命令行省事申请高德 Key 必须用到 SHA1用 Gradle 自带任务查看cd android ./gradlew signingReportsigningReport会把 debug 与 release 变体的 SHA1、MD5、SHA256 全部打印出来。注意applicationId必须和高德控制台填写的包名一致很多同学改包名后 Key 失效不是 Key 错了而是包名变更导致签名指纹不匹配。高德把 Key 与“包名SHA1”绑定任何一项变化都要重新申请。3.2 AndroidManifest 权限与 Key 配置缺一项定位就废景点导游离不开定位权限最低权限集合是uses-permission android:nameandroid.permission.ACCESS_COARSE_LOCATION / uses-permission android:nameandroid.permission.ACCESS_FINE_LOCATION / uses-permission android:nameandroid.permission.INTERNET / uses-permission android:nameandroid.permission.ACCESS_NETWORK_STATE / uses-permission android:nameandroid.permission.ACCESS_WIFI_STATE / uses-permission android:nameandroid.permission.WRITE_EXTERNAL_STORAGE android:maxSdkVersion29 /然后在application标签内加高德 Keymeta-data android:namecom.amap.api.v2.apikey android:value你的高德Key /注意WRITE_EXTERNAL_STORAGE从 Android 10 开始被系统忽略但高德在写入定位缓存时仍会尝试读取保留声明但限制maxSdkVersion29可以避免 targetSdk 升级时的 lint 警告。Android 6.0 以上光声明权限不够还得动态请求。用 Activity Result API 比老式onRequestPermissionsResult简洁得多private val requestLocation registerForActivityResult(ActivityResultContracts.RequestMultiplePermissions()) { if (it[Manifest.permission.ACCESS_FINE_LOCATION] true) { startLocation() } else { Toast.makeText(this, 需要定位权限才能开展导游功能, Toast.LENGTH_LONG).show() } }动态权限不是形式主义用户第一次打开 App 时拒绝定位后续所有“基于当前位置的景点距离排序”都会失效所以要在用户点击“开始导游”时二次触发请求。3.3 底部导航 协调布局搭出景点与地图的切换骨架导游 App 的常规骨架是三个 tab景点、地图、我的。底部导航用BottomNavigationView中间用FragmentContainerView承载避免复杂的 Fragment 替换androidx.fragment.app.FragmentContainerView android:idid/fragment_container android:layout_widthmatch_parent android:layout_heightmatch_parent / com.google.android.material.bottomnavigation.BottomNavigationView android:idid/bottom_nav android:layout_widthmatch_parent android:layout_heightwrap_content android:layout_gravitybottom app:menumenu/bottom_nav_menu /菜单资源如下menu item android:idid/nav_list android:icondrawable/ic_list android:title景点 / item android:idid/nav_map android:icondrawable/ic_map android:title地图 / item android:idid/nav_profile android:icondrawable/ic_profile android:title我的 / /menu景点列表页推荐用CoordinatorLayout嵌套CollapsingToolbarLayout加RecyclerView列表下拉时顶部景点 Banner 收起、标题吸顶交互接近旅游 App 的详情页androidx.coordinatorlayout.widget.CoordinatorLayout com.google.android.material.appbar.AppBarLayout com.google.android.material.appbar.CollapsingToolbarLayout BannerView android:idid/banner / androidx.appcompat.widget.Toolbar ... / /CollapsingToolbarLayout /AppBarLayout androidx.recyclerview.widget.RecyclerView app:layout_behaviorstring/appbar_scrolling_view_behavior / /androidx.coordinatorlayout.widget.CoordinatorLayout这里的appbar_scrolling_view_behavior是系统内置值不要手改成自定义字符串否则 RecyclerView 会被 AppBar 盖住。Banner 轮播用 ViewPager2 加一个 Handler 定时切页二十行代码量级不引第三方库也能跑通。骨架搭完下一步就是把核心业务——地图、定位与景点展示——接进来。4. 核心功能实战定位、POI 加载、路线规划与列表联动这一章把地图真正的业务逻辑串起来。先看定位导游场景下定位是数据的锚点没有坐标景点距离和路线规划全部失去意义。4.1 高德定位回调与坐标参数直接决定演示效果val locationClient AMapLocationClient(this).apply { setLocationListener { loc - if (loc.errorCode 0) { currentLat loc.latitude currentLng loc.longitude aMap.moveCamera( CameraUpdateFactory.newLatLngZoom( LatLng(loc.latitude, loc.longitude), 16f ) ) } else { Log.e(Loc, location error: ${loc.errorCode}, ${loc.errorInfo}) } } } val option AMapLocationClientOption().apply { interval 5000 isNeedAddress true isOnceLocation false } locationClient.setLocationOption(option) locationClient.startLocation()interval是主动上报间隔不是 GPS 点收集间隔5 秒适合步行导游场景如果只打算在进入景区时定一次位把isOnceLocation设为 true 会省不少电。isNeedAddress开启后能在loc.getAddress()拿到文字地址列表页可以直接展示“武汉市东湖新技术开发区”这样的信息不用自己调逆地理编码接口。4.2 景点 POI 的 Marker 展示与点击别用 title 查对象解析完 JSON 后第一步不是直接aMap.addMarker而是维护一个 Marker 列表便于统一清理和刷新private val markers mutableListOfMarker() fun showSpots(spots: ListSpot) { markers.forEach { it.remove() } markers.clear() spots.forEach { spot - val marker aMap.addMarker( MarkerOptions() .position(LatLng(spot.latitude, spot.longitude)) .title(spot.name) .snippet(spot.description) .icon(BitmapDescriptorFactory.fromView(buildIcon(spot))) ) marker.obj spot markers.add(marker) } }marker.obj spot是高频写法比点击时遍历 Marker 集合按 title 查找效率高得多。点击回调里做两件事把 Marker 设为选中态并弹出详情卡片aMap.setOnMarkerClickListener { marker - val spot marker.obj as? Spot ?: returnsetOnMarkerClickListener false marker.showInfoWindow() binding.spotDetailBottomSheet.showSpot(spot) true }提示列表页和地图联动时点击列表项要走同一套逻辑。我的做法是让 Fragment 把 Spot 发给共享 ViewModelMapActivity 观察后调moveCamera并高亮对应 Marker避免两套重复代码维护两个状态源。4.3 路线规划从“看地图”升级成“带路”景点导游最有“干货感”的功能是点击详情页的“去这里”后绘制一条步行路线val routeSearch RouteSearch(this) val query RouteSearch.WalkRouteQuery( RouteSearch.FromAndTo( LatLng(currentLat, currentLng), LatLng(spot.latitude, spot.longitude) ), RouteSearch.WALK_DEFAULT ) routeSearch.calculateWalkRouteAsyn(query) routeSearch.setRouteSearchListener(object : RouteSearch.OnRouteSearchListener { override fun onWalkRouteSearched(result: RouteSearch.WalkRouteResult?, code: Int) { if (code ! 1000 || result?.paths.isNullOrEmpty()) return val walkPath result.paths[0] val list walkPath.steps.flatMap { it.polyline.map { p - LatLng(p.latitude, p.longitude) } } aMap.addPolyline( PolylineOptions() .addAll(list) .width(14f) .color(Color.parseColor(#1E88E5)) ) } })这里的坑在于步行路径是分 step 返回的如果直接拿result.paths[0]的坐标集合去画线会出现断线。上面用flatMap把每个 step 的 polyline 压平拼接成完整坐标链这是路线绘制最容易出错的地方。code ! 1000时九成原因是高德控制台没有给这个 Key 开通“路线规划”服务需要单独申请。4.4 景点列表加载进度条放对位置比样式重要加载 assets 里的 JSON 本身很快但景点语音包和图片在真机上首次读取会有卡顿列表无反馈会显得很“死”。加一个 Material 的CircularProgressIndicatorbinding.progressIndicator.visibility View.VISIBLE viewModel.spots.observe(viewLifecycleOwner) { result - binding.progressIndicator.visibility View.GONE binding.recyclerView.adapter SpotAdapter(result) }进度条放在ConstraintLayout中间位置数据到了就隐藏。除了加载态还要处理一个错误态JSON 解析失败时显示“加载失败重试按钮”而不是白屏。这个兜底在答辩演示时尤其重要机器临时抽风也是评审考察的一部分。4.5 列表与地图联动用最小粒度刷新避免掉帧联动时不要每次点击都重建整个 Adapter而是定位下标后局部刷新fun setSelectedSpot(spotId: String) { val index spots.indexOfFirst { it.id spotId } lastSelected?.let { notifyItemChanged(it) } notifyItemChanged(index) lastSelected index }细节Marker 点击回调在主线程moveCamera动画期间如果同步滚动列表会掉帧。我一般不做scrollToPosition只刷新选中状态用户视觉焦点已经在地图上列表停留在原位反而更自然。地图动画结束后再刷新列表选中态是体感最好的顺序。5. Android 景点导游打包验证混淆、签名与 adb 连真机排错最后一章收在验证环节。这里必须提前做一件事把 release 签名配好不要拿 debug 包去答辩。高德 Key 区分 debug 与 release两者签名指纹不一样你在控制台只申请了 debug Key发布包跑起来定位就会静默失败。用 release 之前先跑一遍./gradlew signingReport拿到发布变体的 SHA1到高德控制台补一个 Key。5.1 用 adb 连小米真机先查这三个位置很多同学开完“USB 调试”后发现adb devices列表还是空的第一反应是换线。排查顺序应该是先adb kill-server adb start-server再看手机上有没有授权弹窗最后查 USB 模式是不是“仅充电”。小米设备要额外打开“USB 安装”和“USB 调试安全设置”连接后常用命令adb devices adb shell dumpsys package com.example.guide第二条命令能确认当前安装包的签名信息、权限列表和目标 SDK比在设置里翻半天可靠。网上有些帖子会教你执行adb shell sh /storage/.../up.sh之类的脚本那是给特定模块用的不是通用操作遇到问题先看adb devices的输出状态是device还是unauthorized。5.2 定位失败现场先看 errorCode 再动代码高德定位失败时回调里的errorCode直接指向问题方向errorCode含义处理方式4Key 不正确或不存在核对包名与 SHA1重新生成 Key7签名验证失败确认 release 包使用独立 keystore重新签名12缺少定位权限检查动态权限是否真正勾选而不是只在 Manifest 声明遇到 7 的典型路径改过包名、换过电脑、或重新生成过 keystore 但忘记更新高德控制台。处理完 Key 后不要只点 Run要卸载旧包重装否则系统缓存里还是旧签名数据。5.3 混淆配置保住数据模型和高德 SDK打 release 包时要保活高德 SDK 和 Gson 要反射的数据模型-keep class com.amap.api.**{*;} -keep class com.autonavi.**{*;} -keep class com.example.guide.data.model.**{*;} -keepclassmembers class ** { android.webkit.JavascriptInterface methods; }data.model必须 keep原因很直接Gson 通过反射按字段名赋值混淆后Spot的latitude变成aJSON 解析出来的对象全为空。验证方式打 release 包后完整走一遍“景点列表 → 地图定位 → 路线规划”主链路再用adb shell dumpsys package核对安装包名与密钥配置。模拟器上定位不准是正常的但 API 调用链通不通、Marker 有没有加载、路线有没有画出一看便知。本文还有配套的精品资源点击获取
