Tdarr项目中的统计API优化与使用指南

统计API架构变更背景

Tdarr作为一款优秀的媒体文件转码管理工具，在2.24.01版本中对统计API进行了重大优化。这一变更主要针对大型媒体库的性能问题，解决了原有架构中存在的两个核心痛点：

1. 自动刷新机制导致的性能损耗：原系统每10秒至5分钟自动重新计算统计信息，当文件发生变化时会给服务器带来不必要的额外负载。实际上，大多数用户仅在查看Tdarr界面时才需要这些统计信息。

2. 数据结构设计问题：原有的统计数据结构采用了多层嵌套数组的形式，不仅难以理解，也增加了处理复杂度。

新旧API对比分析

旧版API工作方式

在2.24.01版本之前，开发者可以通过/api/v2/cruddb端点获取统计信息，请求体如下：

{
    "data": {
        "collection": "StatisticsJSONDB",
        "mode": "getById",
        "docID": "statistics",
        "obj": {}
    }
}

响应中包含一个pies数组，其中每个元素代表一个媒体库的统计信息，格式为["库名称", "库ID", 统计数值]。

新版API设计

优化后的系统引入了新的端点/api/v2/stats/get-pies，采用按需计算的策略。现在获取统计信息需要两个步骤：

1. 获取媒体库列表：

{
    "data": {
        "collection": "LibrarySettingsJSONDB",
        "mode": "getAll",
        "docID": "",
        "obj": {}
    }
}

2. 按库获取统计信息：

{
    "data": {
        "libraryId": "{具体库ID}"
    }
}

性能考量与优化建议

新版API虽然解决了后台计算的问题，但也带来了新的性能考量：

1. 响应时间：每个库的统计请求需要1-2秒处理时间，对于拥有大量媒体库的实例，完整获取所有统计信息可能需要较长时间。

2. 优化策略：

   • 实现缓存机制，仅在检测到文件总数或转码数量发生变化时才重新获取统计信息
   • 考虑并行请求多个库的统计信息（需注意服务器负载）
   • 按需获取，只请求当前关注的库统计信息

开发者适配指南

对于需要集成Tdarr统计功能的开发者，建议采用以下最佳实践：

1. 减少不必要请求：监控文件变化情况，只在必要时获取最新统计

2. 分批处理：对于大量媒体库，考虑分批获取统计信息

3. 错误处理：增加对API响应时间的超时处理和重试机制

4. 数据结构适配：新版API返回的数据结构更为清晰，开发者应相应调整解析逻辑

未来展望

根据项目维护者的说明，Tdarr将在后续版本中：

1. 进一步完善API内部逻辑，可能增加智能缓存机制
2. 推出全面的API文档更新
3. 持续优化大型媒体库场景下的性能表现

开发者可以关注这些更新，及时调整自己的集成方案以获得最佳性能和用户体验。