本文档描述了GitHub Readme Stats的整体架构，该服务生成动态SVG卡片，在README文件中显示各种GitHub统计信息。它全面概述了系统组件、它们之间的交互以及从请求到响应的数据流。
有关特定卡片类型及其生成的信息，请参阅卡片生成系统。
GitHub Readme Stats构建为一个无服务器应用程序，通过API端点按需生成SVG图像。该系统设计为无状态的，每个请求独立处理。其架构遵循模块化模式，并在数据获取、处理和渲染组件之间进行了清晰的分离。
此架构的主要目标是提供一个响应式、可定制的系统，该系统能够检索GitHub统计信息并将其渲染成视觉上吸引人的SVG卡片。
来源
系统通过以下流程处理请求
来源
API层是所有请求进入系统的入口点。它负责参数解析、验证，并协调数据获取和渲染过程。
GitHub Readme Stats公开了多个API端点，每个端点负责生成特定类型的卡片
| 端点 | 目的 | 主要参数 | 处理文件 |
|---|---|---|---|
/api | 统计卡片 | username | api/index.js |
/api/pin | 仓库卡片 | username, repo | api/pin.js |
/api/top-langs | 热门语言 | username | 未在文件中显示 |
/api/wakatime | WakaTime统计 | username | 未在文件中显示 |
/api/gist | Gist卡片 | id | 未在文件中显示 |
每个端点都遵循类似的请求处理模式
来源
系统支持众多参数来定制卡片的显示效果。这些参数从请求查询字符串中提取，并在传递给渲染函数之前进行预处理。
常见参数包括
| 参数类别 | 示例 | 处理函数 |
|---|---|---|
| 布尔值标志 | hide_border, show_icons | parseBoolean() |
| 列表 | hide, exclude_repo | parseArray() |
| 颜色 | title_color, text_color | fallbackColor() |
| 主题 | theme | getCardColors() |
| 本地化 | locale | isLocaleAvailable() |
来源
数据获取层负责从GitHub和WakaTime等外部API检索数据。
该系统使用GitHub的GraphQL API进行高效数据检索，并在需要时回退到REST API。
来源
系统使用GitHub个人访问令牌（PATs）进行身份验证，以避免速率限制问题。可以配置多个令牌以实现负载平衡。
渲染层将获取的数据转换为SVG卡片。
每种卡片类型都有其专用的渲染函数
来源
卡片生成为SVG字符串，这允许
渲染过程广泛使用实用函数进行
来源
该系统根据各种指标计算用户的GitHub排名
排名计算使用加权指标，并结合指数和对数正态累积分布函数来确定用户的级别（S、A+、A、A-、B+、B、B-、C+、C）和百分位。
来源
主题系统为所有卡片提供了一致的样式
来源
系统通过翻译系统支持多种语言
来源
系统包含许多支持核心功能的实用函数
| 功能 | 目的 | 位置 |
|---|---|---|
kFormatter() | 格式化大数字（1.5k） | src/common/utils.js118-122 |
encodeHTML() | HTML编码字符串 | src/common/utils.js339-345 |
isValidHexColor() | 验证颜色字符串 | src/common/utils.js130-134 |
fallbackColor() | 应用颜色回退 | src/common/utils.js206-218 |
flexLayout() | 定位SVG元素 | src/common/utils.js53-65 |
wrapTextMultiline() | 以换行格式化文本 | src/common/utils.js411-436 |
来源
系统采用缓存策略，以减少 API 调用并提高性能
不同卡片类型的缓存时长不同，取决于其数据预期的更改频率
| 卡片类型 | 默认缓存时长 | 常量 |
|---|---|---|
| 统计卡片 | 1天 | CARD_CACHE_SECONDS |
| 热门语言 | 6天 | TOP_LANGS_CACHE_SECONDS |
| 置顶卡片 | 10天 | PIN_CARD_CACHE_SECONDS |
| 错误响应 | 10分钟 | ERROR_CACHE_SECONDS |
来源
系统实施了全面的错误处理
错误卡片包括：
来源
系统包含全面的测试，包括：
端到端测试可验证已部署的实例是否与本地渲染函数的预期输出相匹配。
来源
系统使用 Husky hooks 和 GitHub Actions 进行 CI/CD
来源
GitHub Readme Stats 架构展示了一个结构良好、模块化的系统，用于动态生成 SVG 卡片。API 处理、数据获取和渲染之间清晰的划分使得系统易于维护和扩展。
实用函数、主题和国际化功能的运用，在保持代码模式一致性的同时，为用户提供了灵活且可定制的体验。