OneCode3.0 VFS分布式文件管理API速查手册

// 插件注册示例
@Plugin(id = "vfs-plugin", name = "分布式文件系统插件", version = "1.0.0")
public class VFSPlugin implements Plugin {
    @Override
    public void start(PluginContext context) {
        // 注册VFS服务实现
        context.registerService(VFSClientService.class, new VFSClientServiceImpl());
        context.registerService(VFSDiskService.class, new VFSDiskServiceImpl());
        context.registerService(VFSStoreService.class, new VFSStoreServiceImpl());
    }
    
    @Override
    public void stop() {
        // 释放资源
    }
}

// VFSClientService接口定义
public interface VFSClientService {
    // 根据ID获取文件夹
    ResultModel<Folder> getFolderByID(String folderId);
    
    // 获取文件版本列表
    ResultModel<List<FileVersion>> getFileVersions(String fileId);
    
    // 创建视图
    ResultModel<FileView> createView(FileView view);
    
    // 从回收站恢复文件
    ResultModel<Boolean> restoreFile(String fileId);
    
    // ... 其他30+接口
}

sequenceDiagram
    participant Client as 客户端应用
    participant ClientService as 客户端服务
    participant DiskService as 磁盘服务
    participant StoreService as 存储服务
    participant DB as 元数据库
    participant Storage as 物理存储

    Client->>ClientService: 调用上传文件API(文件内容, 目标路径)
    ClientService->>DiskService: 检查路径有效性
    DiskService->>DB: 查询父文件夹元数据
    DB-->>DiskService: 返回父文件夹信息
    DiskService->>DiskService: 权限校验与路径规范化
    DiskService->>ClientService: 返回路径检查结果

    ClientService->>StoreService: 请求上传文件实体
    StoreService->>StoreService: 计算文件MD5哈希
    StoreService->>Storage: 存储文件实体
    Storage-->>StoreService: 返回文件哈希
    StoreService->>DB: 记录文件实体元数据

    ClientService->>DiskService: 创建文件元数据(路径, 哈希)
    DiskService->>DB: 写入文件元数据记录
    DB-->>DiskService: 返回文件ID
    DiskService->>ClientService: 返回文件信息
    ClientService->>Client: 返回上传结果(文件ID, 状态)

// Java SDK调用示例
VFSClient client = new VFSClient("http://onecode-server:8080/api");
String folderId = "f-123456789";
ResultModel<Folder> result = client.getFolderByID(folderId);

if (result.isSuccess()) {
    Folder folder = result.getData();
    System.out.println("文件夹名称: " + folder.getName());
    System.out.println("创建时间: " + folder.getCreateTime());
    System.out.println("包含文件数: " + folder.getFileCount());
} else {
    System.err.println("获取文件夹失败: " + result.getMessage());
}

// HTTP请求示例
POST /api/vfs/clientservice/GetFolderByID HTTP/1.1
Host: onecode-server:8080
Content-Type: application/x-www-form-urlencoded

folderId=f-123456789

// 响应示例
{
  "code": 200,
  "message": "操作成功",
  "data": {
    "id": "f-123456789",
    "name": "项目文档",
    "parentId": "f-987654321",
    "createTime": "2023-05-15T10:30:00Z",
    "updateTime": "2023-05-16T14:20:00Z",
    "fileCount": 24,
    "folderCount": 5,
    "ownerId": "user-1001",
    "permissions": ["read", "write", "share"]
  },
  "success": true
}

// JavaScript调用示例
async function getFileVersions(fileId) {
  try {
    const response = await fetch('/api/vfs/clientservice/GetFileVersions', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/x-www-form-urlencoded'
      },
      body: `fileId=${encodeURIComponent(fileId)}`
    });
    
    const result = await response.json();
    if (result.success) {
      console.log(`文件${fileId}共有${result.data.length}个版本`);
      result.data.forEach(version => {
        console.log(`版本${version.versionId}: ${version.modifyTime} - ${version.modifier}`);
      });
      return result.data;
    } else {
      console.error('获取版本失败:', result.message);
    }
  } catch (error) {
    console.error('请求异常:', error);
  }
}

// 使用示例
getFileVersions('file-789456123');

# Python调用示例
import requests

url = "http://onecode-server:8080/api/vfs/disk/MkDir"
headers = {
    "Content-Type": "application/x-www-form-urlencoded"
}
data = {
    "path": "/projectA/docs/api-design"
}

response = requests.post(url, headers=headers, data=data)
result = response.json()

if result["success"]:
    print(f"目录创建成功，ID: {result['data']['id']}")
else:
    print(f"创建失败: {result['message']}")

public class Folder {
    private String id;                 // 唯一标识
    private String name;               // 文件夹名称
    private String parentId;           // 父文件夹ID
    private Date createTime;           // 创建时间
    private Date updateTime;           // 更新时间
    private long fileCount;            // 文件数量
    private long folderCount;          // 子文件夹数量
    private String ownerId;            // 所有者ID
    private List<String> permissions;  // 权限列表
    private Map<String, Object> ext;   // 扩展属性
}

public class FileInfo {
    private String id;                 // 唯一标识
    private String name;               // 文件名称
    private String folderId;           // 所属文件夹ID
    private String hash;               // 文件内容哈希
    private long size;                 // 文件大小(字节)
    private String suffix;             // 文件后缀
    private String mimeType;           // MIME类型
    private Date createTime;           // 创建时间
    private Date updateTime;           // 更新时间
    private int versionCount;          // 版本数量
    private String ownerId;            // 所有者ID
    private List<String> permissions;  // 权限列表
    private Map<String, Object> ext;   // 扩展属性
}

public class FileVersion {
    private String id;                 // 版本ID
    private String fileId;             // 文件ID
    private String hash;               // 版本内容哈希
    private long size;                 // 版本大小
    private String modifierId;         // 修改者ID
    private String modifierName;       // 修改者名称
    private Date modifyTime;           // 修改时间
    private String comment;            // 修改备注
    private int versionNum;            // 版本号
}

public class ResultModel<T> {
    private int code;          // 状态码
    private String message;    // 消息
    private T data;            // 数据
    private boolean success;   // 是否成功
}

public class ListResultModel<T> {
    private int code;          // 状态码
    private String message;    // 消息
    private T data;            // 列表数据
    private long total;        // 总条数
    private int page;          // 当前页
    private int size;          // 每页大小
}

public interface StorageAdapter {
    // 存储文件实体
    String store(InputStream inputStream, String fileName, String userId);
    
    // 获取文件实体
    InputStream retrieve(String hash);
    
    // 删除文件实体
    boolean delete(String hash);
    
    // 检查文件是否存在
    boolean exists(String hash);
}

// 文件创建事件监听示例
@Component
public class FileCreateListener implements FileListener {
    @Override
    public void onFileCreated(FileEvent event) {
        FileInfo file = event.getFileInfo();
        // 记录审计日志
        log.info("文件创建: {}({})，大小: {} bytes", file.getName(), file.getId(), file.getSize());
        
        // 自动生成缩略图（如果是图片文件）
        if (file.getMimeType().startsWith("image/")) {
            thumbnailGenerator.generate(file.getId(), file.getHash());
        }
    }
}