feat(driver/cloudflare-imgbed): enhance cloudflare_imgbed API integration with improved error handling and pagination

Author: ZZ0YY

drivers/cloudflare_imgbed/driver.go

@@ -9,6 +9,7 @@ import (
 	"github.com/OpenListTeam/OpenList/v4/internal/driver"
 	"github.com/OpenListTeam/OpenList/v4/internal/errs"
 	"github.com/OpenListTeam/OpenList/v4/internal/model"
+	"github.com/OpenListTeam/OpenList/v4/pkg/utils"
 	"github.com/go-resty/resty/v2"
 )
 
@@ -26,7 +27,8 @@ func (d *CFImgBed) GetAddition() driver.Additional {
 	return &d.Addition
 }
 
-// Init initializes the HTTP client with the configured Address and Token.
+// Init 使用 base 包提供的工厂方法初始化 HTTP 客户端，
+// 并设置 API 基础地址和鉴权请求头。
 func (d *CFImgBed) Init(ctx context.Context) error {
 	d.client = base.NewRestyClient()
 	d.client.SetBaseURL(strings.TrimRight(d.Address, "/")).
@@ -39,37 +41,41 @@ func (d *CFImgBed) Drop(ctx context.Context) error {
 	return nil
 }
 
-// apiError represents a generic error response from the CFImgBed API.
+// apiError 表示 CFImgBed API 返回的通用错误响应结构。
 type apiError struct {
 	Error   string `json:"error"`
 	Message string `json:"message"`
 }
 
-// buildReqPath constructs the path to send to the CFImgBed List API.
+// buildReqPath 根据挂载根路径和当前浏览目录，拼接出发送给 API 的请求路径。
 //
-// OpenList may call List() in two ways:
-//  1. List(nil) — initial load of the mount root
-//  2. List(obj) — where obj was returned by a previous List() call
+// OpenList 可能在两种场景下调用 List：
+//  1. List(nil) — 首次加载挂载点根目录
+//  2. List(obj) — 用户点击进入某个子目录，obj 由上一次 List 返回
 //
-// When RootPath is set (e.g. "/telegram"), OpenList may pass a virtual root
-// dir object whose GetPath() already equals the root path itself. We must
-// detect this and avoid double-prepending rootPath.
+// 当设置了 RootPath（如 "/telegram"）时，OpenList 首次调用的 dir 对象
+// 的 GetPath() 可能已经等于 rootPath 本身，此时不应重复拼接前缀。
 func buildReqPath(rootPath, dirPath string) string {
 	rootPath = strings.Trim(rootPath, "/")
 	dirPath = strings.Trim(dirPath, "/")
 
 	if dirPath == "" || dirPath == rootPath {
-		// Either listing the real root, or OpenList passed the virtual root dir
+		// 正在浏览根目录，或 OpenList 传入了虚拟根目录对象
 		return rootPath
 	}
 	if rootPath == "" {
+		// 未设置挂载前缀，直接使用目录路径
 		return dirPath
 	}
-	// dirPath is a subfolder returned by a previous List call, prepend rootPath
+	// 正常子目录：在目录路径前补上挂载根路径
 	return rootPath + "/" + dirPath
 }
 
-// List retrieves the file and directory listing for the given directory.
+// List 获取指定目录下的文件和子目录列表。
+//
+// 采用内部分页循环拉取，以防止单目录文件过多导致 API 响应超时或内存异常。
+// 每次请求 listPageSize 条记录，直到返回数量不足一页时退出循环，
+// 最终将所有分页结果汇总后一次性返回给 OpenList。
 func (d *CFImgBed) List(ctx context.Context, dir model.Obj, args model.ListArgs) ([]model.Obj, error) {
 	rootPath := strings.Trim(d.GetRootPath(), "/")
 
@@ -79,48 +85,69 @@ func (d *CFImgBed) List(ctx context.Context, dir model.Obj, args model.ListArgs)
 	}
 	reqPath := buildReqPath(rootPath, dirPath)
 
-	var resp ListResponse
-	var errResp apiError
-	res, err := d.client.R().
-		SetQueryParam("dir", reqPath).
-		SetQueryParam("count", "-1").
-		SetResult(&resp).
-		SetError(&errResp).
-		Get("/api/manage/list")
-
-	if err != nil {
-		return nil, err
-	}
-	if res.IsError() {
-		if errResp.Message != "" {
-			return nil, fmt.Errorf("CFImgBed API error: %s", errResp.Message)
+	// 用于去重：API 在分页时每个页面都可能重复返回相同的目录列表，
+	// 使用 map 确保同一个目录对象只被添加一次。
+	dirSeen := make(map[string]bool)
+	objs := make([]model.Obj, 0)
+
+	// 分页拉取循环
+	start := 0
+	for {
+		var resp ListResponse
+		var errResp apiError
+		res, err := d.client.R().
+			SetQueryParam("dir", reqPath).
+			SetQueryParam("start", fmt.Sprintf("%d", start)).
+			SetQueryParam("count", fmt.Sprintf("%d", listPageSize)).
+			SetResult(&resp).
+			SetError(&errResp).
+			Get("/api/manage/list")
+
+		if err != nil {
+			return nil, err
+		}
+		if res.IsError() {
+			if errResp.Message != "" {
+				return nil, fmt.Errorf("CFImgBed API error: %s", errResp.Message)
+			}
+			return nil, fmt.Errorf("CFImgBed API returned status %d", res.StatusCode())
 		}
-		return nil, fmt.Errorf("CFImgBed API returned status %d", res.StatusCode())
-	}
 
-	objs := make([]model.Obj, 0, len(resp.Directories)+len(resp.Files))
+		// 裁剪 API 返回路径中的挂载根前缀，
+		// 使 GetPath() 返回的是相对于 OpenList 挂载点的路径，而非图床的绝对路径。
+		for _, rawDir := range resp.Directories {
+			cleanDir := strings.TrimRight(rawDir, "/")
+			p := stripRootPrefix(cleanDir, rootPath)
+			// 目录去重：分页场景下不同页面可能返回相同的目录条目
+			if !dirSeen[p] {
+				dirSeen[p] = true
+				objs = append(objs, parseDir(p))
+			}
+		}
 
-	// Strip rootPath prefix from returned paths so that GetPath() is relative
-	// to the OpenList mount point, not the CFImgBed root.
-	for _, rawDir := range resp.Directories {
-		cleanDir := strings.TrimRight(rawDir, "/")
-		p := stripRootPrefix(cleanDir, rootPath)
-		objs = append(objs, parseDir(p))
-	}
+		for _, item := range resp.Files {
+			p := stripRootPrefix(item.Name, rootPath)
+			objs = append(objs, parseFile(FileItem{
+				Name:     p,
+				Metadata: item.Metadata,
+			}))
+		}
+
+		// 判断是否已到最后一页：当返回的文件和目录总数小于请求的每页数量时，
+		// 说明本页已经是最后一页，无需继续请求。
+		fetched := len(resp.Files) + len(resp.Directories)
+		if fetched < listPageSize {
+			break
+		}
 
-	for _, item := range resp.Files {
-		p := stripRootPrefix(item.Name, rootPath)
-		objs = append(objs, parseFile(FileItem{
-			Name:     p,
-			Metadata: item.Metadata,
-		}))
+		start += listPageSize
 	}
 
 	return objs, nil
 }
 
-// stripRootPrefix removes the rootPath prefix from a path returned by the API.
-// If rootPath is empty or the path doesn't start with rootPath/, return as-is.
+// stripRootPrefix 移除 API 返回路径中的挂载根前缀。
+// 如果未设置 rootPath 或路径不以 rootPath/ 开头，则原样返回。
 func stripRootPrefix(p, rootPath string) string {
 	if rootPath == "" {
 		return p
@@ -132,12 +159,13 @@ func stripRootPrefix(p, rootPath string) string {
 	return p
 }
 
-// Link constructs a direct download URL for the given file object.
-// Format: {Address}/file/{rootPath}/{filePath} with no double slashes.
+// Link 拼装文件的直接下载/访问链接。
+// 路径中可能包含空格、中文、#、+ 等特殊字符，必须进行安全编码以生成有效 URL。
 func (d *CFImgBed) Link(ctx context.Context, file model.Obj, args model.LinkArgs) (*model.Link, error) {
 	rootPath := strings.Trim(d.GetRootPath(), "/")
 	filePath := strings.Trim(file.GetPath(), "/")
 
+	// 拼接完整路径，避免出现双斜杠
 	var fullPath string
 	if rootPath != "" && filePath != "" {
 		fullPath = rootPath + "/" + filePath
@@ -147,7 +175,8 @@ func (d *CFImgBed) Link(ctx context.Context, file model.Obj, args model.LinkArgs
 		fullPath = filePath
 	}
 
-	link := strings.TrimRight(d.Address, "/") + "/file/" + fullPath
+	// 对路径进行安全编码，处理空格、特殊字符等可能导致链接失效的情况
+	link := strings.TrimRight(d.Address, "/") + "/file/" + utils.EncodePath(fullPath)
 	return &model.Link{URL: link}, nil
 }
 
@@ -195,4 +224,5 @@ func (d *CFImgBed) GetDetails(ctx context.Context) (*model.StorageDetails, error
 	return nil, errs.NotImplement
 }
 
+// 编译时检查 CFImgBed 是否完整实现 driver.Driver 接口。
 var _ driver.Driver = (*CFImgBed)(nil)

drivers/cloudflare_imgbed/meta.go

@@ -5,6 +5,7 @@ import (
 	"github.com/OpenListTeam/OpenList/v4/internal/op"
 )
 
+// Addition 定义驱动在 OpenList 前端管理界面中显示的表单配置项。
 type Addition struct {
 	driver.RootPath
 	Address string `json:"address" type:"text" required:"true" default:"" help:"API domain, https://img.example.com"`

drivers/cloudflare_imgbed/types.go

@@ -10,64 +10,67 @@ import (
 	"github.com/OpenListTeam/OpenList/v4/pkg/utils"
 )
 
-// File represents a file object parsed from the CFImgBed List API response.
-// It implements the model.Obj interface.
+// File 表示从 CFImgBed 列表 API 响应中解析出的文件对象，实现 model.Obj 接口。
 type File struct {
-	Path     string
-	Name_    string
-	Size_    int64
-	ModTime_ time.Time
-	Mime_    string
+	path    string    // 文件相对路径，如 "example/image.jpg"
+	name    string    // 显示名称（路径最后一段），如 "image.jpg"
+	size    int64     // 文件大小（字节）
+	modTime time.Time // 最后修改时间（从 Unix 毫秒时间戳转换而来）
+	mime    string    // MIME 类型，如 "image/jpeg"
 }
 
-func (f *File) GetPath() string         { return f.Path }
-func (f *File) GetName() string         { return f.Name_ }
-func (f *File) ModTime() time.Time      { return f.ModTime_ }
-func (f *File) CreateTime() time.Time   { return f.ModTime_ }
-func (f *File) GetSize() int64          { return f.Size_ }
+func (f *File) GetPath() string         { return f.path }
+func (f *File) GetName() string         { return f.name }
+func (f *File) ModTime() time.Time      { return f.modTime }
+func (f *File) CreateTime() time.Time   { return f.modTime }
+func (f *File) GetSize() int64          { return f.size }
 func (f *File) IsDir() bool             { return false }
-func (f *File) GetID() string           { return f.Path }
+func (f *File) GetID() string           { return f.path }
 func (f *File) GetHash() utils.HashInfo { return utils.HashInfo{} }
 
-// Dir represents a directory object parsed from the CFImgBed List API response.
-// It implements the model.Obj interface.
+// Dir 表示从 CFImgBed 列表 API 响应中解析出的目录对象，实现 model.Obj 接口。
 type Dir struct {
-	Path  string
-	Name_ string
+	path string // 目录相对路径，如 "example/subfolder"
+	name string // 显示名称（路径最后一段），如 "subfolder"
 }
 
-func (d *Dir) GetPath() string         { return d.Path }
-func (d *Dir) GetName() string         { return d.Name_ }
+func (d *Dir) GetPath() string         { return d.path }
+func (d *Dir) GetName() string         { return d.name }
 func (d *Dir) ModTime() time.Time      { return time.Time{} }
 func (d *Dir) CreateTime() time.Time   { return time.Time{} }
 func (d *Dir) GetSize() int64          { return 0 }
 func (d *Dir) IsDir() bool             { return true }
-func (d *Dir) GetID() string           { return d.Path }
+func (d *Dir) GetID() string           { return d.path }
 func (d *Dir) GetHash() utils.HashInfo { return utils.HashInfo{} }
 
-// Compile-time checks to ensure File and Dir implement model.Obj.
+// 编译时检查 File 和 Dir 是否完整实现 model.Obj 接口。
 var _ model.Obj = (*File)(nil)
 var _ model.Obj = (*Dir)(nil)
 
-// ListResponse represents the JSON structure returned by the CFImgBed List API.
+// listPageSize 定义每次向 API 请求的最大条目数。
+// 采用内部分页循环拉取，以防止单目录文件过多导致 API 响应超时或内存异常。
+const listPageSize = 1000
+
+// ListResponse 表示 CFImgBed 列表 API 返回的 JSON 结构。
 type ListResponse struct {
 	Files       []FileItem `json:"files"`
 	Directories []string   `json:"directories"`
 }
 
-// FileItem represents a single file entry in the List API response.
-// Metadata uses map[string]interface{} because the actual API returns mixed types:
-//   - TimeStamp: integer (e.g. 1774910085474) in newer versions
-//   - FileSizeBytes: integer (e.g. 3936071)
-//   - FileSize: string (e.g. "3.75") — human-readable size
-//   - FileType: string (e.g. "audio/mpeg")
-//   - Legacy fields may use string values for numbers
+// FileItem 表示列表 API 返回的单个文件条目。
+// 注意：Metadata 使用 map[string]interface{} 而非 map[string]string，
+// 因为实际 API 返回的字段类型不统一：
+//   - TimeStamp: 可能是整数（如 1774910085474），也可能在旧版本中是字符串
+//   - FileSizeBytes: 整数（如 3936071）
+//   - FileSize: 字符串（如 "3.75"）— 仅供人类阅读的格式化大小
+//   - FileType: 字符串（如 "audio/mpeg"）
 type FileItem struct {
 	Name     string                 `json:"name"`
 	Metadata map[string]interface{} `json:"metadata"`
 }
 
-// getString safely extracts a string value from metadata, trying key in order.
+// getString 从 metadata 中安全提取字符串值，按 keys 顺序依次尝试。
+// 支持 string 和 float64（JSON 数字反序列化后的默认类型）两种输入。
 func getString(m map[string]interface{}, keys ...string) string {
 	for _, k := range keys {
 		if v, ok := m[k]; ok {
@@ -84,8 +87,9 @@ func getString(m map[string]interface{}, keys ...string) string {
 	return ""
 }
 
-// getInt64 safely extracts an int64 value from metadata, trying key in order.
-// Supports string, float64 (JSON number), and int64 types.
+// getInt64 从 metadata 中安全提取 int64 值，按 keys 顺序依次尝试。
+// 同时兼容 string、float64（JSON 数字）和 int64 三种反序列化类型，
+// 确保在不同 API 版本下均能正确解析。
 func getInt64(m map[string]interface{}, keys ...string) int64 {
 	for _, k := range keys {
 		if v, ok := m[k]; ok {
@@ -103,44 +107,40 @@ func getInt64(m map[string]interface{}, keys ...string) int64 {
 	return 0
 }
 
-// parseFile converts an API FileItem to a *File model.Obj.
-// It tries multiple key names for each field to handle different API versions:
-//   - Size: FileSizeBytes (int) > File-Size (string)
-//   - MIME: FileType > File-Mime
-//   - Time: TimeStamp (handles both int and string)
+// parseFile 将 API 返回的 FileItem 转换为 *File 对象。
+// 字段提取策略（兼容新旧 API 版本）：
+//   - 文件大小：优先取 FileSizeBytes（int），回退到 File-Size（string）
+//   - MIME 类型：优先取 FileType，回退到 File-Mime
+//   - 修改时间：取 TimeStamp（同时处理 int 和 string 两种格式）
 func parseFile(item FileItem) *File {
 	name := path.Base(item.Name)
 	var size int64
 	var modTime time.Time
 	var mime string
 
 	if item.Metadata != nil {
-		// Try FileSizeBytes (int) first, fall back to File-Size (string)
 		size = getInt64(item.Metadata, "FileSizeBytes", "File-Size")
-
-		// Try FileType first, fall back to File-Mime
 		mime = getString(item.Metadata, "FileType", "File-Mime")
-
-		// TimeStamp may be int or string depending on API version
 		ts := getInt64(item.Metadata, "TimeStamp")
 		if ts > 0 {
 			modTime = time.UnixMilli(ts)
 		}
 	}
 
 	return &File{
-		Path:     item.Name,
-		Name_:    name,
-		Size_:    size,
-		ModTime_: modTime,
-		Mime_:    mime,
+		path:    item.Name,
+		name:    name,
+		size:    size,
+		modTime: modTime,
+		mime:    mime,
 	}
 }
 
-// parseDir converts a directory path string from the API to a *Dir model.Obj.
+// parseDir 将 API 返回的目录路径字符串转换为 *Dir 对象。
+// 显示名称取路径的最后一段（即最深层目录名）。
 func parseDir(dirPath string) *Dir {
 	return &Dir{
-		Path:  dirPath,
-		Name_: path.Base(dirPath),
+		path: dirPath,
+		name: path.Base(dirPath),
 	}
 }