如果你学 Android 学到一定程度整天对着 TextView、Button 打转想找个完整项目练手那 CoolWeather 这个名字多半听过。它是《第一行代码》里贯穿后半本的重头戏一个联网的天气应用——启动之后先选城市然后展示当前温度和天气状况支持手动刷新还能在后台定时更新天气。听起来不复杂但它把 Android 开发里最常用的几块硬骨头全过了一遍网络请求、JSON 解析、SQLite 数据库、Service 后台任务、Activity 和 Fragment 的配合还有列表界面的展示。我当时做这个项目时连 Gradle 依赖冲突都整不明白照着原书敲代码一路踩坑一路搜答案最后看到模拟器里天气数据刷出来的那一刻才觉得自己对 Android 开发终于有了“整体感”。这篇文章不打算复述书里每一行代码而是从一个小白的真实视角把这个项目到底做了什么、开发前要准备什么、核心功能怎么一步步实现以及我自己踩过的坑和排查思路尽量完整地分享出来。如果你正准备拿这个项目练手或者已经做到一半卡住了里面提到的不少问题你应该都会遇到。1. 项目拆解这个天气应用究竟包含多少核心功能1.1 功能清单和用户使用路径先把这个应用当产品来看不要一开始钻代码。CoolWeather 的用户路径非常清晰第一次打开 App看到的是省市县三级联动选择界面你一层层点进去选到具体的县或城市App 会记住这个选择然后进入天气展示界面。天气界面会显示当前城市、更新时间、当前温度、天气状况、最高最低温还有未来几天的天气预报、空气质量、生活建议比如穿衣、运动、洗车指数等等。展示出来之后你可以在界面上手动点击刷新也可以让它自己在后台每隔一段时间重新请求一次天气数据。如果用户把 App 放在后台或锁屏Service 会继续干活下次打开主界面时看到的数据就是新的。另外选过的城市和最后一次天气数据会存到本地数据库和 SharedPreferences 里下次启动直接显示不用每次联网拉全量数据。这个功能范围对新手来说刚刚好不大不小五脏俱全。它有交互、有网络、有存储、有后台逻辑做完之后你对 Android 的四大组件基本都能上手一遍尤其是 Service 和 Activity 的关系很多人学的时候云里雾里做完这个项目就会有实感。1.2 技术栈盘点每个名词背后是什么不用急着把每个技术都吃透但至少要知道这个项目里会用到哪些东西。UI 层Activity Fragment XML 布局城市选择界面用 Fragment 来管理三个层级的列表天气主界面是自定义布局配合 RecyclerView 展示未来几天的预报。网络层基于 OkHttp 封装一个简单的工具类发起 HTTP 请求获取天气数据。数据解析Gson 把 JSON 字符串转成 Java 对象。这一步是很多新手的噩梦因为天气服务商返回的 JSON 嵌套层次特别多一不小心 Gson 解析就崩。数据库SQLite LitePal 这个 ORM 框架来存储省市县数据。原书把全国省市区数据打包在 assets 目录下的 JSON 文件里第一次启动时解析并存入数据库之后直接从数据库读速度快也省流量。后台任务用 Service 做后台循环请求通过线程里的 sleep 控制更新间隔同时结合广播或通知来提示用户。图片加载天气图标是图片用 Glide 来加载顺便处理复用和缓存的问题。这些技术随便单拎一个出来都够学一阵子但在这个项目里它们被组合成一条完整的数据流数据库读城市信息网络请求天气 JSON解析成对象存储缓存再绑定到 UI 上。把这套流程走通比单独看任何一篇教程都管用。1.3 为什么说这个项目适合小白很多人一上来就去啃大型开源项目结果连工程结构都看不懂越看越受挫。CoolWeather 的规模控制得比较好它不像商业项目那样有复杂的架构和几十个模块但也比教科书里单页面的小 Demo 高级不少。你可以跟着原书一步步做下去每完成一个模块都能在 App 里看到实际效果这种正向反馈对小白的坚持非常重要。更重要的是这个项目逼着你接触“真实开发”的思维方式。比如网络请求不能写在主线程你会发现不这么干界面直接卡死甚至 ANR数据从服务器拿回来是 JSON不能直接用必须解析每次刷新界面之前要判断用户有没有选城市各种边界条件很多。这些意识不是看理论能建立的必须亲手把一个功能从接口跑到界面走一遍才会刻在脑子里。2. 开发前的准备环境、数据和工程规划2.1 开发环境与版本匹配如果你用的还是老旧的教程配置项目很可能一上来就编译不过。我的建议是直接用较新的稳定版 Android StudioJDK 用 17 或 21Gradle 版本跟着 Android Studio 自动匹配就行不要手动去改。然后是 Android SDK至少要包含你当前设备或模拟器对应的 API Level同时项目里的 compileSdk 和 targetSdk 建议保持一致。容易踩的坑是号不对齐。比如原书案例基于某个较老的 Android 版本如果你把 compileSdk 升得很高有些依赖库的旧版本反而会出现兼容问题。我当时就在 OkHttp 版本上卡了很久后来统一升级到库作者推荐的版本问题才消失。所以一开始不要迷信“越新越好”稳定能跑比什么都重要。模拟器和真机我建议都准备。模拟器调试方便但天气定位和后台服务的行为和真机还是有区别尤其是国产手机的省电策略会在后面给你上眼药。我自己是先模拟器跑通功能再放到真机上观察后台更新两个环境都得测。2.2 天气数据从哪来原书用的是某个免费天气数据服务商的开放接口。你需要去它的开放平台注册一个账号创建一个应用拿到 API Key然后请求接口时会带上城市 ID 和 Key服务商返回 JSON 格式的天气数据。这里有两个重要提醒。第一注册后不要急着写代码先在浏览器或接口调试工具里请求一次看看实际返回的 JSON 长什么样。很多新手上来就写解析代码结果字段名对不上Gson 解析报错时一脸懵。第二免费接口会有访问频率限制调试时不要疯狂点击刷新否则可能被临时封禁我当时就因为这个白等了一个小时。城市 ID 的问题也要注意。原书的 assets 目录里有一个全国省市区数据文件每个城市都会绑定一个 weather_id比如某个城市对应的是“CN101010100”这种格式。选城市时拿到这个 weather_id后面请求天气数据时把它拼进 URL 里。所以这个项目的数据流是内置 JSON 文件 - 数据库 - 界面选择 - 拿到 weather_id - 拼接天气接口 URL - 请求并解析。2.3 工程目录设计要提前想好原书案例的包结构很清楚我建议你也照着分一遍不要图省事全部写在 MainActivity 里。大致可以分成下面几个包activity存放主界面、天气展示界面的 Activity。service后台更新天气的服务。db数据库相关的实体类和数据操作。util网络请求工具、解析工具、常量类。model对应天气 JSON 结构的实体类比如 Province、City、County、Weather、AQI、Forecast 等等。fragment城市选择界面用的 Fragment。这种分包的好处是职责清晰。网络找 util数据找 model 和 db界面逻辑找 activity 和 fragment。后面如果你要改成 MVVM 架构也是在分包的基础上再增加一层不用大改。我见过很多新手把全部逻辑揉在 Activity 里先不说维护自己过几天回来看代码都找不到方法在哪。3. 一步步实现核心功能从选城市到显示天气3.1 省市区三级联动读数据库还是写死数组城市选择功能的核心是一套三级列表联动界面长这样左边或当前屏显示省份列表点击某个省份进入市列表点击市进入县/区列表选到最末级之后把选择结果回传给天气界面。在实现时不要把这些城市数据硬编码成一个超长数组写在 Java 代码里。正确做法是把它们存在 SQLite 数据库里。原因很简单数据有层级关系筛选查询方便而且数据量不小存库比写死数组干净得多。原书用的是 LitePal 操作数据库实体类定义好之后直接用 LitePal.find() 就能查出来。// 查询省列表 ListProvince provinceList LitePal.findAll(Province.class); // 查询某个省下的市 ListCity cityList LitePal.where(provinceId ?, province.getId()).find(City.class); // 查询某个市下的县区 ListCounty countyList LitePal.where(cityId ?, city.getId()).find(County.class);第一次启动时需要把 assets 里的省市区 JSON 数据解析出来并存入数据库。这里有一个关键性能点解析和写入数据库应该放到子线程不要在主线程执行否则启动画面会卡顿甚至 ANR。我当时在这个功能上遇到的问题比较低级数据解析成功了但数据库里查出来是空的。排查了半天发现是因为 LitePal 的实体类对应表名和默认映射规则不一致我建表时改过表名但查询时用了默认的类名去找自然查不出东西。建议刚开始用 LitePal 时保持类名和表名对应关系简单统一。3.2 天气主界面UI 和数据怎么绑天气主界面是用户最终看到的核心页面。它通常包含一个可上下滑动的 ScrollView内部嵌套多个布局块顶部是当前城市和更新时间中间是当前温度、天气状况图标下面依次是未来几天预报、空气质量、生活建议。界面本身不难难的是数据怎么从网络请求到 JSON再解析成对象最后填到布局里。我习惯写一个工具方法比如 loadWeather(String weatherId)方法内部开一个子线程去请求接口拿到 JSON 后用 Gson 解析成 Weather 对象再通过 runOnUiThread 切回主线程更新界面。String response HttpUtil.sendOkHttpRequest(url); final Weather weather Utility.handleWeatherResponse(response); runOnUiThread(new Runnable() { Override public void run() { if (weather ! null ok.equals(weather.status)) { // 把缓存存到 SharedPreferences SharedPreferences.Editor editor pref.edit(); editor.putString(weather, response); editor.apply(); // 刷新各个控件的显示 titleCity.setText(weather.basic.cityName); nowTemp.setText(weather.now.temperature °C); // ... } else { // 提示用户加载失败 } } });这段逻辑在原书里反复出现请求、解析、切换线程、更新 UI。我强烈建议把这条链路记到脑子里它会伴随你整个 Android 开发生涯。无论是登录、列表还是详情页套路都差不多。很多人卡住的原因就是没理解为什么不能直接在主线程请求其实你只要在代码里故意这么写一次看到应用直接崩溃或者卡住就一辈子记住了。3.3 后台自动更新Service 不是万能保险自动更新天气是一个典型的后台任务需求。原书用 Service 来实现在主界面 Activity 的 onStart 方法里启动服务在 onStop 里停止服务而服务内部维护一个循环每次请求天气数据之后让线程睡一段时间比如 8 小时然后再请求下一次。public class AutoUpdateService extends Service { Override public int onStartCommand(Intent intent, int flags, int startId) { new Thread(new Runnable() { Override public void run() { while (true) { // 请求最新天气并更新缓存 updateWeather(); try { Thread.sleep(8 * 60 * 60 * 1000); } catch (InterruptedException e) { e.printStackTrace(); } } } }).start(); return START_STICKY; } // ... }这里有一个非常重要的背景知识Android 8.0 之后纯后台服务很容易被系统限制一不小心就被杀掉。如果你的 targetSdk 比较高常见做法是把 Service 改造成前台服务也就是在通知栏显示一个常驻通知告诉用户“当前有服务在后台运行”。从产品角度一个天气应用常驻通知确实不太友好但在学这个项目阶段理解 Service 生命周期比纠结产品体验更重要。我在真机调试时发现老代码里那种while (true) Thread.sleep的方式在省电模式下完全撑不过去手机锁屏半小时后服务就没了。后来我把更新逻辑改成 WorkManager 定时任务利用系统提供的周期任务框架可靠性高了不少。这部分属于进阶优化如果你想彻底搞清楚 Android 后台机制可以往这个方向研究绝对值得。3.4 手动刷新和切换城市天气主界面的刷新按钮逻辑其实和加载天气是一个方法只不过多了一层 UI 反馈点击后刷数据成功更新界面失败提示网络异常。切换城市则是从主界面跳回城市选择界面重新选完之后把新的 weather_id 传回来再次触发请求。这里有一个容易被忽略的点切换城市之后的返回键行为。如果你用 Activity 跳转的方式重新打开选择界面用户选完城市按返回键很容易回到旧的天气界面而不是刷新后的新城市天气。我当时处理得比较粗暴在返回主界面时重新加载天气结果有时候加载没完成界面显示的还是旧数据。后来在 onActivityResult 里加了一个标识位强制刷新成功前显示加载状态才把这个问题解决。关于手动刷新还有一个下拉刷新组件可以直接用。原书较早版本没有引入下拉刷新只是做了一个按钮。现在做的话建议直接用 SwipeRefreshLayout 包住 ScrollView用户体验更接近主流 App。4. 踩坑记录与排查思路4.1 网络请求失败从权限到明文流量如果你做完这个项目还没遇到“请求失败”那可能是你运气好。我第一次运行的时候天气死活在界面上刷不出来Logcat 里一堆异常。排查步骤如下第一检查 AndroidManifest.xml 里有没有声明网络权限。这听起来像废话但漏的人不在少数尤其是直接复制别人的清单文件时最容易把权限弄丢。第二检查 URL 拼得对不对尤其是 weather_id 和 Key 参数。我调试时习惯把最终拼出来的 URL 打印在 Log 里再复制到浏览器打开如果浏览器能正常返回 JSON说明接口没问题问题出在 App 代码。第三检查 Android 9.0 以上对明文 HTTP 的限制。如果接口地址是 http:// 而不是 https://系统默认不允许应用直接访问明文流量。解决办法是在 AndroidManifest.xml 的 application 标签上加android:usesCleartextTraffictrue或者配置网络安全策略文件。超时问题也很常见。默认连接超时时长可能太短尤其是模拟器网络状态不好的时候请求稍微慢一点就报 SocketTimeoutException。建议在 OkHttp 或底层连接时显式设置 connectTimeout 和 readTimeout比如 10 秒。4.2 JSON 解析异常结构对照法是核心技能Gson 解析崩是小白遇到最多的报错之一常见提示包括 JsonSyntaxException 或 NullPointerException。根本原因几乎都是“代码里的实体类结构和接口实际返回的 JSON 对不上”。接口返回的天气数据往往是多层嵌套的这里就不贴完整 JSON 了直接说几个容易踩的点。第一顶层可能是一个数组比如HeWeather你必须用 List 来接收而不是单个对象。第二某些字段是字符串类型比如温度18你在实体类里如果用 int 接收Gson 在某些情况下也会出问题建议和接口保持一致用 String。第三不同的天气状况字段可能在多个层级比如实时天气是now.cond.txt未来预报是数组里的cond.txt_d不要搞混。我最推荐的排查方式是把返回的 JSON 原样复制到一个在线 JSON 格式化工具里一边看结构一遍对着实体类改。不要靠猜不要靠改一个字段试一次效率太低。另外一个技巧是在解析前先打印 response很多时候解析失败是因为请求本身返回了错误信息比如 Key 失效而不是数据结构不对。4.3 后台服务不干活本质是系统资源的博弈后台服务是小白最容易误以为“写完就完了”的部分实际上它涉及 Android 系统对应用资源的限制。Samsung、华为、小米等手机都有各自的省电策略会在特定条件下清理后台进程或限制网络访问。我自己测试时出现过这种现象天气应用在前台一切正常锁屏放了一个晚上第二天解锁打开数据显示还是昨晚的也就是说服务在后台根本没跑起来。排查思路是这样的先看服务有没有被系统杀死可以在服务里加日志观察 onDestroy 是否被调用再看是否是因为应用被放在了省电名单外或被限制后台联网。同时也要检查代码里有没有在服务启动条件上犯低级错误比如没有调用 startForeground 导致 Android 8.0 以上启动服务直接被拒。做进阶优化时可以用 WorkManager 替代纯 Service它能在系统允许的时间窗口内执行任务被系统杀死后还能重试是最稳妥的姿势。4.4 图片加载和列表卡顿天气应用中图片不算多但如果你把未来几天的预报做成列表并尝试用 ListView 或 RecyclerView 加载天气图标时就会遇到图片加载和列表复用的问题。直接在主线程用BitmapFactory.decodeFile去加载网络图片会卡到你怀疑人生正确思路是交给 Glide。用 Glide 很简单Glide.with(context) .load(https://example.com/icon/ weatherCode .png) .into(imageView);它内部会自动做图片缓存、尺寸压缩和异步加载不需要你自己管线程。我还要提醒两个细节一是 Glide 的with(context)最好传入 Activity 或 Fragment 的实例不要传 Application Context否则无法感知生命周期可能在界面销毁后继续加载导致问题二是 RecyclerView item 里如果有圆角或阴影效果尽量避免在运行时动态创建 ShapeDrawable这会加大绘制成本我当时就因为在 item 的bindViewHolder里每次 new 一个背景导致列表滑动时有明显掉帧。5. 如果重新做一次我会怎么优化5.1 架构升级从堆代码到有层次原书的代码偏向功能实现Activity 里往往包含了网络请求、解析、更新 UI 的一整套逻辑。作为学习没问题但做完之后下一步最好做架构层面的重构。最直观的改动是引入 ViewModel LiveData把 Activity 里的数据持有和更新抽离出来。ViewModel 的好处是界面旋转时数据不会丢LiveData 可以自动感知生命周期避免内存泄漏。原来用 Handler 切线程更新 UI 的代码可以大幅删减。做完这个重构你会发现 Activity 瘦了很多逻辑边界更清楚网络请求放仓库层数据存放到数据库层界面只关心状态的展示。我当时按照这个思路改造时顺便把网络库换成了 Retrofit 配合协程因为 Retrofit 的接口定义方式比手写 OkHttp 工具类干净得多配合 Gson 转换器甚至可以自动完成解析主线程调度也由协程接管。可能有人觉得这违背了“小白项目”的初衷但恰恰相反从能跑到写得体面本身就是一个工程师成长的必经路径。5.2 功能扩展往产品方向多想一步技术跑通后你可以从产品角度问自己几个问题用户真的愿意手动打开 App 看天气吗天气数据能不能自动定位当前城市未来几天的气温变化能不能用图表展示空气质量指数有没有颜色分级极端天气有没有预警推送这些问题每一个都可以变成一个扩展点。我建议挑一两个做深不要全都做。比如定位功能用系统自带的定位 API 获取经纬度再通过地理编码接口反查城市最后更新天气信息。这一个功能做完你会接触到权限申请、运行时权限处理、定位服务回调等一系列新知识成长比重复做列表要大得多。再比如把数据和图表结合用自定义 View 画一个未来 24 小时温度曲线又会涉及到 Canvas 绘制的知识。5.3 从“照书敲”到“自己设计”最后一条建议听起来玄但非常重要。做完原书项目之后可以尝试不看书从零开始重新实现一遍功能。你可以换一套架构换一套命名换一个 UI 风格甚至把省市区数据源换成自建的接口模拟。这个过程你会明显感觉自己从“代码搬运工”变成了“设计者”。我个人的体会是照书敲代码时很多问题是被书里的解决方案提前屏蔽掉的你没有真正经历过“面对问题、分析方案、挑选技术”的思考过程。重新自己设计时你会发现自己开始主动思考缓存策略、接口设计、错误提示、边界情况这些才是开发工作中真正值钱的能力。如果再用这个项目练一次手我会更早接入自动化测试和日志系统把网络请求和解析结果用日志记录下来而不是等到报错时再一个 Toast 一个 Log 地打。记住一点这个项目的核心价值不全在天气功能而在于你通过它把 Android 开发的整个链路打通了。后面你再做任何 App都会发现很多内容不过是对这套链路的重组和扩展。最后再分享一个小技巧调试天气项目时在 OkHttp 拦截器里打印完整请求和响应或者直接用日志工具观察 API 返回。你看到的原始 JSON 永远是排查问题最直接的线索比看任何报错堆栈都管用。踩过这些坑之后再去看别的网络请求项目你会淡定很多。