企业官网建设流程全解析

在景区里打开导航是最让人崩溃的事情之一：地图上明明显示“您已到达目的地”，可你面前只有两米高的灌木丛和一脑袋的问号。城市导航在景区失灵几乎是常态，道路数据缺失、卫星信号被山体遮挡、POI分布稀疏，这些问题的根源在于通用地图服务商不会为一个景区单独维护路网数据。所以当A同学提出用Spring Boot做后端、Android做客户端，给青屿山景区定制一套旅游导航系统App时，我几乎没有犹豫就接了这个项目。

这个项目从立项到交付调试大约用了六周，中间踩过的坑、推倒重来的模块、真机联调时的连环翻车，都值得单独写一篇文章记录。如果你正好在准备毕业设计，或者想完整走一遍“Android客户端 + Spring Boot服务端”的实战流程，这篇内容可以作为参考蓝本。我会把架构设计、数据库建模、关键接口实现、Android端地图接入、前后端联调排错，以及打包交付前最容易忽略的细节全部拆开讲，尽量做到拿来就能用。

1. 立项前的调研：景区导航App到底要解决什么问题

1.1 景区导航和城市导航的差异到底在哪

通用地图在城市里好用，是因为城市路网数据完整：有道路等级、有车道信息、有门牌号，而且建筑遮挡相对可控。但换成山区景区，情况完全不同。山上的步道、栈道、缆车线路，通用地图上要么没有，要么与实际走向偏差很大；卫星信号经过山体反射后，定位点会左右漂移十几米；再加上景区里岔路口多、标识不全，游客经常在某个“三岔路口”不知道该往哪走。

这个项目要做的，不是把通用地图搬进App，而是围绕青屿山景区自建一套路网数据和景点POI体系，再通过Android端的地图SDK把路线绘制出来。简单说，我们要做的是“景区专用导航层”，底层仍使用第三方地图SDK负责定位和底图展示，但路线数据、景点位置、导航提示全部由我们自己的Spring Boot后端维护。

还有一个容易被忽略的问题：偏远景区网络状况普遍不稳定。如果每一次坐标请求都依赖实时网络，App基本没法用。所以缓存策略是需求文档里单独列出来的一条核心约束，后面我会详细讲我做的四级缓存方案。

提示：立项阶段如果只盯着“导航”两个字，很容易把项目做成一个地图Demo。一定要先梳理清楚：哪些数据必须服务端控制、哪些逻辑可以放本地、弱网下App如何降级表现。这个因素直接决定了后期开发会不会返工。

1.2 功能范围怎么裁剪：砍掉哪些、保留哪些

需求评审时列出来的功能远比我最后做的多。AR实景导航、语音讲解、在线购票、实时客流热力图、UGC游记社区……每一个听起来都很加分，但都能单独开一个更复杂的项目。作为以Spring Boot和Android为核心链路的实战项目，我更倾向于把链路做完整而不是把功能面铺开。

最终保留了六个功能模块：

• 用户注册与登录：基于JWT的无状态认证，包含密码加密存储和Token过期刷新机制。
• 景点列表与详情：分页加载青屿山景点数据，展示图片、介绍、开放时间、建议游玩时长。
• 地图定位与景点标注：进入地图页自动定位，把附近景点以Marker形式标注在底图上。
• 路线规划与导航轨迹：选择起点和终点，后端返回路线坐标点集，客户端绘制轨迹并提供转向提示。
• 景点评论与评分：登录用户可以发表评论和打分，列表按时间倒序展示。
• 收藏管理：用户收藏景点，个人中心查看收藏列表。

砍掉的功能不是不好，而是不符合这个项目的技术目标。比如AR导航需要额外的视觉识别能力，语音讲解需要大量音频资源制作，在线购票则牵扯支付渠道和退款流程。一个项目能在六周内做完整、能演示、能答辩，比堆砌一堆半成品功能重要得多。

2. 后端Spring Boot接口与数据表：先定好传输协议再写界面

2.1 五张核心表怎么设计

数据库设计是整个项目的地基。我的原则是：能用最简单的表结构表达清楚业务关系，就坚决不加冗余字段。青屿山导航系统后端一共五张核心表。

用户表主要存账号信息、密码盐值和用户昵称。密码字段存储的是加盐后的哈希值，数据库不保存明文密码。

景点表是内容核心，包含经纬度、区域名称、封面图URL、开放时间、建议时长。经纬度存储有一个大学问：Android端第三方地图SDK返回的坐标是GCJ-02坐标系，如果后端用GPS原始WGS-84坐标，两者混用会导致Marker偏出去好几十米。我统一采用服务端只存GCJ-02坐标，客户端直接使用，不做转换。

路线表用来存储一条推荐游览路线的节点信息。表里面除了路线基本信息外，专门设计了route_points字段，以JSON数组存储该路线的全部途经点坐标，包括经纬度、节点名称、节点类型。导航轨迹绘制本质就是解析这个JSON，再把坐标点连成线。

评论表和收藏表就是常规的主从关系表，评论关联用户ID和景点ID，收藏也类似。所有外键关系通过索引维护，没有物理外键。

表结构上值得多说一句的是：业务表都加了create_time和update_time两个审计字段，虽然会让插入语句稍微麻烦一点，但在排查数据和联调问题时能省下大量时间。

2.2 JWT登录认证：用一个拦截器解决所有受保护接口

用户认证我选择JWT而不是Spring Security + Session，理由很简单：Android客户端是无状态的，Token交互比Session Cookie方便得多，而且毕业设计答辩时讲JWT的认证流程，思路清晰、容易展开。

后端引入jjwt库，拦截器处理流程如下：

1. 用户调用登录接口，校验用户名密码，通过后生成Token返回客户端。
2. Token负载部分只放userId和username，过期时间设置为2小时。
3. 自定义HandlerInterceptor，在preHandle阶段从请求头Authorization中解析Token。
4. 校验签名和过期时间，通过则把userId写入request属性，后续Controller直接取用；失败则返回401状态码。
5. 注册拦截器时，放行登录、注册、景点列表、景点详情等不需要认证的接口。

核心代码很短，配置拦截器时有一个细节容易忽略：拦截器的排除路径必须同时包含GET和POST两种方式。如果只写了路径没写HTTP方法，会出现登录接口被拦截器误伤的奇观。

注册接口的密码处理用的是加盐SHA-256，每次注册生成随机盐值，密码哈希值存储到数据库。这样做的主要目的是防止彩虹表攻击，虽然加了盐也不能算绝对安全，但在这个项目级别已经足够了。

2.3 统一返回结构与分页接口设计

接口协议不统一，前后端联调就是灾难。后端从第一天起就固定了统一的返回结构Result ，包含code、message、data三个字段。code为200表示成功，401表示未认证，500表示服务端异常。Android端所有的网络响应解析都建立在这个统一结构上，不需要针对每个接口单独写解析逻辑。

景点列表接口是一个典型的分页接口，参数为pageNum和pageSize，返回结构包含当前页数据、总条数和总页数。这里有一个实际开发中容易忽略的点：分页返回的景点列表字段里有一个is_favorite标记，表示当前登录用户是否已经收藏过该景点，需要在SQL查询时根据userId做left join判断。一开始我忽略了这个字段，导致列表页的收藏按钮状态显示错乱，后来才补上。

接口文档我用OpenAPI生成，启动项目后访问Swagger UI就能看到每个接口的入参、出参和错误码说明。文档除了给自己看，更重要的作用是给Android端开发同学（也就是另一个身份的我自己）提供联调依据，不用每次翻代码去猜字段含义。

3. Android端四个核心模块：从列表到地图的完整实现

3.1 网络层搭建：Retrofit + OkHttp + Token拦截器

Android端网络层我采用Retrofit 2 + OkHttp + Gson的组合。这个组合在Android生态里足够成熟，Retrofit负责接口定义和响应转换，OkHttp负责底层HTTP连接和拦截器，Gson负责JSON序列化反序列化。

ApiService使用接口加注解定义所有后端接口：

public interface ApiService { @POST("api/user/login") Call<Result<UserInfo>> login(@Body LoginRequest request); @POST("api/user/register") Call<Result<String>> register(@Body RegisterRequest request); @GET("api/spot/list") Call<Result<PageResult<SpotItem>>> getSpotList( @Query("pageNum") int pageNum, @Query("pageSize") int pageSize ); @GET("api/spot/detail/{id}") Call<Result<SpotDetail>> getSpotDetail(@Path("id") int id); @POST("api/review/add") Call<Result<String>> addReview(@Body ReviewRequest request); }

重点是OkHttp的Token拦截器。用户登录成功后，Token保存到SharedPreferences；发起请求时，拦截器从SharedPreferences取出Token，添加到请求头。如果请求返回401，拦截器捕获响应后回调一个事件，通知界面跳转到登录页。

这个拦截器还有一个作用：统一处理弱网重试。OkHttp的retryOnConnectionFailure方法配合合理的超时时间，可以在Wi-Fi切换或信号波动时自动重试一次，别小看这一次重试，真实景区场景下经常就是这么一次重试救回了请求。

BaseUrl的配置我单独拎到了BuildConfig里，debug环境指向局域网IP，release环境指向云服务器域名。后面打包部分会详细说这个配置的意义。

3.2 地图SDK接入与路线绘制：注意坐标系一致

地图模块是整个App技术含量最高的部分，也是我花时间最多的地方。Android端接入的是第三方地图SDK，应用启动时在Application的onCreate中完成初始化，地图页加载时开启定位。

定位权限处理有个很容易被忽略的细节：Android 6.0以上必须动态申请权限，Android 12以上还需要精确定位权限的额外声明。如果只检查了ACCESS_FINE_LOCATION，真机在Android 12上定位会静默失败，控制台连错误日志都没有。

定位成功后拿到当前坐标和景区边界，用SDK的标记管理类把景点以Marker形式添加到地图。这里要特别注意：后端返回的景点经纬度必须和地图SDK使用同一个坐标系。我在2.1节已经说过，后端统一存储GCJ-02坐标，客户端拿到后直接使用，不要自作主张再转换一次，否则Marker会偏移到奇怪的地方。

路线绘制的核心逻辑是：根据路线ID请求后端接口，拿到route_points坐标点数组，遍历数组构建PolylineOptions对象，设置线段颜色和宽度后添加到地图。转折点处加方向箭头，终点处添加终点Marker。导航提示做成了Toast形式，在轨迹每个关键节点坐标附近触发，保证用户不用一直低头看屏幕。

真机测试时我发现模拟器上一切正常，但真机上Marker点击事件会偶发丢失。排查后定位为：Marker被地图的默认点击事件消费了，需要在SDK的OnMarkerClickListener回调里返回true，表示事件已消费，不再继续往下传递。

3.3 景点列表、详情和评论：RecyclerView的常规与不常规

景点列表页就是一个标准的RecyclerView + CardView列表，图片加载用Glide。这里要提一个从实际测试中总结出来的经验：景区封面图原图动不动3-5MB，在弱网环境下加载慢得让人怀疑App崩了。Glide的override方法把图片尺寸限制到400dp宽，后端接口同时返回大图和小图两个URL，列表页用小图，详情页再用大图，图片流量能缩小80%以上。

详情页除了景点介绍外，还放了评论区列表和评分展示。评论列表同样使用RecyclerView，内嵌了一个“写评论”的浮动按钮，点击后弹出底部对话框。评分用Android的RatingBar组件，默认星星颜色太淡，在深色背景上几乎看不见，需要设置自定义starDrawable，这个也是实测后调整的。

评论提交的接口有一个隐藏校验：登录状态过期后，后端会返回401。如果客户端没有全局处理401跳转，用户会感觉“点了提交没反应”，其实是请求已经失败但界面上没有任何提示。把401处理统一定义在网络层拦截器里非常必要，现在几乎成了我自己所有项目的标配。

收藏按钮在列表页和详情页各有一个，状态同步是一个小坑。设计思路是列表页的is_favorite字段只作为初始展示，点击收藏按钮时立即更新本地UI，同时调用后端接口。如果接口失败，再回滚按钮状态并弹出提示。这种做法牺牲了一点严格一致性，换来的是操作响应快，弱网环境下不会出现“点了半天按钮没反应”的挫败感。

4. 前后端联调排查：那些在机房试不出来、真机才暴露的问题

4.1 明文流量限制、局域网IP与JWT过期的连环坑

联调阶段遇到的第一堵墙是Android的明文流量限制。从Android 9开始，应用默认禁止使用HTTP明文协议访问网络，而后端开发环境跑在http://192.168.x.x:8080。第一次用真机调试时，所有请求全部报CLEARTEXT communication not permitted，接口一个都打不通。

解决方案有两种：直接设置android:usesCleartextTraffic="true"允许所有明文流量，或者配置networkSecurityConfig只允许特定域名的明文访问。我用了第二种，只让debug环境指向的局域网IP走明文，release环境默认走HTTPS。这样既解决了调试问题，也不会在正式包上留下安全隐患。

第二堵墙是局域网IP访问不到。开发机和手机连了同一个Wi-Fi，但后端的Spring Boot只监听localhost，Android端当然连不上。排查到这一步时，需要在application.yml里修改server.address=0.0.0.0，让服务对外可见。同时Windows防火墙也要放行8080端口，否则请求会卡在连接超时。

第三堵墙是Token过期后的连锁反应。我的Token有效期设成2小时，调试时触发一次过期后，所有受保护接口都返回401，但客户端全局拦截器没有做“跳转登录页”的动作，而是把错误弹窗展示出来了，体验非常糟糕。后来我实现了401统一处理：拦截到401时清空本地Token，发送一个登录失效的全局事件，所有Activity通过观察者模式监听到事件后统一跳转登录页。

4.2 山区弱网环境的四级缓存方案

青屿山景区面积不小，部分区域4G信号只有一格甚至完全断网。Android端如果不做缓存，断网状态下App基本变成一块废铁。我最终实现了四级缓存方案。

第一级是内存缓存。HashMap保存最近访问的景点详情数据，LRU策略淘汰，适合在同一会话中快速返回上一页再进入的场景。

第二级是磁盘缓存。用文件缓存保存景点列表的JSON响应，设置5分钟过期时间，列表页优先读缓存，同时后台请求最新数据并更新UI。这个策略让用户在信号不稳定区域依然能浏览到景点列表。

第三级是SharedPreferences保存用户偏好类数据，比如登录Token、主题模式、搜索历史。Preferences是在Android里最轻量的本地存储方式，适合存少量键值对。

第四级是离线地图包。这个项目因为时间关系只做了基础支持：用户可以在Wi-Fi环境下提前下载青屿山景区的离线底图切片，断网时地图底图依然可以显示，但动态路线请求会失败并给出友好提示。

实现缓存时有一个顺序问题：网络请求返回成功后先写缓存再更新UI，还是先更新UI再异步写缓存？我最终选择后者，因为先更新UI可以让用户感觉响应更快。缓存写入正常情况下耗时极小，放在异步线程里执行即可。

5. 打包交付前必须做的三件事：签名、环境切换和文档沉淀

5.1 签名打包与多渠道环境配置

开发调试期间用的是Android默认的debug签名，但交付时一定要配置独立的release签名文件。Android Studio里签名的生成路径很直观：Build菜单下Generate Signed Bundle/APK，按向导创建一个keystore文件，配置好别名和密码即可。有一个建议是把签名文件信息写入gradle配置里的signingConfigs，并设置storePassword和keyPassword通过环境变量获取，不要把明文密码提交到代码仓库。

环境切换是我在无数个项目里反复强调的问题。开发环境连局域网IP，测试环境连测试服务器，正式环境连线上服务器。如果每次打包前手动改代码里的BaseUrl，改动成本低但容易漏改，还会出现忘记切换导致正式包连了测试环境的情况。我用BuildConfig字段区分环境，在build.gradle里根据buildType设置不同的BASE_URL，代码里统一从BuildConfig读取。这样打包release版本时自动使用正式地址，完全不需要人为干预。

5.2 我所总结的十几条实用避坑清单

最后这份清单算是这个项目最大的副产品，每一条都是在真机或交付过程中真实踩过、修过的坑，分享给你直接照着避雷。

• 坐标体系必须统一。Android端地图SDK使用GCJ-02，后端数据必须存GCJ-02，不要混用WGS-84。
• 权限动态申请要覆盖Android 12及以上版本，只申请定位权限不够，还要检查精确定位的权限声明。
• OkHttp超时时间不能统一设成默认值，复杂网络环境下建议connectTimeout 10秒、readTimeout 15秒，过短会误判失败，过长会卡界面。
• 列表图片务必做尺寸压缩和缩略图方案，否则弱网环境直接劝退用户。
• 结果集分页接口必须返回总条数，否则客户端无法判断是否还有下一页。
• 接口字段命名统一使用驼峰，后端Java和Android端Java都是驼峰习惯，JSON序列化保持默认即可。
• JWT的Token生成时加入客户端类型字段（Android/iOS），方便后续做多端区分和统计绕过率。
• 注册接口要加验证码机制，至少也要做请求频率限制，否则容易被打接口刷垃圾账号。
• 数据库所有表加create_time字段，排查问题时没有这个字段真的会想哭。
• 配置文件里的密码、密钥不要出现在代码里，用环境变量或jasypt加密。
• Android的Gradle依赖版本要固定，不要用动态版本号加号，团队协作时版本冲突会让你怀疑人生。
• 定时任务如果有自动刷新Token的能力，心跳接口和Token刷新接口需要做好并发控制，避免同时发起多个刷新请求。
• Swagger接口文档一定要标注每个字段的示例值，给队友联调时可以少问十次“这个是什么”。

我做完整交付时最大的体会是：一个项目能不能用，不看它堆了多少功能，而是看它在不理想的环境下还能不能保持基本可用。青屿山旅游导航系统虽然只覆盖了核心链路，但至少做到了：打开App能看到景点、能定位不漂移、能断网浏览缓存、登录状态清晰可控。把这条路走通之后，后面想扩展实时客流、语音播报或者其他功能，都只是往这个稳定骨架上填肉的问题。