LANraragi API中单本漫画集端点返回错误计数问题分析

问题概述

在LANraragi项目的API设计中，获取单本漫画集(tankoubon)的端点(GET /api/tankoubons/:id)存在计数不准确的问题。该端点返回的JSON响应中包含两个关键计数字段：total和filtered，但当前实现中存在数值计算错误。

技术细节

错误表现

当调用该API端点时，返回的JSON结构中：

1. total字段总是比实际关联的漫画档案(archives)数量多2
2. 对于空漫画集(无任何档案)，total返回2而非预期的0
3. 对于包含1个档案的漫画集，total返回3而非预期的1

预期行为

按照API设计规范，这两个字段应该表示：

• total: 该漫画集关联的档案总数
• filtered: 当前返回结果中实际包含的档案数量(考虑分页等因素)

问题根源

经过代码分析，发现计数错误源于实现逻辑中的两个问题：

1. 在计算总数时，错误地将某些元数据字段也计入了总数
2. 对数据结构处理不当，导致额外计数

影响范围

该问题影响所有使用此API端点的客户端应用，特别是：

• 依赖准确计数的分页功能
• 需要精确显示漫画集内容数量的前端界面
• 自动化处理流程中基于计数的逻辑判断

解决方案

开发团队已通过以下方式修复此问题：

1. 修正计数逻辑，确保只统计实际的漫画档案
2. 保持API响应结构的稳定性，不改变字段名称
3. 确保total和filtered字段的含义在整个API中保持一致

最佳实践建议

对于API使用者，建议：

1. 始终验证关键计数字段的准确性
2. 对于重要业务逻辑，考虑添加额外的验证层
3. 关注API版本更新，及时适配修复后的行为

总结

计数准确性是API可靠性的重要指标。LANraragi团队对此问题的快速响应体现了对API质量的重视。用户升级到修复版本后即可获得正确的计数行为，无需修改现有代码。