企业官网建设流程全解析

• 后端
• 前端
• 数据可视化

GitHub Trends 是一个基于个人 commit 数据生成代码贡献统计卡片的开源项目，它不依赖仓库的 Star 数或公共仓库整体指标，而是深入解析你每一笔提交（commit）的增删行数，按语言、按仓库、按时间段聚合出线代码量（Lines of Code，LOC）统计，并输出可动态嵌入 GitHub Profile README 的 SVG 图片。读完本文，你将掌握 GitHub Trends 的完整使用流程：注册认证（公开/私有两种工作流）、拼接 Languages 卡片与 Repositories 卡片的 API 端点与全部定制参数、切换 6 种内置主题，以及在本地运行其官方脚本直接计算统计结果而不泄露访问令牌。

本文核心文档为仓库根目录的 README.md，并融合了 docs/API.md、docs/FAQ.md、docs/THEME.md 的说明，同时对照后端源码（如 backend/src/routers/users/svg.py、backend/src/processing/user/commits.py）印证参数的实际作用与底层计算逻辑。

项目是什么：深入 GitHub API 的个人贡献指标

根据 README 的定位，GitHub Trends 会"dives deep into the GitHub API"（深入挖掘 GitHub API），为你带来关于代码贡献的指标。它可以：

• 按语言、仓库和时间三个维度统计你写下的代码行数；
• 将统计结果渲染成动态图片（SVG），方便嵌入 GitHub Profile 展示给全世界。

项目提供两类核心卡片（详见 docs/API.md）：

两者均默认展示 Top 5 项（语言卡片还会追加一个 "Other" 聚合条目），顶部子标题会显示统计时间范围、LOC 口径以及被排除的提交数。

为什么与众不同：基于 commit 而非仓库的统计口径

README 明确解释了 GitHub Trends 与其他同类项目的关键差异：很多同类项目只统计你的公开仓库整体指标，而 GitHub Trends 基于你个人的每一次 commit 来计算。这意味着：

• 如果你为开源项目提交代码，这些贡献会被准确计入你自己的名下；
• 如果你的仓库有协作者提交代码，GitHub Trends 也能区分出"你本人"写的那部分，而不是把整仓库的代码都算作你的产出。

正是通过这种口径，GitHub Trends 成为较早支持按语言、按仓库展示个人 LOC 统计的项目之一，并且配套提供了更易用的 Web 界面用于定制卡片。

从源码看，这一能力由后端多层级聚合管道支撑：src/aggregation/layer0（backend/src/aggregation/layer0）负责从 GitHub GraphQL/REST 拉取原始提交数据，src/aggregation/layer1、layer2负责用户校验与组装，最终由 backend/src/processing/user/commits.py 中的get_top_languages/get_top_repos聚合成卡片所需的数据结构。

快速开始：30 秒把卡片放进你的 Profile

按照 README 的 Quickstart，只需两步：

第一步：注册账号

访问https://api.githubtrends.io/auth/signup/public，用 GitHub 账号授权创建 GitHub Trends 账号（后面会详解公开/私有两种工作流的区别）。

第二步：粘贴 Markdown

将下面这段 Markdown 粘贴到你的 GitHub Profile README（或任意 Markdown 内容）中，把avgupta456替换成你自己的用户名：

[![GitHub Trends SVG](https://api.githubtrends.io/user/svg/avgupta456/langs)](https://githubtrends.io)

刷新页面，你就能看到自己的语言统计卡片。默认显示最近 1 个月、仅公开贡献、LOC Added（净增行数）的统计。

两种工作流：Website 与 API

README 将使用方式分为两条路径：

Website Workflow（网页工作流，Alpha）

访问githubtrends.io注册账号并开始使用；项目还提供了githubtrends.io/demo演示页，供你注册前直观感受卡片效果。前端工程位于 frontend 目录，包含 Home 定制页、Demo 页、Wrapped 页等（frontend/src/pages）。

API Workflow（API 工作流，Alpha）

如果你希望绕过网页、直接与后端 API 交互来创建和定制卡片，请参阅 docs/API.md —— 这是本文后续章节的主要内容。两种工作流共用同一套卡片渲染服务，API 工作流把可定制性完全暴露在 URL 查询参数上。

认证机制：公开与私有两种 OAuth 工作流

无论使用哪种工作流，创建卡片前都需要先注册 GitHub Trends 账号（详见 docs/API.md 的 Authentication 章节）。账号的作用是：将代表你发往 GitHub API 的查询与你的 GitHub API 配额绑定。文档承诺在几乎所有场景下消耗不超过你配额的 5%。

注册只需一次：之后的所有请求都会使用存储的 access token。两种授权级别如下：

访问对应地址后，GitHub 会提示你授权，随后（顺利的话）跳转到成功页面。

两点进阶说明（来自 docs/API.md）：

• 升级：如果之前只完成了公开工作流认证，可以直接访问私有工作流的链接来升级权限，无需另建账号；
• 注销：想删除账号时，去你的 GitHub Settings 里撤销授予 GitHub Trends 的 access token 即可（后端也提供auth/delete/{user_id}与auth/redirect/delete/{user_id}路由用于删除本地用户数据，见 backend/src/routers/auth/standalone.py）。

关于私有权限的边界问题（为什么私有工作流申请了"读写"权限但仅使用读能力），详见本文末尾的 FAQ 章节。

Languages Card：语言统计卡片

认证完成后，访问如下端点即可获取语言卡片（docs/API.md）：

https://api.githubtrends.io/user/svg/{user_id}/langs

卡片会展示你的 Top 5 语言（基于对个人与开源仓库所有提交的统计）。由于内部采用近似计算，LOC 数值会四舍五入到最接近的 100 行。

定制参数

参数以?开头、&分隔依次追加到端点后，例如：

https://api.githubtrends.io/user/svg/avgupta456/langs?time_range=three_months&include_private=true&compact=true

参数背后的源码逻辑

• time_range映射：后端在use_time_range（backend/src/utils/utils.py）中把每个取值映射为具体天数——one_month→30 天、three_months→90 天、six_months→180 天、one_year→365 天、all_time→3650 天；并生成如Past 1 Year、All Time的展示文案，显示在卡片子标题中。
• loc_metric计算口径：loc_metric_func（backend/src/processing/user/commits.py）实现为changed时返回additions + deletions（增删总行数），否则返回additions - deletions（净增行数，即 README 所称 "lines written"）。
• include_private数据源切换：为true时读取data.contribs.total_stats.languages（含私有），否则读取data.contribs.public_stats.languages。
• 排序与 Top 5：按 LOC 降序排序后取前 4 名，其余语言合并进 "Other" 聚合条；最终列表包含 Total、前 4 名与 Other。只有占比超过 1% 的条目才会被渲染。
• 卡片渲染：get_top_langs_svg（backend/src/render/top_langs.py）使用svgwrite绘制，紧凑布局（compact=true）下卡片尺寸为 300×175，普通布局为 300×285；若数据不足会渲染get_no_data_svg的占位卡片。
• 子标题信息：卡片子标题会依次追加 LOC 口径（LOC Added/LOC Changed）、统计是否完整（不完整时提示Incomplete (refresh to update)）、以及被排除的提交数（超过 50 时提示N commits excluded）。

Repositories Card：仓库统计卡片

认证完成后，访问如下端点获取仓库卡片（docs/API.md）：

https://api.githubtrends.io/user/svg/{user_id}/repos

卡片展示你在给定时间段内贡献代码行数最多的仓库（含个人与开源仓库）。

定制参数

同样以?开头、&分隔追加参数，例如：

https://api.githubtrends.io/user/svg/avgupta456/repos?time_range=one_year&include_private=true&group=private&loc_metric=changed&theme=dark

参数背后的源码逻辑

• 仓库聚合：get_top_repos（backend/src/processing/user/commits.py）遍历data.contribs.repo_stats，先按include_private过滤私有仓库；对每个仓库先粗算 LOC（各语言 LOC 之和），再剔除占比不足该仓库 5% 的语言后精算；最终按 LOC 降序保留。
• 展示条数：bars = 4（源码中标注为 TODO，后续可能开放配置），即最多展示 4 个仓库条目。
• group三种策略（backend/src/processing/user/commits.py）：
  • none：仓库数量 ≤4 时直接全部展示，否则也只取前 4；
  • other：前 3 名独立展示，其余仓库按语言合并进other/repos聚合条；
  • private：先尽力让公开仓库占据展示位（不足 4 个时用私有仓库补位），多余的公开仓库与全部私有仓库合并进聚合条。
• 卡片渲染：get_top_repos_svg（backend/src/render/top_repos.py）按仓库内各语言的占比绘制分色条形，并在底部生成语言图例。

主题定制：6 种内置主题

所有卡片（Languages 与 Repositories）均支持theme参数，可用主题如下（完整对照见 docs/THEME.md）：

用法示例：

https://api.githubtrends.io/user/svg/avgupta456/langs?theme=synthwaves

主题在渲染层通过模板函数get_template(..., theme=theme)作用于卡片的背景、文字与条形配色（backend/src/render/template.py），前端 Wrapped 组件同样复用主题体系（frontend/src/components/Wrapped/Templates/theme.js）。

本地运行官方脚本：不交出 token 也能看统计

如果你不想把 access token 交给 GitHub Trends（详见 FAQ），官方提供了完全本地的运行方案（docs/FAQ.md）：

1. 克隆本仓库；
2. 进入backend目录（backend）；
3. 安装依赖：pip install -r requirements.txt（依赖清单见 backend/requirements.txt）；
4. 运行本地脚本：

python ./scripts/local.py --user_id=USER_ID --access_token=ACCESS_TOKEN --start_date=2023-01-01 --end_date=2023-01-31 --output_dir=OUTPUT_DIR

脚本会把原始数据与加工后的 JSON写入你指定的输出目录。对照 backend/scripts/local.py 的parse_args，全部可用参数如下：

脚本的实际输出为 4 个文件（main函数，backend/scripts/local.py）：

• raw.json：get_user_data拉取并聚合后的原始数据（UserPackage模型，JSON 格式化输出）；
• langs.json：调用get_top_languages(raw_output, loc_metric="changed", include_private=True)得到的语言统计；
• repos.json：调用get_top_repos(raw_output, loc_metric="changed", include_private=True, group="none")得到的仓库统计；
• wrapped.json：调用get_wrapped_data(raw_output, 2023)生成的年度 Wrapped 数据（对应项目主页宣传的 GitHub Wrapped 功能）。

注意脚本内部固定使用loc_metric="changed"、include_private=True，因此在本地运行时你的 token 需要具备读取私有贡献的权限，才能得到与私有工作流一致的结果。

常见问题（FAQ）速览

以下内容整理自 docs/FAQ.md：

Q1：GitHub Trends 能访问我的私有代码贡献吗？

公开工作流签发的 token 仅具有公开信息的只读权限，无法查看或编辑任何私有贡献。若需分析私有贡献，请使用私有工作流。需要说明的是：由于 GitHub 平台本身不提供"只读私有访问"的 OAuth 粒度（FAQ 引用了 2015 年以来的相关 issue），私有工作流的 token 在权限声明上包含读写能力，但 GitHub Trends 实际只使用其读权限。若你对此安全边界有顾虑，请改用公开工作流。

Q2：如何让两张卡片并排显示？

在 Markdown 中使用 HTML（技巧源自 github-readme-stats 项目）：

<a href="https://githubtrends.io"> <img align="center" src="https://api.githubtrends.io/user/svg/avgupta456/langs" /> </a> <a href="https://githubtrends.io"> <img align="center" src="https://api.githubtrends.io/user/svg/avgupta456/repos" /> </a>

align="center"会让两张卡片水平对齐排列在 Profile 的同一行。

Q3：如何不交出 token 查看统计？

即上一节所述的本地脚本方案，克隆仓库后通过python ./scripts/local.py ...在本地完成拉取与计算。

Q4：遇到 bug 或想贡献代码？

项目鼓励通过 GitHub 的 issue 和 pull request 流程参与，欢迎讨论任何改进建议。

局限与注意事项

• LOC 为近似值：内部对 commit 的增删行数做了截断处理（见 backend/src/constants.py 中CUTOFF = 1000——单文件增删超过 1000 或合计超过 2000 行的 commit 会被忽略 LOC；FILE_CUTOFF = 1000控制文件级统计阈值），因此文档明确 LOC 会四舍五入到 100 行；
• 忽略部分语言：BLACKLIST = ["Jupyter Notebook", "HTML"]两种语言会被排除在统计之外；
• 公开访问限制：从 backend/src/aggregation/layer2/auth.py 可以看出，未认证的公开请求需要校验用户存在且对项目仓库点过 Star（或已在数据库注册），这是当前服务的访问控制策略，本地脚本不受此限制；
• 数据缓存与刷新：SVG 端点首次请求可能返回 Loading 占位卡，并在后台任务中完成数据拉取（见 backend/src/routers/users/svg.py 的run_in_background逻辑），子标题显示Incomplete (refresh to update)时刷新页面即可更新。

结语

GitHub Trends 的核心价值在于"以个人 commit 论英雄"：无论代码贡献给开源社区还是私有项目，它都能按语言与仓库准确归因到你名下，并以高度可定制、可嵌入的 SVG 卡片形式沉淀进你的 GitHub Profile。结合 README.md、docs/API.md、docs/FAQ.md、docs/THEME.md 四份文档，以及backend/src/processing/user/commits.py、backend/src/routers/users/svg.py等源码，你可以完整掌握从注册认证、端点拼接、参数定制、主题切换到本地脱机计算的整条使用链路。后续若需深入源码，可从 backend/src（数据层、聚合层、渲染层）与 frontend/src（网页定制界面）继续探索。

• 后端
• 前端
• 数据可视化