Runnerly应用架构设计与服务交互

# Runnerly 应用架构设计与服务交互 ## 1. 数据服务设计 ### 1.1 应用架构概述 在 Runnerly 应用中，新的应用组织架构包含了多个服务。Reports 和 Strava 服务会从 Redis 获取部分工作，并与数据服务进行交互。数据服务是一个 HTTP API，它封装了包含所有用户和跑步数据的数据库，而仪表盘则是实现 HTML 用户界面的前端。 ### 1.2 数据服务 API 设计 数据服务视图需要实现以下 API： - 对于 Strava 服务：一个用于添加跑步记录的 POST 端点。 - 对于 Reports 服务： - 一个用于检索用户 ID 列表的 GET 端点。 - 一个根据用户 ID 和月份获取跑步记录列表的 GET 端点。 HTTP API 设计遵循最小化原则，即尽可能暴露最少的入口点，并且在所有服务中共享跑步记录的结构时，也只暴露最少数量的字段。 ### 1.3 使用 Open API 2.0 Open API 2.0 规范（也称为 Swagger）是一种简单的描述语言，以 JSON 或 YAML 文件的形式呈现，它列出了所有 HTTP API 端点、使用方式以及输入输出数据的结构。以下是一个最小的 Open API 描述文件示例，定义了一个 `/apis/users_ids` 端点，并支持使用 GET 方法检索用户 ID 列表： ```yaml swagger: "2.0" info: title: Runnerly Data Service description: returns info about Runnerly license: name: APLv2 url: https://www.apache.org/licenses/LICENSE-2.0.html version: 0.1.0 basePath: /api paths: /user_ids: get: operationId: getUserIds description: Returns a list of ids produces: - application/json responses: '200': description: List of Ids schema: type: array items: type: integer ``` 使用 Swagger 描述 HTTP 端点有以下优点： - 有大量的 Open API 2.0 客户端可以使用描述文件进行有用的操作，如针对服务构建功能测试或验证发送的数据。 - 为 API 提供了标准的、与语言无关的文档。 - 服务器可以检查请求和响应是否符合规范。 ### 1.4 构建 HTTP API 的两种方式 在使用 Swagger 构建 HTTP API 时，有两种主要的方式： - **规范优先方式**：先创建 Swagger 规范文件，然后根据规范文件中的信息创建应用。例如，Connexion 框架就是基于这种原则，它通过传入规范文件和函数来生成 Flask 应用，并使用 `operationId` 字段来解析每个操作将调用的函数。 - **规范提取方式**：由代码生成 Swagger 规范文件。一些工具包可以通过读取视图文档字符串来实现这一点。 ### 1.5 Flask 应用中使用 Swagger 的示例 Flakon 项目有一个特殊的 Blueprint 类 `SwaggerBlueprint`，它不需要在规范中添加 Python 函数，也不需要根据操作来猜测函数的位置。以下是一个创建 Swagger Blueprint 并实现 `getUserIds` 操作的示例： ```python from flakon import SwaggerBlueprint api = SwaggerBlueprint('swagger', spec='api.yml') @api.operation('getUserIds') def get_user_ids(): # .. do the work .. ``` ### 1.6 应用拆分考虑 目前，已经从单体应用中拆分出了与后台任务相关的部分，并添加了一些 HTTP API 视图，以便新的微服务与主应用进行交互。还可以考虑拆分出训练功能和竞赛功能，使其成为独立的微服务，但在进行拆分时需要有充分的理由，因为每次拆分都存在使应用变得臃肿的风险。 ## 2. 服务交互 ### 2.1 服务交互类型 在 Runnerly 应用中，存在同步和异步两种服务交互方式： - **同步交互**：当用户查看主网页视图时，应用需要从数据库和竞赛数据源中获取跑步记录和竞赛列表，这些网络调用是同步的，因为需要立即显示结果。