TamarFeuer/dotnet-weather-app

# WeatherAPI 这是一个小型全栈项目，旨在学习分层后端架构（ASP.NET Core）和响应式前端状态管理（Angular + NgRx）。它包含两个功能： - **某个月的典型天气**：包括温度范围、典型（平均）值和简短描述，从 JSON 文件或 SQLite 数据库读取（只需修改一行代码即可切换）。 - **荷兰城市的 5 天预报**：从免费的 [Open-Meteo](https://open-meteo.com/) API 获取实时数据，采用与月份功能相同的可切换驱动模式。 ``` GET /api/weather/typical?month=January -> { "minTemp": 1, "maxTemp": 6, "average": 3, "description": "Freezing" } GET /api/weather/cities -> ["Amsterdam", "Rotterdam", "The Hague", ...] GET /api/weather/forecast?city=Amsterdam -> [ { "date": "2026-07-03", "minTemp": 13, "maxTemp": 21, "condition": "Cloudy" }, ... ] ``` ## 目录 - [背后的设计理念](#the-ideas-behind-it) - [仓库结构](#repository-layout) - [前端](#frontend) - [后端结构](#backend-structure) - [预报请求的流转方式](#how-a-forecast-request-flows) - [切换存储方式（JSON 或 SQLite）](#swapping-storage-json-or-sqlite) - [运行项目](#running-it) - [持续集成](#continuous-integration) - [检查数据库](#inspecting-the-database) - [备注](#notes) ## 背后的设计理念 本项目主要由两种模式塑造。 **Clean Architecture** - 依赖关系向内指向：外层关注点（Web、数据库）依赖于内层关注点（业务规则），反之则不然。后端采用了一种简化的实现方式：请求流经三个层（Controller → Service → Repository），并传递纯数据模型（Temperature、City、ForecastDay、TypicalInfo）。这些模型并不是第四个步骤，而是数据本身——即最内层的环，也就是下面经典模型中心的“Entities”：  *来源：Robert C. Martin, "The Clean Architecture" (blog.cleancoder.com/uncle-bob/2012/08/13/the-clean-architecture.html)* **单向数据流** - 前端从不直接修改共享状态。组件派发一个 action，effect 处理异步工作，reducer 生成新的状态，selectors 再将其反馈给组件：一个循环，一个方向。  ## 仓库结构 本仓库包含两个并排的应用： - `weather-backend/` - ASP.NET Core API（本 README 会对此进行介绍；以下所有后端路径均相对于此文件夹） - `weather-frontend/` - Angular 应用：包含本月的典型天气以及城市预报网格，实时更新且无需刷新页面 ## 前端 `weather-frontend/` 是一个 Angular 应用。状态存在于 **NgRx** store 中（Redux 模式：actions、reducers、selectors、effects）——这是项目在它所考虑的两个选项（Signals 和 NgRx）之间做出的选择。 该 store 包含两个 slice，每个功能对应一个： - **`weather`** - 本月的典型天气。 - **`forecast`** - 城市列表以及所选城市的 5 天预报。 各个组件独立与 store 进行通信；根组件 `App` 只是承载它们的容器： - **`TypicalWeather`** - 加载时自动派发当前月份（无下拉菜单），保持月份功能在使用中。通过 `TemperatureDisplay` 显示结果。 - **`TemperatureDisplay`** - 从 store 读取月份信息，并显示范围、平均值和描述。 - **`CityPicker`** - 一个下拉菜单，其选项来自后端：加载时会派发一个 action 来获取城市列表，更改时会派发所选的城市。 - **`ForecastGrid`** - 一个容器：读取 forecast slice 并为每一天渲染一个 **`DayCard`**。 - **`DayCard`** - 展示型组件：不包含 store 逻辑；一天的数据通过 input 传入，它仅负责将其渲染出来。 ## 后端结构 在 `weather-backend/` 内部，按照职责组织了四个文件夹，每个请求都遵循 Controller → Service → Repository 的流程（Models 包含共享的数据类型）：  这两个功能都采用了相同的结构：controller 调用 service，service 调用接口背后的内容（一个“端口”），并由具体的驱动程序填充该端口。月份功能的端口是 `IMonthDataSource`（由 SQLite 或 JSON 填充）；预报功能的端口是 `IForecastSource`（由 Open-Meteo 驱动程序填充）。在 `Program.cs` 中只需修改一行代码即可切换驱动程序，应用中的其他部分完全不知情。 ## 预报请求的流转方式 一个请求从选择城市到访问实时 API 并返回的完整路径，贯穿整个 NgRx 生命周期（action → effect → reducer → selector）： ``` 1. User picks a city in the dropdown 2. 's (change) fires → CityPicker dispatches citySelected("Amsterdam") 3. The reducer sets loading: true on the forecast slice 4. The loadForecast$ effect hears citySelected and calls the frontend ForecastService.getForecast("Amsterdam") → an Observable ----------------- crosses to the backend ----------------- 5. Kestrel receives GET /api/weather/forecast?city=Amsterdam → routing → ForecastEndpoint 6. Controller calls _service.GetForecastAsync("Amsterdam") 7. ForecastService validates the city via DutchCities.Find (404 if unknown), then calls _source.GetForecastAsync(city) 8. IForecastSource → OpenMeteoForecastSource builds the Open-Meteo URL from the city's coordinates and awaits the live HTTP call 9. The driver adapts Open-Meteo's JSON (parallel arrays + WMO weather codes) into a list of our own ForecastDay objects 10. Controller returns Ok(days) → JSON array of { date, minTemp, maxTemp, condition } ----------------- response crosses back ----------------- 11. The effect's Observable emits the days; the effect dispatches forecastLoaded 12. The reducer writes the days into the forecast slice and sets loading: false 13. ForecastGrid's selectors (fed as signals) change → Angular re-renders 14. The grid renders one DayCard per day (no page refresh) ``` 月份功能遵循相同的生命周期：`TypicalWeather` 在加载时派发 `monthSelected`，effect 调用后端，`TemperatureDisplay` 从 store 读取结果。 ## 切换存储方式（JSON 或 SQLite） 月份功能的两个驱动程序位于相同的 `IMonthDataSource` 接口背后。在 `Program.cs` 中选择其中一个——注释掉一行，取消注释另一行： ``` // builder.Services.AddScoped(); // file builder.Services.AddScoped(); // SQLite (default) ``` 应用中的其他部分都不会发生改变——controller、service 和 repository 完全不知道接口背后使用的是哪种存储方式。 - **JSON driver** 读取 `Repository/months.json`。 - **SQLite driver** 使用 EF Core；数据库文件 `weather.db` 在启动时由 `EnsureCreated()` 自动创建并填充种子数据。 预报功能采用了相同的理念：`OpenMeteoForecastSource` 位于 `IForecastSource` 背后，在 `Program.cs` 中通过 `AddHttpClient` 进行配置。只需修改那一行代码，即可将其替换为带有种子数据的驱动程序。 ## 运行项目 后端，在 `weather-backend/` 目录下运行： ``` cd weather-backend dotnet run ``` 然后在浏览器中测试它（预报功能需要互联网连接，因为它会调用实时的 Open-Meteo API）： - `http://localhost:5151/api/weather/typical?month=July` - `http://localhost:5151/api/weather/cities` - `http://localhost:5151/api/weather/forecast?city=Amsterdam` 前端，在 `weather-frontend/` 目录下运行： ``` cd weather-frontend npm start # Angular dev server on http://localhost:4200 ``` 按 `Ctrl+C` 停止其中任何一个。 ## 持续集成 每次向 `main` 推送代码都会触发 Azure DevOps 中的一个流水线，该流水线在 [`azure-pipelines.yml`](azure-pipelines.yml) 中以代码形式定义。它会启动一个全新的 Microsoft 托管的 Ubuntu agent，检出仓库，安装 .NET SDK 并构建后端。如果构建失败，运行状态就会变红，这样就能自动发现有问题的代码，而不是等到下一个人拉取代码时才被发现。 这是正在逐步构建的 DevSecOps 设置的第一层。后续还将加入：前端构建、自动化测试、质量门禁（只有在流水线运行通过的情况下，拉取请求才能合并）以及安全扫描。 ## 检查数据库 当 SQLite 驱动程序处于活动状态时，你可以使用 `sqlite3` CLI 直接查看 `weather.db` 内部的内容（使用 `sudo apt install sqlite3` 安装）： ``` cd weather-backend echo "=== SELECT * FROM Temperatures ==="; sqlite3 -header -column weather.db "SELECT * FROM Temperatures;" ``` 预报功能没有本地数据库（其数据是实时的），但你可以在后端运行时直接打开端点，查看前端接收到的原始数据： ``` http://localhost:5151/api/weather/forecast?city=Amsterdam ``` ## 备注 - `weather.db` 在运行时生成（并被 git 忽略）——它会根据 `WeatherDbContext` 中的种子数据自动重建。 - 预报功能调用 Open-Meteo（免费，无需 API key）。支持的城市及其坐标列表位于 `Repository/DutchCities.cs` 中。 - 后端目标框架为 .NET 10，通过 `Microsoft.EntityFrameworkCore.Sqlite` 进行存储。前端使用 Angular 以及 `@ngrx/store`、`@ngrx/effects` 和 `@ngrx/store-devtools`。

标签：Angular, DevSecOps, EF Core, Grype, SQLite, Web API, 上游代理, 自动化攻击