这是一份完整的Flutter应用开发教程，详细介绍了如何使用Retrofit库集成和风天气API，构建功能完善的天气预报应用。教程涵盖了从项目配置到代码实现的全部流程，特别针对鸿蒙系统进行了适配说明，为开发者提供了可直接落地的技术方案。
智能速览
Retrofit库在Flutter项目中的完整集成流程
和风天气API的数据模型定义与接口封装
天气服务的二次封装实现单例模式
首页UI与网络请求的完整交互逻辑
常见错误处理与版本兼容性解决方案
精华内容
通过Retrofit库的合理封装，不仅简化了网络请求代码，还提升了类型安全性和开发效率。下面将详细拆解整个实现过程。
依赖配置
在pubspec.yaml中添加必要依赖包，包括dio: ^5.4.0作为底层HTTP客户端，retrofit: ^4.0.3提供类型安全的API定义，json_annotation: ^4.8.1支持JSON序列化。开发依赖需要添加build_runner: ^2.4.7、json_serializable: ^6.7.1和retrofit_generator: ^10.2.1。特别注意retrofit_generator必须使用10.2.1或更高版本，否则可能遇到代码生成错误。配置完成后执行flutter pub get安装依赖。
数据模型
在lib/models/weather_models.dart中定义所有天气相关的数据模型。使用@JsonSerializable()注解标记需要序列化的类，包括Location存储城市位置信息，Now存储当前天气数据，WeatherResponse作为天气响应容器。每个模型类都必须包含fromJson和toJson方法，通过代码生成器自动实现。对于可能为空的字段，使用?标记为可空类型，避免JSON解析异常。
API接口定义
在lib/api/qweather_api.dart中使用Retrofit注解定义API接口。通过@RestApi(baseUrl)指定基础URL，使用@GET、@POST等注解定义HTTP方法，@Query和@Path注解处理参数。核心接口包括cityLookup城市搜索、weatherNow实时天气、weatherDaily每日预报和topCity热门城市查询。所有方法返回Future
服务封装
创建WeatherService类实现二次封装，采用单例模式确保全局唯一实例。在init()方法中配置Dio实例，设置10秒连接超时和接收超时，添加请求头包含API Key，并启用日志拦截器便于调试。封装后的方法如searchCity()、getCurrentWeather()简化了调用流程，统一处理错误码，提供更友好的异常信息。
首页实现
在lib/screens/home_page.dart中实现完整的天气展示功能。在initState()中初始化WeatherService并加载数据。首页包含当前天气卡片显示温度和天气状况，详细信息卡片展示风向、气压、能见度等数据，热门城市列表支持快速切换。支持下拉刷新和手动刷新，所有网络请求都通过封装的WeatherService完成，确保代码一致性。
本教程提供了完整的Flutter Retrofit天气预报应用开发方案，从基础配置到高级功能都有详细说明。掌握了这些技术，可以快速开发出稳定可靠的天气类应用。如何进一步优化用户体验和数据缓存策略，值得开发者深入思考。
