CityMate——基于MVVM的城市信息助手

源代码地址： https://github.com/Phoenix3334/TravelAlone
项目成品及报告： https://pan.baidu.com/s/1nSKgGBaZb-W-O95fUN5aaA?pwd=3894

1. 项目介绍

CityMate 是一款基于 Android Studio 开发的轻量化城市信息助手应用，采用 Kotlin 语言构建，核心架构为 MVVM，结合 Jetpack Compose 声明式 UI 框架与 Retrofit 网络请求库，通过对接第三方开放 API 实现天气查询、城市新闻浏览、智能对话交互三大核心功能。

应用聚焦「轻量化、高可用、易扩展」设计理念，整合多源城市信息，为用户提供实时、便捷的城市生活服务，同时模块化的架构设计支持快速迭代与功能扩展。

核心功能

功能模块	核心能力
城市天气查询	输入城市名称获取实时天气、温度、风速、空气质量；展示未来4天预报；动态天气UI视觉效果
城市新闻查询	按城市维度推送头条新闻；展示标题、来源、发布时间、配图；支持点击跳转原文
智能对话助手	自然语言交互（天气/新闻咨询、常规问答）；基于 DeepSeek 大模型 API 实现；支持上下文对话

2. 开发环境

环境/工具	版本要求
操作系统	Windows 10 及以上
JDK	11+（推荐 AdoptOpenJDK / Oracle JDK）
Gradle	7.0+（项目内置 Gradle Wrapper，无需单独安装）
Android Studio	Flamingo 及以上
Android SDK	API 33 (Android 13.0 / Tiramisu)
系统镜像	Google APIs Intel x86_64 Atom System Image

3. 需求设计

3.1 功能性需求

3.1.1 天气查询子系统

项目	描述
名称	天气查询子系统
概览	基于第三方天气 API 实现城市天气信息查询，展示实时/未来天气数据
参与角色	用户、系统、第三方天气 API
基本流程	1. 用户进入天气界面 → 2. 输入城市名称提交 → 3. 输入合法性校验 → 4. 调用 API → 5. 解析数据 → 6. 界面展示
异常流程	- 城市名称无效：提示「未找到该城市天气信息」，支持重新输入 - 网络/API 失败：提示「网络异常，请重试」，保留界面状态
后置条件	成功展示天气数据；失败时仅提示错误，不影响其他功能使用

3.1.2 新闻查询子系统

项目	描述
名称	新闻查询子系统
概览	基于第三方新闻 API 推送城市相关资讯，支持列表浏览与原文跳转
参与角色	用户、系统、第三方新闻 API
基本流程	1. 用户进入新闻界面 → 2. 系统发起 API 请求 → 3. 解析数据 → 4. 列表展示新闻卡片 → 5. 点击卡片跳转原文
异常流程	- 无相关新闻：提示「暂无相关内容」，保留刷新能力 - 加载失败：提示「新闻加载失败，请重试」
后置条件	成功展示新闻列表；失败时给出提示，支持手动刷新

3.1.3 智能对话子系统

项目	描述
名称	智能对话子系统
概览	基于 DeepSeek 大模型 API 实现自然语言交互，支持天气/新闻咨询、常规问答
参与角色	用户、系统、大语言模型 API（LLM API）
基本流程	1. 用户进入对话界面 → 2. 输入并发送问题 → 3. 调用 LLM API → 4. 解析回复 → 5. 对话气泡展示
异常流程	- 输入为空：禁止发送，提示「请输入内容」 - API 请求失败：提示「服务暂不可用」 - 响应超时：展示「思考中」加载状态
后置条件	记录对话历史并展示；失败时不影响其他功能使用

3.2 非功能性需求

需求类型	具体要求
性能	- 核心功能响应 ≤ 3 秒 - 界面滑动/交互无卡顿 - 多模块并行使用无阻塞
可用性	- 界面简洁直观，操作无学习成本 - 加载/成功/失败状态有明确反馈 - 容错性强，避免程序崩溃
兼容性	- 支持 Android 8.0+ 系统 - 适配不同屏幕尺寸/分辨率 - 兼容 Wi-Fi/移动数据网络
安全性	- 采用 HTTPS 传输数据 - 校验用户输入，防止异常数据 - 隐藏 API 密钥等敏感信息
可维护/扩展性	- 模块低耦合，新增功能不影响现有逻辑 - 支持替换不同大模型服务 - 架构清晰，便于维护

3.3 其他需求

• 运行环境：Android 移动设备，依赖稳定网络连接（访问第三方 API）；
• 部署方式：APK 安装包部署，无需额外配置即可运行；
• 技术约束：遵循 MVVM 架构、Jetpack Compose 规范，依赖第三方 API 服务；
• 扩展规划：未来可新增地图/出行/生活服务模块，支持语音输入、个性化推荐等交互优化。

4. 概要设计

4.1 架构概要设计

系统采用 MVVM 三层架构设计，自上而下分为表示层、业务逻辑层、数据层，各层单向依赖、职责清晰，降低模块耦合度。

4.1.1 表示层（Presentation Layer）

作为用户交互入口，仅负责界面展示与操作传递，不包含业务逻辑。

• 核心组件：
  • UI Screens：天气/新闻/对话界面，可视化展示数据；
  • Navigation：管理页面跳转、维护界面堆栈；
  • UI State：通过 LiveData/StateFlow 监听数据变化，自动刷新界面（加载/错误/成功状态）。
• 核心逻辑：观察 ViewModel 暴露的状态数据，实现界面与数据的自动同步。

4.1.2 业务逻辑层（Business Logic Layer）

系统核心控制层，承接表示层操作、调用数据层接口、管理业务状态。

• 核心组件：
  • ViewModel：封装业务逻辑，接收用户操作，暴露可观察状态；
  • 业务状态管理：维护天气/新闻/对话数据、加载状态、错误状态等；
  • 业务协调：协调多模块流程（如查天气时同步更新新闻）；
  • 外部依赖：对接天气 API、新闻 API、DeepSeek 对话 API。

4.1.3 数据层（Data Layer）

统一管理数据获取与解析，屏蔽底层数据源细节。

• 核心组件：
  • Repository：提供统一数据访问接口，整合多源数据；
  • Network Data Source：基于 Retrofit 实现 API 请求与响应解析；
  • Data Models：定义标准化数据结构（天气/新闻/对话模型）。

4.1.4 层间交互规则

• 依赖关系：表示层 → 业务逻辑层 → 数据层（单向依赖，无反向依赖）；
• 数据流：用户操作 → 表示层 → ViewModel → Repository → 第三方 API → Repository → ViewModel → 表示层（UI 刷新）。

4.2 数据流设计

系统遵循单向数据流原则，数据流转清晰可追踪：

1. 用户在表示层发起操作（如查询天气）；
2. 表示层将操作传递至对应 ViewModel；
3. ViewModel 调用 Repository 数据接口；
4. Repository 通过 Retrofit 向第三方 API 发起请求；
5. 数据层解析返回结果，封装为标准化数据模型；
6. 结果返回至 ViewModel，更新业务状态；
7. 表示层监听状态变化，自动刷新界面展示数据。

5. 项目亮点与实现原理

5.1 技术亮点

亮点	核心优势
MVVM 架构解耦	界面/业务/数据层分离，便于测试、维护与扩展；状态驱动 UI，减少手动刷新代码
Jetpack Compose 界面	声明式 UI 开发，代码简洁易维护；支持动态主题、响应式界面效果
模块化子系统设计	天气/新闻/对话模块独立封装，新增功能无需修改现有代码
统一数据访问层	Repository 屏蔽数据源差异，上层逻辑与网络实现解耦
智能对话上下文管理	基于 ViewModel 维护对话历史，支持多轮自然交互
高容错性设计	完善的异常处理（网络/输入/API 失败），避免程序崩溃

5.2 实现原理

5.2.1 MVVM 架构落地

• Model：封装天气/新闻/对话数据模型，统一解析与存储；
• View：通过 Compose 构建界面，监听 ViewModel 状态自动刷新；
• ViewModel：隔离业务逻辑与界面，处理用户操作并更新状态，生命周期与页面解耦。

5.2.2 网络数据访问

基于 Retrofit + Gson 实现：

1. 定义 API 接口（如 WeatherApiService），声明请求方法与参数；
2. Repository 封装 API 调用逻辑，统一处理请求/响应；
3. 返回标准化数据模型，上层无需关注网络解析细节。

5.2.3 状态驱动 UI 更新

• ViewModel 暴露 StateFlow（包含加载/成功/错误状态）；
• Compose 界面通过 collectAsState() 监听状态变化；
• 数据变更触发 Compose 重组，自动更新界面，无需手动调用刷新。

5.2.4 智能对话上下文保持

• 对话子系统 ViewModel 维护 MutableStateList 存储对话历史；
• 用户发送消息时，将内容追加至历史列表并调用 LLM API；
• API 回复后，更新历史列表，界面自动刷新展示完整对话流。

6. 快速开始

6.1 环境准备

1. 安装 Android Studio Flamingo 及以上版本；
2. 配置 JDK 11+ 环境，确保 java -version 输出符合要求；
3. 下载 Android SDK API 33 及对应系统镜像。

6.2 代码拉取

git clone https://github.com/your-username/CityMate.git
cd CityMate

6.3 配置 API 密钥

在 app/src/main/res/values/strings.xml 中添加第三方 API 密钥：

<string name="weather_api_key">你的天气API密钥</string>
<string name="news_api_key">你的新闻API密钥</string>
<string name="deepseek_api_key">你的DeepSeek API密钥</string>

6.4 运行项目

1. 打开 Android Studio，导入项目；
2. 连接 Android 设备/启动模拟器（API 33+）；
3. 点击「Run ‘app’」按钮，构建并运行应用。

7. 许可证

本项目基于 MIT 协议开源，详见 LICENSE 文件。

8. 免责声明

本项目仅用于学习交流，所使用的第三方 API 需遵守对应平台的使用规范，开发者不对数据准确性、服务可用性承担责任。