Skip to content

[Feature] 希望 /api/fs/list 列表接口增加底层文件唯一标识符raw_file_id #2933

Description

@sunny-00001

请确认以下事项

  • 我已确认阅读并同意 AGPL-3.0 第15条
    本程序不提供任何明示或暗示的担保,使用风险由您自行承担。

  • 我已确认阅读并同意 AGPL-3.0 第16条
    无论何种情况,版权持有人或其他分发者均不对使用本程序所造成的任何损失承担责任。

  • 我确认我的描述清晰,语法礼貌,能帮助开发者快速定位问题,并符合社区规则。

  • 我已确认阅读了OpenList文档

  • 我已确认没有重复的问题或讨论。

  • 我认为此问题必须由OpenList处理,而非第三方。

  • 我已确认此功能尚未被实现。

  • 我已确认此功能是合理的,且有普遍需求,并非我个人需要。

  • 我没有阅读这个清单,只是闭眼选中了所有的复选框,请关闭这个 Issue 。

需求描述

目前 /api/fs/list 文件列表接口返回的 id 字段为 OpenList 内部拼接生成标识,不是网盘驱动的底层真实文件 ID
存在以下问题:

  1. 文件发生重命名、移动路径之后,path+name 会发生改变,无法作为持久化的唯一标识符;
  2. 现有 id 在部分驱动下为空字符串,部分场景下会发生变动,不能用于外部程序做缓存、同步、增量比对、状态追踪;
  3. 底层驱动已经获取到真实的文件唯一 ID,但仅在 /api/fs/get 单文件接口的 raw 对象内返回,list 列表接口直接丢弃 Raw 原始数据
    如果要拿到底层 ID,只能拿到列表路径后逐个调用 /api/fs/get,目录文件数量多时会产生大量额外请求,性能很差。

希望在 list 接口每条文件对象中新增一个标准化字段,例如 raw_file_id,用于返回对应网盘驱动的底层文件唯一 ID

实现思路

  1. 模型层扩展
    model.Obj 结构体中新增公开字段 RawFileID string,驱动解析网盘返回结果时,从驱动原始返回数据(Raw)中提取对应底层唯一文件 ID,赋值给 RawFileID

各个驱动底层 ID 字段名不统一(部分叫 file_idfidid),由各驱动内部做提取适配,不在上层直接透传完整 Raw 对象,避免接口输出随驱动内部结构变化。

  1. 驱动层适配
    修改各个网盘驱动,在生成 model.Obj 对象时,优先从驱动响应原始数据解析底层文件唯一 ID,赋值给 RawFileID
    驱动无法获取底层唯一 ID 的场景,该字段留空,序列化输出自动为 null
  2. 接口序列化层(fs/list 输出)
    修改列表接口序列化逻辑(server/handles/fsread.go),将 RawFileID 加入列表接口的 JSON 输出结构,原有 idpathname 等全部字段保持原样,不破坏现有 API 兼容性

/api/fs/get 接口无需改动,维持现有 raw 对象逻辑不变。

  1. 兼容性保障
  • 已有客户端不会感知新增字段,JSON 新增字段属于向后兼容变更;
  • 不支持的驱动输出为 null,外部调用方需要做判空处理;
  • 不修改数据库、缓存逻辑,仅在接口输出层追加字段,无数据持久化变更。
  1. 边界说明
    部分网盘驱动不提供稳定全局唯一文件 ID,此时该字段返回 null,由调用方自行降级回退使用 path 做识别;
    该字段只用于外部程序做比对、索引、同步,不作为 OpenList 内部业务主键使用。

完整整合版(把【需求 + 期望行为 + 实现思路】合并,直接提交 Issue)

附加信息

参考现状:单文件接口 /api/fs/getraw 内部已经携带该信息,但各个驱动 raw 内部字段名不统一,希望服务端内部做一次适配,对外输出统一的 raw_file_id,而不是直接暴露完整 raw 对象。

AI生成内容(可选)

No response

Metadata

Metadata

Assignees

No one assigned

    Labels

    invalidInvalid Content/Cannot Reproduce

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions