Go-Shiori项目v1.6版本缓存与电子书功能升级解析

在Go-Shiori项目从v1.5升级到v1.6的过程中，缓存更新与电子书生成功能的API接口发生了显著变化。本文将从技术实现角度解析这些变更，帮助开发者更好地适配新版本。

接口变更要点

1. 端点路径重构
   原v1.5版本的/api/cache端点已被废弃，新版本统一使用RESTful风格的/api/v1/bookmarks/cache作为标准路径。这种变化体现了项目向API版本化管理的演进。

2. 参数命名规范调整
   请求体参数从驼峰式(camelCase)更改为蛇形式(snake_case)，这是为了符合大多数REST API的设计惯例：

   • createArchive → create_archive
   • createEbook → create_ebook
   • keepMetadata → keep_metadata
   • 新增skip_exist参数用于控制是否跳过已存在缓存

3. 认证机制强化
   新版要求使用标准的Bearer Token认证替代原有的X-Session-Id头部，这是为了遵循OAuth 2.0的行业标准。

典型请求示例

{
  "create_archive": true,
  "create_ebook": true,
  "ids": [1, 2, 3],
  "keep_metadata": true,
  "skip_exist": false
}

迁移建议

1. 客户端适配
   开发者需要更新客户端代码以匹配新的API规范，特别注意：

   • 端点URL的版本前缀(/v1/)
   • 参数命名的格式转换
   • 认证头的正确处理

2. 错误处理
   新版本对非法请求会返回更精确的状态码：

   • 401表示认证失败
   • 404表示资源不存在
   • 400表示参数错误

3. 功能扩展
   v1.6新增的skip_exist参数为批量处理提供了更精细的控制能力，建议在客户端实现相应选项。

技术背景

这种接口变更反映了项目向标准化REST API的演进过程。蛇形命名更符合JSON API的通用规范，而版本化端点则为后续的API演进提供了兼容性保障。认证机制的升级也提升了系统的安全性。

对于需要同时支持新旧版本的应用，建议实现API版本检测和适配层，根据服务端版本自动选择正确的通信方式。这种设计模式可以平滑过渡到新版本，同时保持向后兼容。