Supabase-py 存储下载功能JSON解析异常问题分析

在Python的Supabase客户端库supabase-py中，用户报告了一个关于存储下载功能的异常问题。当尝试从存储桶下载文件时，系统会抛出JSON解析错误，导致下载操作失败。

问题现象

开发人员在使用supabase-py的storage模块时，调用download方法获取文件内容时遇到了以下异常：

json.decoder.JSONDecodeError: Expecting value: line 1 column 1 (char 0)

同样的错误也出现在调用list方法时。该问题在版本2.3.6至2.4.0中均有出现。

技术分析

深入分析问题根源，我们发现这是由于HTTP响应处理逻辑中的一个设计缺陷导致的。当storage API返回非JSON格式的响应时（如二进制文件内容），代码仍尝试将其解析为JSON，从而触发了解析异常。

具体来说，在storage3/_sync/file_api.py文件中，第49行代码无条件地对响应内容执行了JSON解析：

{**response.json(), "statusCode": response.status_code}

解决方案

开发团队迅速响应并发布了修复版本。主要改进包括：

1. 在0.7.1版本中增加了对非JSON响应的处理逻辑
2. 在0.7.3版本中修复了因缺少JSONDecodeError导入导致的NameError问题

修复后的代码会先检查响应内容类型，仅对确实包含JSON数据的响应执行解析操作，从而避免了不必要的解析异常。

最佳实践建议

对于使用supabase-py存储模块的开发者，我们建议：

1. 确保使用最新版本的supabase-py客户端库
2. 对于受RLS保护的存储桶，确保在请求时提供了正确的认证信息
3. 实现适当的错误处理和重试机制，特别是对于可能返回403错误的场景
4. 对于文件下载操作，预期响应可能是二进制数据而非JSON格式

总结

这个问题的解决展示了开源社区快速响应和修复问题的能力。通过版本迭代，supabase-py现在能够更健壮地处理各种类型的存储API响应，为开发者提供了更稳定的文件操作体验。建议所有用户升级到最新版本以获得这些改进。