Android Studio天气预报小程序源码：环境配置与网络解析实战

简介这是一份 Android Studio 天气预报小程序完整源码包定位为 Android 初学者的实战练手项目也适合用于课程设计或毕业设计参考。项目基于 Retrofit 与 Gson 技术栈访问 OpenWeatherMap 天气服务完整覆盖了 Android 应用开发中常见的关键环节新建工程与依赖配置、定义网络请求接口、初始化 Retrofit 实例、发送异步请求、解析返回的 JSON 数据、在 TextView 等控件上绑定城市名和温度信息并加入了加载进度提示、下拉刷新与本地缓存等交互优化。压缩包共包含 1260 个文件整体大小约 9.76MB。文件类型中既有编译阶段生成的 flat、dex、class 中间产物也有 120 个 JSON 配置、76 个 XML 布局、33 个 Java 源码以及 21 张 PNG 图片附带的 Android 工程目录结构清晰便于按模块对照学习。目前已有 3876 人学习下载。借助这份源码开发者可以快速掌握天气类应用的整体搭建思路并在此基础上进一步扩展多城市切换、未来一周预报和天气图标动画等功能。1. AndroidStudio 实现天气预报小程序源码它到底在解决什么问题一说到天气预报小程序源码很多人第一反应是“不就是调个接口、显示个温度吗”。但真正拿到一份源码想在 Android Studio 里跑起来时卡住你的往往不是天气数据本身而是工程环境、权限、网络请求、JSON 解析这一整条链路。我见过太多人卡在第一步源码下了Gradle 同步失败同步过了模拟器上黑屏好不容易起来又请求不到数据。这份笔记要讲的就是怎么在 Android Studio 里把一份天气预报小程序源码从“能编译”推进到“能稳定出数据、能换城市、能扛住高频刷新”中间每一步的选型理由和坑位我都会给出可照做的方案。这套技术方案适合三类人做 Android 课程设计需要交付源码的学生刚学完四大组件想练手网络请求的初级开发者以及想快速搭一个带天气展示的内部工具应用、又不愿意为纯展示功能引入重型框架的从业者。它不需要高深的算法不需要后端配合只靠 AndroidStudio 原生工程加上一个免费的天气数据源就能做出完整功能。下面从数据源选型开始拆。2. 做天气 App 前先想清楚的数据源选型和三层架构2.1 天气数据源怎么选免费、稳定、文档全的优先天气预报小程序源码的核心不是界面是数据。而数据源的选择直接决定你要写多少解析代码、会不会用着用着就断供。常见的公开天气接口有和风天气、心知天气、OpenWeatherMap 这几个。国内访问稳定性、返回字段完整度、注册免费门槛这三个条件都要看我一般建议新手直接用支持城市 ID 和经纬度查询、返回 JSON 的国内服务商。原因有三第一国内服务商的文档和示例代码是中文的出问题了能查第二响应速度更快因为服务器节点在国内第三免费版额度对个人学习足够用不会用几天就被封。以免费版接口为例通常注册后你会拿到一个 API Key。请求 URL 的形式一般是https://www.example-api.com/api/weather?city城市IDkey你的Key。建议你直接在浏览器里先访问这个 URL确认返回的 JSON 结构后再去写代码。这一步很多人跳过了结果代码写完一直解析失败最后才发现是返回格式和自己想的不一样。先在浏览器里看到真实数据是写所有网络请求代码的第一原则。2.2 定一个不后悔的包结构和数据流拿到一份源码或者自己新建工程时先把包结构定下来否则写到后面 Activity 里全是 JSON 解析代码改一个字段要翻半天。常见做法是分三层网络层负责发请求和拿原始字符串数据层负责把 JSON 转成 Java 对象UI 层只负责把对象里的字段展示到控件上。对应到包名就是network、bean、ui三个包加上一个utils包放公共工具。数据流向是固定的UI 层触发请求 → 网络层用 OkHttp 发异步请求 → 回调里拿到 JSON 字符串 → 数据层用 Gson 解析成实体类 → 实体类对象通过接口回传给 UI 层 → UI 层刷新控件。这个流程放在哪个 Activity 里都一样所以把它写成工具类最划算。一个典型的工具方法签名是getWeather(String cityId, Callback callback)内部封装了 OkHttp 的请求和异常处理UI 层只需要传入城市 ID 并实现回调接口即可。这样做的好处是将来加多城市、加缓存、加自动刷新都不需要动 UI 代码。// NetworkUtils.java 核心骨架用 OkHttp 封装天气请求 public class NetworkUtils { private static final String BASE_URL https://www.example-api.com/api/weather; private static OkHttpClient client new OkHttpClient.Builder() .connectTimeout(10, TimeUnit.SECONDS) // 连接超时模拟器网络不好时能快速失败 .readTimeout(10, TimeUnit.SECONDS) // 读取超时防止接口卡死 .build(); public interface WeatherCallback { void onSuccess(String json); // 返回原始JSON解析交给数据层 void onError(String error); // 返回错误描述方便排查 } public static void getWeather(String cityId, String apiKey, WeatherCallback callback) { String url BASE_URL ?city cityId key apiKey; Request request new Request.Builder().url(url).build(); client.newCall(request).enqueue(new Callback() { Override public void onFailure(Call call, IOException e) { callback.onError(e.getMessage()); } Override public void onResponse(Call call, Response response) throws IOException { if (response.isSuccessful()) { callback.onSuccess(response.body().string()); } else { callback.onError(HTTP错误码: response.code()); } } }); } }这段代码有三个参数需要按你的实际情况调connectTimeout和readTimeout建议保持 10 秒太短了容易在弱网下误判失败太长了用户会以为死机BASE_URL里的域名和路径必须以你注册的服务商文档为准cityId不是城市名称而是服务商定义的城市代码在服务商的“城市列表”文档里可以下载或查询。注意onResponse里调用了response.body().string()这个方法只能调用一次重复调用会报IllegalStateException拿到字符串后记得检查是不是ok或success开头有些服务商会在业务错误时依然返回 HTTP 200只在 JSON 里放错误信息这一步拦截能省很多排错时间。3. 用 Android Studio 跑通最小可运行版本从新建工程到首次出数据3.1 环境自检Gradle 版本和 SDK 在哪一步最容易翻车用 AndroidStudio 打开别人给的源码时第一次爆炸点九成在 Gradle 同步。新版 Android Studio 的 Gradle 版本和插件版本不匹配就会报Minimum supported Gradle version is X.X.X这个错误和天气代码没有任何关系纯粹是环境问题。常见做法是先自查本机已安装的 Gradle 版本和 JDK 版本再回头看你拿到的源码里build.gradle的配置。gradle-wrapper.properties里写的是 Gradle 自身版本build.gradle里的com.android.tools.build:gradle:7.0.4是 Android 插件版本这两个必须存在兼容关系。Gradle 7.0.4 这个版本号在热搜里出现频率很高对应的兼容 Gradle 版本是 7.0.2 以上JDK 要用 11。我建议直接先跑一个官方模板工程确认 Android Studio 本身能用再往这个模板里搬天气代码而不是一上来就啃别人的完整工程。如果你拿到的源码是 2023 年以前写的大概率用的是androidx.appcompat老版本依赖新工程模板里已经把这些依赖升级了直接搬代码时要留意 import 路径的变化。3.2 权限、依赖和网络配置最小工程的三个必改点在写任何天气请求代码之前先把 AndroidManifest.xml 里的网络权限加上再把usesCleartextTraffic这个属性设好。Android 9 及以上默认禁止明文 HTTP 请求如果你用的免费接口不支持 HTTPS请求会直接报CLEARTEXT communication not permitted这一条坑了非常多初学者。解决办法有两种一是换成 HTTPS 接口二是在 manifest 里声明允许明文流量。依赖方面在build.gradle的 dependencies 块里至少要加两个库OkHttp 负责网络请求Gson 负责 JSON 解析。这两个库都是 Maven 中央仓库的公开依赖不需要额外配置仓库地址Android Studio 会自动下载。如果你下载慢可以在settings.gradle里把google()和mavenCentral()的仓库换成国内镜像。!-- AndroidManifest.xml 中需要确认的三个关键配置 -- uses-permission android:nameandroid.permission.INTERNET / uses-permission android:nameandroid.permission.ACCESS_NETWORK_STATE / application android:usesCleartextTraffictrue android:label天气预报 android:themestyle/Theme.AppCompat.DayNight /application注意三个点INTERNET权限是请求天气数据的基础漏了它 OKHttp 会直接抛UnknownHostException这个报错很容易让人误判成网络问题ACCESS_NETWORK_STATE权限不是必须的但加上后可以在代码里判断当前网络是否可用避免在飞行模式下白等超时usesCleartextTraffictrue只在调试阶段推荐正式上线如果接口支持 HTTPS 建议去掉否则会有安全隐患。这个属性对整个 application 生效不需要在具体 Activity 上重复配置。3.3 写一个能拉回天气 JSON 的 MainActivity环境配置完成后写一个最简 Activity 来验证“网络层是否能拿到数据”。这一步的目标不是好看是让数据流先通起来。布局里只需要放一个按钮和一个 TextView点击按钮发起请求把返回的原始 JSON 直接显示在 TextView 上。很多人第一步就去做复杂 UI结果数据还没通界面写了几个小时最后全返工。先把原始数据打出来再谈美化。// MainActivity.java 最小验证代码 public class MainActivity extends AppCompatActivity { private TextView tvResult; private static final String API_KEY 你的APIKey; // 从天气服务商后台获取 Override protected void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); setContentView(R.layout.activity_main); tvResult findViewById(R.id.tv_result); findViewById(R.id.btn_query).setOnClickListener(v - NetworkUtils.getWeather(101010100, API_KEY, new NetworkUtils.WeatherCallback() { Override public void onSuccess(String json) { runOnUiThread(() - tvResult.setText(json)); // 子线程不能直接改UI } Override public void onError(String error) { runOnUiThread(() - tvResult.setText(请求失败: error)); } }) ); } }这里的101010100是北京的地区代码实际使用时要根据服务商的编码规则去替换。runOnUiThread这一行不能省因为 OkHttp 的回调线程不是主线程直接操作 TextView 会报Only the original thread that created a view hierarchy can touch its views。这一步跑通的标准是点击按钮后 TextView 里出现一大段 JSON里面有temp、humidity之类的字段。如果你看到的是一个带code:401的 JSON说明 API Key 填错或者没有开通对应服务如果是一段浏览器都打不开的域名错误说明 BASE_URL 的地址和服务商的文档不对应。这一关过了后面的事情就是“把 JSON 变成界面”的工作量问题了。4. 把 JSON 变成界面解析、适配器和城市切换4.1 定义一个对得上接口的天气实体类用 Gson 解析天气 JSON 前要先把实体类定义好。实体类的字段名必须和 JSON 里的 key 一致否则解析出来全是 null。所以正确做法是把浏览器里看到的 JSON 保存下来照着它一个字段一个字段地写实体类不要凭记忆猜字段名。Gson 解析时遇到实体类里没有的 JSON 字段会自动忽略但如果 JSON 里没有实体类已有的字段Gson 会直接赋 null后面一调用就是空指针。// WeatherBean.java 天气实体类字段名严格对标JSON返回 public class WeatherBean { private String city; // 城市名称 private String updateTime; // 数据更新时间 private NowBean now; // 当前天气对象 public String getCity() { return city; } public String getUpdateTime() { return updateTime; } public NowBean getNow() { return now; } public static class NowBean { private String temp; // 当前温度注意服务商返回的是字符串还是数字 private String feelsLike; // 体感温度 private String humidity; // 湿度百分比 private String info; // 天气现象描述晴、多云等 public String getTemp() { return temp; } public String getFeelsLike() { return feelsLike; } public String getHumidity() { return humidity; } public String getInfo() { return info; } } }这里最容易被忽略的是temp字段的类型。有些服务商返回temp: 16是字符串有些返回temp: 16是数字如果实体类写成intGson 解析字符串也会自动转但如果写成String而 JSON 里是数字Gson 同样能转成字符串。为了避免出错建议温度、湿度这类展示型字段一律用String只在需要做数值比较计算的字段上才用int或double。另外NowBean是内部类时一定要写成static否则 Gson 内部类的实例化会报错这是很多人容易踩的 Gson 专属坑。4.2 RecyclerView 适配器多天预报列表怎么绑光有当前天气不够一份能看的天气预报小程序源码至少要有未来几天的预报列表。服务商一般在同一个接口里返回一个daily数组每个元素代表一天里面包含日期、最高温、最低温、白天天气状况、晚上天气状况。在布局里用 RecyclerView 来展示每行显示一个一天的预报是最常见的实现方式。// DailyAdapter.java RecyclerView适配器核心逻辑 public class DailyAdapter extends RecyclerView.AdapterDailyAdapter.ViewHolder { private ListWeatherBean.DailyBean dailyList; public DailyAdapter(ListWeatherBean.DailyBean list) { this.dailyList list; } Override public ViewHolder onCreateViewHolder(ViewGroup parent, int viewType) { View view LayoutInflater.from(parent.getContext()) .inflate(R.layout.item_daily, parent, false); return new ViewHolder(view); } Override public void onBindViewHolder(ViewHolder holder, int position) { WeatherBean.DailyBean day dailyList.get(position); holder.tvDate.setText(day.getDate()); holder.tvTemp.setText(day.getTempMin() °C ~ day.getTempMax() °C); holder.tvInfo.setText(day.getTextDay()); } Override public int getItemCount() { return dailyList null ? 0 : dailyList.size(); } static class ViewHolder extends RecyclerView.ViewHolder { TextView tvDate, tvTemp, tvInfo; ViewHolder(View itemView) { super(itemView); tvDate itemView.findViewById(R.id.tv_date); tvTemp itemView.findViewById(R.id.tv_temp); tvInfo itemView.findViewById(R.id.tv_info); } } }getItemCount里做空判断是防止列表数据还没加载时就渲染返回 0 比返回 null 安全得多。onBindViewHolder是每行数据绑定的位置注意这里只是赋值文本不要做耗时操作否则滚动时会掉帧。item_daily.xml就是普通的 LinearLayout里面放三个 TextView 横排即可。绑定到 RecyclerView 的代码放 Activity 里setLayoutManager(new LinearLayoutManager(this))是必须的忘了它 RecyclerView 不会显示任何内容而且不报错只能在 logcat 里看到一条提示这是很难排查的静默失败。4.3 城市切换和 UI 刷新的状态管理做完了列表接下来就是城市切换。最简单的做法是提供一个EditText和一个“查询”按钮用户输入城市名或城市 ID点击后重新请求数据并刷新界面。但这里有一个关键问题城市名在服务商的 API 里未必是合法的参数多数服务商要求传城市 ID而不是城市名。这就需要一个映射用户输入“北京”你查表得到101010100再拿这个 ID 去请求。而这份映射表要么自己维护要么用服务商提供的模糊搜索接口。我建议先做一个下拉框或列表选择城市而不是让用户自由输入这能避免大量输入校验工作。Activity 里维护一个String[] cityNames和对应的String[] cityIds点击城市后通过updateWeather(cityId)这个方法统一处理请求和刷新。这个方法内部做三件事先清空列表数据再发起网络请求最后在回调里更新适配器并调用notifyDataSetChanged()。清空数据这一步不能省否则用户切到新城市时看到的是上一个城市的数据直到新数据回来。这个空窗期必须处理否则会被人怀疑源码是假的。// MainActivity 中城市切换后的刷新逻辑 private void updateWeather(String cityId) { dailyList.clear(); // 先清空旧数据避免显示残留 adapter.notifyDataSetChanged(); // 通知界面立即刷新为空态 NetworkUtils.getWeather(cityId, API_KEY, new NetworkUtils.WeatherCallback() { Override public void onSuccess(String json) { WeatherBean bean new Gson().fromJson(json, WeatherBean.class); runOnUiThread(() - { dailyList.addAll(bean.getDaily()); // 新数据覆盖 adapter.notifyDataSetChanged(); // 再次刷新界面 tvUpdateTime.setText(更新于: bean.getUpdateTime()); }); } Override public void onError(String error) { runOnUiThread(() - Toast.makeText(MainActivity.this, 请求失败: error, Toast.LENGTH_SHORT).show()); } }); }这里的dailyList是 Activity 里的成员变量相当于一个“临时缓存”在界面上展示数据用。注意new Gson().fromJson(json, WeatherBean.class)这一行如果 JSON 里没有daily字段解析后bean.getDaily()会返回 null下一行addAll就崩了。稳妥的写法是在调用addAll前判空或者把实体类里daily字段初始化为new ArrayList()。这个初始化手段在 Java 里叫“字段默认值兜底”在写工具类、解析类时非常实用能省掉大量 null 判断。UI 层的代码到这一步已经完整了下一章聊真机调试时遇到的实际问题。5. 天气预报源码最常见的 6 个翻车点现象、原因、解决5.1 完全照着源码写还是报 CLEARTEXT communication not permitted现象点击查询按钮后onError回调里出现CLEARTEXT communication not permitted网络层完全没发出去请求。原因Android 9API 28开始默认禁止应用使用明文 HTTP 流量而很多免费天气接口的 URL 还是 http 开头的不是 https。解决在 AndroidManifest.xml 的 application 标签里加android:usesCleartextTraffictrue或者把 URL 改成 https 接口。Debug 阶段用前者最快上线前建议迁移到 https。还有一个隐性坑如果你的应用 targetSdkVersion 是 28 以下这个限制不生效所以很多人换台设备现象就变了本质是 targetSdkVersion 不同导致的和手机新旧没有关系。5.2 JSON 解析报错 Expected BEGIN_OBJECT but was STRING现象Gson 抛JsonSyntaxException: Expected BEGIN_OBJECT but was STRING程序直接崩溃。原因服务商返回的字段类型和实体类不一致最常见的是接口返回了一个 JSON 字符串比如{data:{\temp\:\16\}}而实体类里写的private DataBean data;。解决先在onSuccess里把原始 JSON 打印到 logcat用浏览器或在线 JSON 工具核对层级结构如果发现是字符串套对象就在解析前先把字符串层getString(data)取出再用fromJson解析内层 JSON。另一个常见场景是接口失败时返回{error:bad key}而你的实体类只定义了成功时的结构失败时因为缺字段赋 null等你要调用getDaily().size()时就空指针崩溃。所以解析后务必加一个bean.getDaily() ! null的判断。5.3 Android 6.0 以上运行时权限不弹窗直接返回失败现象在 Android 10 手机上运行界面显示“获取定位失败”或城市列表为空但在 Android 5 的旧模拟器上就正常。原因Android 6.0API 23开始ACCESS_FINE_LOCATION和ACCESS_COARSE_LOCATION属于危险权限必须在代码里动态申请只写在 manifest 里没用。解决在 Activity 里调用requestPermissions(new String[]{Manifest.permission.ACCESS_FINE_LOCATION}, 100)并在onRequestPermissionsResult回调里做后续处理。如果你的天气预报源码没有用到定位功能直接用城市列表选择那就不需要申请这两个权限很多源码在默认工程模板里带了定位相关代码但没写动态申请就会触发这一个坑。判断方法很简单看你的源码里有没有getLastKnownLocation这个方法。5.4 Gradle 同步失败Could not find com.android.tools.build:gradle:7.0.4现象打开源码后 AS 提示Could not find com.android.tools.build:gradle:7.0.4或者下载到一半显示Connect timeout。原因插件版本和本机 Gradle 版本不匹配或者网络连不上 Google 的 Maven 仓库。解决先看gradle-wrapper.properties里distributionUrl指定的 Gradle 版本再看项目级build.gradle的插件版本按我前面说的兼容关系调整。如果你在国内网络环境把build.gradle里的仓库地址改成阿里云镜像下载速度会改善很多。这个坑和天气代码无关但它是“源码跑不起来”的头号原因比任何代码 bug 都致命。5.5 模拟器上显示 HTTP 400 Bad Request但浏览器里能打开现象同样的 URL 在电脑浏览器上能返回 JSON在 Android 模拟器上就报 400 或 403。原因URL 里的中文参数没有进行 URL 编码或者 API Key 里带了特殊字符。比如?city北京keyxxx中的中文在浏览器里被自动编码了但在 OkHttp 里是原样发送的服务端不接受。解决用HttpUrl来拼接 URL或者对参数逐个调用URLEncoder.encode(param, UTF-8)。这是最容易迷惑人的一个坑因为“浏览器能打开”会让你误以为接口没问题实际上是客户端没有做编码。5.6 切换城市后界面短暂显示旧数据甚至闪一下旧数据再变新数据现象从北京切到上海界面先显示北京的天气一两秒后才变成上海。原因你的 Activity 复用了同一个dailyList集合在发起新请求前没有清空它。前面updateWeather方法里我写了dailyList.clear()就是针对这个问题。有些源码是在 onResponse 回调里才setList(bean.getDaily())在旧数据和新数据之间没有清空操作RecyclerView 会继续渲染旧列表。解决任何一次新的查询请求发出前先清空当前列表并调用notifyDataSetChanged()用“空态”占位等新数据回来再填充。如果不想让界面闪空态也可以用一个ProgressBar覆盖在列表上方请求结束后隐藏这样用户看到的是加载中而不是旧数据。6. 把天气预报小程序源码做成能自用的成品缓存、自动刷新和验证方法6.1 用 SQLite 缓存天气数据省流量也防限流免费天气接口基本都有每秒请求次数限制比如 QPS 1也就是一秒只能调一次。为了不让用户在短时间内频繁切换城市把你的配额跑光也为了在断网时还能显示上一次的天气加一个本地缓存是非常值得的。缓存方案优先选 SQLiteAndroid 自带这个能力不需要额外引库。建一张weather_cache表字段就三个city_id、json_data、update_time。查询请求发出前先读表里有没有当天的数据如果有就直接用不发起网络请求如果没有或超过 2 小时再走网络。-- weather_cache 表的建表语句 CREATE TABLE weather_cache ( city_id TEXT PRIMARY KEY, -- 城市ID主键保证一个城市只存一条 json_data TEXT NOT NULL, -- 接口返回的完整JSON原文不用拆字段存 update_time INTEGER NOT NULL -- 存时间戳判断数据是否过期 );把完整的 JSON 原文存进去而不是把解析后的字段打散存是缓存设计里最省心的做法。这样读取时不需要关心实体类有哪些字段变化直接new Gson().fromJson(cachedJson, WeatherBean.class)就还原了。时间戳用System.currentTimeMillis()存长整型判断时拿当前时间和它相减。缓存有效期设在 30 分钟比较合适太长天气不准太短退化成每次都请求。用 SQLite 做缓存的好处是免费天气接口通常也关联城市的 ID不做缓存的话App 一启动就触发一次请求而用户往往只在开启 App 的第一分钟看天气后面的刷新都是浪费。6.2 自动刷新、通知栏和真机验证方法如果想让这份源码在手机上长期使用可以加一个定时刷新。Android 里做定时任务现在推荐WorkManager它会在合适的时机批量执行比Handler.postDelayed省电得多。做法是定义一个Worker在doWork()里调用同样的网络请求和缓存更新逻辑然后通过PeriodicWorkRequestBuilder设置间隔最小间隔是 15 分钟。这一步做完App 就能实现“每天早上自动拉取最新天气用户打开就是新数据”的效果。真机验证方面我习惯在模拟器上用telnet设置模拟器经纬度来测试不同城市的定位或者在真机上换卡切换网络观察请求失败时的异常提示。更简单的办法是把手机的系统时间改到明天再打开 App 看缓存会不会失效并触发重新请求这是最快验证缓存逻辑是否正确的手段。最后的验证清单就三件事飞行模式下打开 App看能不能读取缓存显示上次天气而不白屏切换 5 个城市后再关掉网络看缓存表里这几条是否都存在用运营商网络而不是 Wi-Fi确认接口不会被运营商拦截。这三关过了这份天气预报小程序源码才能真正交付出去。做这个项目给我最大的教训是网络返回的 JSON 真的和你写代码时想象的会不一样所有解析失败都和现实数据对不上有关。任何一次改动我都先打印原始字符串再改代码希望帮到你。本文还有配套的精品资源点击获取