OpenList Spring Boot Auto Configuration Starter

OpenList API 的 Spring Boot 自动配置 Starter，通过简单的配置和自动注入即可在 Java 项目中调用 OpenList 的全部 REST API。

快速开始

1. 添加 Maven 依赖

<dependency>
    <groupId>com.echovale</groupId>
    <artifactId>openlist-spring-boot-auto-configuration</artifactId>
    <version>dev-1.0</version>
</dependency>

2. 配置 application.yaml

openlist:
  base-url: https://your-openlist-server:5244
  username: admin
  password: your-password
  # otp-code: 123456           # 如果启用了两步验证，请取消注释并填写验证码
  connect-timeout: 10s          # 连接超时，默认 10s
  read-timeout: 30s             # 读取超时，默认 30s

3. 注入并使用

@Service
public class MyService {

    @Autowired
    private OpenListClient openListClient;

    public void doSomething() {
        // 获取根目录文件列表
        FileListResponse files = openListClient.listFiles("/");
        files.getContent().forEach(item ->
            System.out.println(item.getName() + " - " + item.getSize() + " bytes"));

        // 创建目录
        openListClient.mkdir("/new-folder");

        // 列出所有存储
        List<StorageItem> storages = openListClient.listStorages();
        storages.forEach(s ->
            System.out.println(s.getMountPath() + " -> " + s.getDriver()));
    }
}

配置参考

API 接口

通用响应格式

所有 API 的原始 JSON 响应均遵循如下格式：

{
    "code": 200,
    "message": "success",
    "data": { ... }
}

对应的 Java 模型类为 OpenListResponse<T>：

认证 API

login — 用户登录

自动登录并获取 JWT Token。Token 会缓存在内存中，后续 API 调用自动携带。

• 接口方法：LoginResponse login()

• 对应 API：POST /api/auth/login

请求参数（自动从配置中读取）：

返回类型：LoginResponse

使用示例：

LoginResponse response = openListClient.login();
System.out.println("Token: " + response.getToken());

首次调用任何 API 方法时，Starter 会自动执行登录，通常无需手动调用此方法。

logout — 用户登出

• 接口方法：void logout()

• 对应 API：GET /api/auth/logout

使用示例：

openListClient.logout();

用户 API

getCurrentUser — 获取当前用户信息

• 接口方法：OpenListResponse<JsonNode> getCurrentUser()

• 对应 API：GET /api/me

返回类型：OpenListResponse<JsonNode>

响应 JSON 示例：

{
    "code": 200,
    "message": "success",
    "data": {
        "id": 1,
        "username": "admin",
        "base_path": "/",
        "role": "admin",
        "enabled": true
    }
}

使用示例：

OpenListResponse<JsonNode> response = openListClient.getCurrentUser();
if (response.getCode() == 200) {
    JsonNode user = response.getData();
    System.out.println("Username: " + user.get("username").asText());
    System.out.println("Role: " + user.get("role").asText());
}

文件系统 API

listFiles — 获取文件列表

• 接口方法：FileListResponse listFiles(String path)

• 对应 API：GET /api/fs/list?path=<path>

请求参数：

返回类型：FileListResponse

FileItem 字段：

响应 JSON 示例：

{
    "code": 200,
    "message": "success",
    "data": {
        "content": [
            { "name": "Documents", "size": 0, "is_dir": true, "modified": "2024-01-15T10:30:00Z" },
            { "name": "readme.txt", "size": 1024, "is_dir": false, "modified": "2024-01-10T08:00:00Z" }
        ],
        "total": 2
    }
}

使用示例：

FileListResponse response = openListClient.listFiles("/");
for (FileItem item : response.getContent()) {
    String type = item.isDir() ? "[DIR]" : "[FILE]";
    System.out.println(type + " " + item.getName() + " (" + item.getSize() + " bytes)");
}

getFile — 获取文件详情

• 接口方法：OpenListResponse<JsonNode> getFile(String path)

• 对应 API：GET /api/fs/get?path=<path>

请求参数：

使用示例：

OpenListResponse<JsonNode> response = openListClient.getFile("/readme.txt");
System.out.println("File info: " + response.getData());

mkdir — 创建目录

• 接口方法：void mkdir(String path)

• 对应 API：POST /api/fs/mkdir

请求参数：

请求体 JSON 示例：

{ "path": "/new-directory" }

使用示例：

openListClient.mkdir("/new-directory");

rename — 重命名文件/目录

• 接口方法：void rename(String oldPath, String newPath)

• 对应 API：POST /api/fs/rename

请求参数：

请求体 JSON 示例：

{ "old_path": "/old-name.txt", "new_path": "/new-name.txt" }

使用示例：

openListClient.rename("/old-name.txt", "/new-name.txt");

remove — 删除文件/目录

• 接口方法：void remove(String path)

• 对应 API：POST /api/fs/remove

请求参数：

请求体 JSON 示例：

{ "path": "/file-to-delete.txt" }

使用示例：

openListClient.remove("/file-to-delete.txt");

uploadFile — 上传文件

• 接口方法：void uploadFile(String path, byte[] content)

• 对应 API：PUT /api/fs/put?path=<path>

请求参数：

请求头：Content-Type: application/octet-stream

使用示例：

byte[] fileContent = Files.readAllBytes(Paths.get("local-file.pdf"));
openListClient.uploadFile("/uploads/local-file.pdf", fileContent);

addOfflineDownload — 添加离线下载任务

• 接口方法：void addOfflineDownload(String url, String path)

• 对应 API：POST /api/fs/add_offline_download

请求参数：

请求体 JSON 示例：

{ "url": "https://example.com/large-file.zip", "path": "/downloads" }

使用示例：

openListClient.addOfflineDownload("https://example.com/file.zip", "/downloads");

decompressArchive — 解压归档文件

• 接口方法：void decompressArchive(String path, String targetPath)

• 对应 API：POST /api/fs/archive/decompress

请求参数：

请求体 JSON 示例：

{ "path": "/downloads/archive.zip", "target_path": "/extracted" }

使用示例：

openListClient.decompressArchive("/downloads/archive.zip", "/extracted");

batchRename — 批量重命名

• 接口方法：void batchRename(List<BatchRenameOperation> operations)

• 对应 API：POST /api/fs/batch_rename

请求参数：

BatchRenameOperation 字段：

请求体 JSON 示例：

{
    "operations": [
        { "old_path": "/a.txt", "new_path": "/a-renamed.txt" },
        { "old_path": "/b.txt", "new_path": "/b-renamed.txt" }
    ]
}

使用示例：

List<BatchRenameOperation> ops = new ArrayList<>();

BatchRenameOperation op1 = new BatchRenameOperation();
op1.setOldPath("/a.txt");
op1.setNewPath("/a-renamed.txt");
ops.add(op1);

BatchRenameOperation op2 = new BatchRenameOperation();
op2.setOldPath("/b.txt");
op2.setNewPath("/b-renamed.txt");
ops.add(op2);

openListClient.batchRename(ops);