【免费下载链接】prehistoric-animal-museumA free, open-source bilingual 3D museum where young children and their grown-ups explore prehistoric animals across land, sea, and sky.项目地址https://gitcode.com/gh_mirrors/pr/prehistoric-animal-museum点击查看免费下载prehistoric-animal-museum 是一个免费开源的双语 3D 史前动物博物馆让小朋友和家长在陆地、海洋与天空中探索史前动物。这个项目的 README 上有一枚动态 GitHub Stars 徽章——它不是静态图片而是由一个部署在 Cloudflare Workers 上的 Worker 实时渲染每次有人点星徽章上的数字会自动更新。本文将带你完整看懂这套「实时星标徽章」的工作原理与部署方式。徽章长什么样一个会「呼吸」的 SVG徽章的最终形态是一张 240×54 像素的 SVG 图片左侧是 GitHub 的圆形小 Octocat 剪影中间写着PRIMARY REPOSITORY / GitHub右侧带一颗黄色星星和实时星标数例如857超过一万则显示为12.3k。它由 workers/github-stars-badge/badge.mjs 中的renderBadge函数在服务器端动态拼接 SVG 字符串生成——所以数字永远是服务端刚查到的真实值而不是截图。Worker 的工作原理一次请求的完整旅程核心逻辑只有约 140 行全部在 workers/github-stars-badge/index.mjs 中按请求顺序分为四步门卫检查只允许GET和HEAD方法且路径必须是/github-stars.svg其他请求直接返回 405 或 404见 index.mjs#L93-L105。先查缓存命中缓存且数据在一小时内FRESH_FOR_MS直接返回响应头标记X-Badge-Cache: HIT零 API 调用。缓存过期就「边答边刷」先立刻返回旧徽章STALE同时用waitUntil在后台悄悄拉取最新星标数并写回缓存。用户永远不会等到一次慢请求。拉取真实数据缓存未命中时调用 GitHub API 获取stargazers_count设 5 秒超时见 index.mjs#L59-L75。万一 GitHub 挂了或限流则返回写死的兜底数字 860FALLBACK_STAR_COUNT并附带Warning头说明降级徽章永远可用。缓存策略三层防护让徽章又快又稳这套 Worker 最值得学习的是它对「可用性」的执念。缓存策略配置在 index.mjs#L6-L10场景策略说明正常响应max-age3600, stale-while-revalidate86400, stale-if-error6048001 小时内必是新鲜的之后 24 小时内旧值可继续服务并在后台刷新出故障时旧值最长可用 7 天后台刷新失败静默丢弃旧徽章继续服务绝不阻塞用户GitHub 完全不可用兜底数字max-age300只缓存 5 分钟网络恢复后很快自愈另外还有一个安全细节parseStarCount会校验返回值必须是非负安全整数非法数据比如带script的注入字符串直接拒绝防止恶意响应被拼进 SVG。这条规则有专门的测试守护见 tests/github-stars-badge-worker.test.ts。项目文件结构一个 Worker 最小工程该有的样子整个 Worker 就 4 个文件非常适合作为模板参考workers/github-stars-badge/index.mjs —— 请求处理主逻辑导出fetch入口workers/github-stars-badge/badge.mjs —— 纯函数解析星标数、格式化k、渲染 SVG方便单独测试workers/github-stars-badge/wrangler.jsonc —— 部署配置绑定自定义域名badges.leon-made-this.workworkers/github-stars-badge/index.d.mts —— TypeScript 类型声明把cache、fetch、waitUntil抽象为依赖注入让核心逻辑可以被测试替换对应的测试覆盖了缓存命中、过期后台刷新、兜底降级、HEAD 方法与路径校验等场景tests/github-stars-badge-worker.test.ts。部署步骤两条命令搞定本地验证与上线git clone https://link.gitcode.com/i/a97ab75c9eb11d0c49b9015ceda6409d cd prehistoric-animal-museum npm install项目已在 package.json 中内置了两个脚本# 本地运行 Worker 测试vitest npm run test:github-stars-badge # 部署到 Cloudflare Workers使用 wrangler 4.128.0 npm run deploy:github-stars-badge部署脚本本质上是npx --yes wrangler4.128.0 deploy --config workers/github-stars-badge/wrangler.jsoncwrangler.jsonc里声明了自定义域名路由因此上线后徽章地址就是该域名下的/github-stars.svg。README 中英文版直接引用这个 URL并用一条测试锁定见 tests/github-stars-badge-worker.test.ts#L164-L174防止有人误改回静态图片。如何在自己项目里复刻这套徽章如果你想给自己的开源项目也做一枚实时星标徽章只需照搬四个关键决策Workers 纯函数渲染把「渲染」和「取数」拆到独立的纯函数文件Worker 只做编排依赖注入 vitest通过 index.d.mts 的BadgeRequestDependencies接口把缓存、时间、fetch 注入进来本地就能完整模拟缓存场景STALE-while-revalidate 缓存宁可给 1 小时前的旧数字也不让用户等 5 秒兜底值 短缓存外部 API 失效时返回写死的近似值并把缓存 TTL 压到 5 分钟故障后快速自愈。这套方案没有数据库、没有前端框架总代码量不到 200 行却做到了「永远可用、永远够新、永远安全」——这正是 Cloudflare Workers 这类无服务器环境最适合承载的轻量服务。小结要点本项目做法徽章形态服务端动态渲染 SVG数字实时数据源GitHub API5 秒超时缓存1 小时新鲜窗口 24 小时 stale 窗口 7 天容灾兜底固定星标数 8605 分钟自愈部署一条 npm 脚本调用 wrangler自定义域名路由保障vitest 全覆盖 README 引用一致性测试从 workers/github-stars-badge/ 目录抄起你也能为自己的项目装上一枚「会呼吸」的星标徽章。赞分享【免费下载链接】prehistoric-animal-museumA free, open-source bilingual 3D museum where young children and their grown-ups explore prehistoric animals across land, sea, and sky.项目地址https://gitcode.com/gh_mirrors/pr/prehistoric-animal-museum点击查看免费下载相关推荐GitHub成就徽章项目架构解析如何构建完整的徽章收集系统GitHub成就徽章项目架构解析如何构建完整的徽章收集系统 GitHub成就徽章系统是GitHub为开发者设计的个性化成就展示功能通过徽章记录开发者在开源社终极GitHub成就徽章自定义开发指南从零开始创建专属个人成就终极GitHub成就徽章自定义开发指南从零开始创建专属个人成就 GitHub成就徽章是展示开发者贡献和技能的独特方式能够让你的个人资料在众多用户中脱颖而出。badge-maker 徽章生成库实战指南Shields 官方 SVG 徽章渲染引擎解析badge maker 徽章生成库实战指南Shields 官方 SVG 徽章渲染引擎解析 导读 badge maker 是 Shields 徽章服务对外发布的开发工具后端创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考