如何利用 pub.dev API 构建 Dart 包分析工具：突破 30 天窗口限制
内容提要
pub.dev 的下载量仅显示30天滚动窗口，而非累计总量，发布初期高峰过后数字骤降，易被误判为包已衰退。作者发现其未公开的 metrics 接口提供52周每周下载数据，据此开发了 PubTrace，可展示任意包的完整累计下载曲线。该工具不存数据库，数据实时取自 pub.dev 官方接口，并附 curl 命令供用户自行验证。
延伸解读
下载量统计的局限性
pub.dev 显示的下载量是30天滚动窗口，而非累计总量。这意味着发布初期的下载高峰一旦超出30天，数字就会大幅下降，但这并不代表包被弃用。此外，下载量仅统计从服务器新鲜获取的次数，若用户本地缓存已存在，则不会计入。因此，下载量低估了实际使用量，且只反映近期趋势。
未公开的 metrics 接口
文章发现 pub.dev 有一个未公开但可公开访问的 metrics 接口，提供52周的每周下载数据。该接口未被官方文档支持，可能随时变更。PubTrace 利用此接口获取完整历史数据，并强调所有数据均可通过 curl 命令自行验证，无需信任第三方。
PubTrace 的设计原则
PubTrace 不存储任何数据，所有数字实时从 pub.dev 官方接口获取，并设有1小时缓存。每个页面提供验证面板，展示获取数据所用的 curl 命令，确保结果可复现。这种设计强调透明和可验证性，避免成为中间数据源。
对开发者的实用价值
对于包作者，PubTrace 展示52周累计下载曲线，帮助判断包的真实增长趋势，而非被30天窗口误导。对于求职者，可验证的累计下载数据能更有力地证明社区贡献。对于社区，可比较不同包的历史表现，辅助依赖选择。所有数据均来自 pub.dev 官方接口，无估算。
Q&A
pub.dev 上显示的下载量是累计总量吗？为什么我的包下载量会突然下降？
不是累计总量。pub.dev 显示的是最近 30 天的滚动窗口下载量，只统计过去 30 天内的下载次数。当发布初期的高峰期超出这个 30 天窗口后，数字就会大幅下降，但这并不代表包被弃用或损坏，只是窗口移动了。
pub.dev 是如何统计下载次数的？为什么下载量可能低于实际使用量？
pub.dev 统计的是包归档文件从服务器被下载的次数。当运行 pub get 或 flutter pub get 时，pub 工具会先检查本地 PUB_CACHE，如果包已缓存则不会产生下载，也就不会被计数。因此下载量反映的是开发者从服务器新鲜获取包的次数，而非使用该包的项目数量。官方文档也说明，一个包可能使用量很高但下载量相对较低，因为 pub 客户端会缓存下载。
pub.dev 有哪些官方 API 可以获取包的信息？
官方文档中记录了三个主要端点：1) GET /api/packages/{package}/score，提供 30 天滚动下载量、点赞数、pub 评分等；2) GET /api/packages/{package}，返回完整包元数据，包括所有版本、发布时间等；3) GET /api/packages/{package}/publisher，返回发布者信息。这些端点都是官方支持且文档化的。
pub.dev 的 metrics 接口是什么？它提供了哪些数据？
metrics 接口是 GET /api/packages/{package}/metrics，它不在官方文档中，但公开可访问且被 pub.dev 内部使用。它返回一个 scorecard 对象，其中包含 weeklyVersionDownloads，提供过去 52 周每周的下载数据，按版本范围细分（总下载、主版本、次版本、补丁版本）。数组有 52 个条目，索引 0 是最新一周，索引 51 是最旧一周。pub.dev 的周图表就是基于此数据。
PubTrace 是什么？它如何展示包的完整下载历史？
PubTrace 是一个免费工具，网址是 https://pubtrace.dev。它利用 pub.dev 的 metrics 接口获取 52 周每周下载数据，并计算累计下载量，生成 52 周的累计下载曲线图，展示包的真实增长轨迹。它还显示总下载量、点赞数、pub 评分和发布者信息，并提供验证面板，展示用于获取数据的 curl 命令，方便用户自行验证。
PubTrace 如何保证数据的可信度？为什么它不存储数据？
PubTrace 不存储任何数据，所有数字都是实时从 pub.dev 的 API 获取并计算的。它采用无数据库架构，避免用户需要信任中间人。每个页面都有验证面板，显示获取数据所用的 curl 命令，任何人都可以复制命令在终端运行，复现所有数字。PubTrace 只是一个计算层，数据源是 pub.dev 官方 API，因此无需信任 PubTrace 本身。
PubTrace 如何处理发布不足 52 周的包？会估算缺失数据吗？
不会估算。如果包发布不足 52 周，PubTrace 会根据实际可用的周数标注图表，例如发布 8 周就显示 8 周的历史，并明确标注。它不会外推或估计缺失的周数，只展示数据中实际存在的内容。对于超过一年的包，metrics 接口只保留 52 周数据，更早的数据不可用，PubTrace 会透明地说明这一点。
对于 Dart/Flutter 包作者，PubTrace 有什么实际帮助？
PubTrace 帮助包作者了解自己包的真实增长情况。pub.dev 上的数字只是最近 30 天的快照，而 PubTrace 展示完整的 52 周累计轨迹，让作者能判断包是在增长、稳定还是下降，并基于真实数据做决策。此外，对于求职或作品集，累计下载曲线比 pub.dev 上较低的 30 天数字更有说服力，且数据可独立验证。
