Tolgee平台多键禁用状态批量查询API优化方案

背景介绍

Tolgee作为一个开源本地化平台，其API设计对开发者体验至关重要。近期平台实现了单个翻译键的禁用语言状态查询功能，但在实际使用中，开发者发现当需要同步大量翻译内容时，逐个查询键的禁用状态会导致性能问题，严重影响同步效率。

问题分析

当前实现要求开发者必须遍历每个键来获取禁用语言信息，这种设计存在两个主要缺陷：

1. 性能瓶颈：即使只有少量变更，批量操作也需要数分钟完成
2. 网络开销：每个键都需要单独请求，产生大量HTTP往返

这种设计在同步场景下尤为不利，因为同步操作通常需要检查大量键的状态差异。

解决方案探讨

针对这一问题，我们提出三种技术优化方案：

方案一：批量ID查询

扩展现有API，允许传入键ID列表（如最多1000个），后端使用SQL的IN操作符一次性查询多个键的禁用状态。这种方案：

• 实现简单，只需修改现有端点参数
• 减少网络请求次数
• 保持API风格一致

方案二：专用分页端点

设计新的getAllDisabledKeys端点，提供：

• 标准分页参数
• 可选的项目/命名空间过滤
• 一致的返回结构

这种方案更符合RESTful设计原则，但需要新增API端点。

方案三：扩展键列表API

在现有的getAllKeys端点中添加advanced参数，当设置为true时返回包含禁用语言等高级信息。这种方案：

• 复用现有端点
• 减少API数量
• 一次请求获取完整键信息
• 被认为是三种方案中的最优选

技术实现考量

无论采用哪种方案，都需要注意：

1. 性能优化：确保批量查询的数据库效率，可能需要：

   • 添加适当索引
   • 优化JOIN操作
   • 考虑缓存策略

2. API设计：

   • 保持响应结构一致
   • 明确文档说明
   • 考虑后向兼容

3. 分页处理：对于大数据集，必须实现合理分页机制

预期收益

实现批量查询后，预期将带来以下改进：

• 同步操作时间从分钟级降至秒级
• 减少服务器负载
• 提升开发者体验
• 使大规模翻译管理更加可行

结论

Tolgee平台的API设计需要兼顾灵活性和性能。通过实现多键禁用状态的批量查询，可以显著提升平台在大规模翻译管理场景下的实用性。三种方案各有优劣，但从开发者体验和实现复杂度综合考虑，扩展现有键列表API的方案最为理想。