卡片生成系统

相关源文件

• api/index.js
• api/pin.js
• src/common/utils.js

卡片生成系统是 GitHub Readme Stats 的核心组件，它将用户数据转换为视觉上吸引人的 SVG 卡片。该系统处理从接收 API 请求到生成可嵌入 GitHub README 文件中的 SVG 图像的整个过程。

有关特定卡片类型的信息，请参阅统计卡片、仓库卡片、热门语言卡片、WakaTime 卡片和Gist 卡片。

卡片生成工作流程

卡片生成过程遵循所有卡片类型的一致模式

来源：api/index.js13-138 api/pin.js12-105

工作流程包括以下主要步骤

1. API 请求：系统接收带有查询参数的 HTTP 请求
2. 参数解析：提取查询参数并解析为适当的类型
3. 验证：验证参数的正确性
4. 数据获取：从 GitHub API 或其他来源检索数据
5. SVG 渲染：数据转换为 SVG 卡片
6. 响应：SVG 发送回客户端

卡片类型和 API 端点

系统支持多种卡片类型，每种类型都有自己的 API 端点

来源：api/index.js1-10 api/pin.js1-10

每种卡片类型都遵循相同的模式：

1. API 端点接收请求
2. 专门的抓取器检索数据
3. 专用渲染器将数据转换为 SVG

卡片组件和渲染

所有卡片共享通用组件和渲染实用程序

来源：src/common/utils.js20-326

基础卡片组件

基础卡片组件为所有卡片类型提供基础，包括：

• 具有适当尺寸的 SVG 容器
• 基于主题的背景样式
• 可定制圆角的边框
• 标题和内容容器

通用工具

该系统包括用于卡片生成的几个实用程序：

实用工具	目的
flexLayout()	水平或垂直排列元素并提供适当的间距
createLanguageNode()	创建编程语言的视觉表示
iconWithLabel()	结合图标和文本标签用于统计
getCardColors()	检索基于主题的颜色并进行适当的覆盖
renderError()	在出现问题时生成错误卡片
wrapTextMultiline()	处理描述的文本换行

来源：src/common/utils.js53-65 src/common/utils.js74-81 src/common/utils.js92-110 src/common/utils.js267-326 src/common/utils.js360-401 src/common/utils.js411-436

数据获取

每种卡片类型都有一个专用抓取器，用于从适当的来源检索数据

来源：api/index.js68-78 api/pin.js57

抓取器处理：

• API 身份验证
• 请求的构建
• 响应的解析
• 数据转换

主题应用

主题通过颜色系统应用于卡片

来源：src/common/utils.js267-326

getCardColors() 函数管理主题应用：

1. 检索默认主题或选定主题
2. 应用查询参数中的任何颜色覆盖
3. 验证颜色并在需要时回退到默认值
4. 返回渲染器使用的完整颜色对象

错误处理

系统包括强大的错误处理功能

来源：api/index.js121-137 api/pin.js88-104 src/common/utils.js23-40 src/common/utils.js360-401

错误处理系统

• 捕获处理过程中的所有异常
• 针对特定问题使用自定义错误类型
• 为用户提供有用的错误消息
• 渲染标准化错误卡片
• 为错误设置适当的缓存头

自定义选项

卡片生成系统通过查询参数支持广泛的定制

参数类别	示例	目的
内容控制	hide, show, include_all_commits	控制显示的数据
视觉样式	title_color, text_color, bg_color	自定义卡片外观
布局	card_width, border_radius, line_height	调整卡片尺寸
定位	locale	设置卡片语言
动画	disable_animations	控制动画效果

来源：api/index.js14-41 api/pin.js13-28

缓存系统

为了优化性能和降低 API 调用限制，系统实现了一种缓存策略

来源：api/index.js80-92 api/pin.js59-71 src/common/utils.js443-477

缓存系统：

• 为不同卡片类型使用不同的缓存持续时间
• 允许通过查询参数覆盖缓存持续时间
• 对错误实现更短的缓存时间
• 使用环境变量进行全局缓存控制

此缓存策略平衡了数据的新鲜度与性能和速率限制之间的关系。