TDLib文件上传机制详解：PreliminaryUploadFile与文件持久化

文件上传的基本流程

在TDLib中，文件上传是一个核心功能，开发者可以通过PreliminaryUploadFile方法启动文件上传过程。这个方法允许开发者预先上传文件到服务器，而无需立即将其附加到消息中。上传过程中，TDLib会通过UpdateFile通知来报告上传进度。

PreliminaryUploadFile的特性

PreliminaryUploadFile方法有几个重要特点：

1. 非持久化上传：使用此方法上传的文件不会立即获得持久化的远程ID
2. 进度监控：通过监听UpdateFile通知可以获取上传进度
3. 临时状态：上传完成后文件仍处于临时状态，直到被实际使用

文件状态转换的关键点

当使用PreliminaryUploadFile上传文件时，开发者可能会观察到以下行为：

1. uploadedSize会逐渐增加直到等于文件总大小
2. isUploadingActive会在上传完成后变为false
3. 但isUploadingCompleted不会自动变为true

这是因为文件需要被实际发送到聊天中才会完成最终的持久化过程。这是TDLib设计上的一个重要特性，确保了服务器资源不会被未使用的文件占用。

实现文件持久化的正确方式

要使上传的文件获得持久化ID并完成上传过程，必须将文件包含在发送的消息中。以下是推荐的实现方式：

// 创建本地文件输入
TdApi.InputFile inputFile = new TdApi.InputFileLocal("file_path");

// 创建文档消息内容
TdApi.InputMessageDocument messageContent = new TdApi.InputMessageDocument(
    inputFile, 
    null,   // 缩略图
    true,   // 禁用内容类型检测
    null    // 标题
);

// 发送包含文件的消息
client.send(new TdApi.SendMessage(
    recipient,  // 接收者
    0,          // 消息ID
    null,       // 回复设置
    null,       // 选项
    null,       // 回复标记
    messageContent
), handler, null);

文件生命周期管理

TDLib提供了几个方法来管理上传文件的生命周期：

1. cancelPreliminaryUploadFile：取消尚未包含在消息中的预上传文件
2. deleteFile：从TDLib缓存中删除已下载的文件
3. deleteMessages：删除消息(包括未发送的消息)，相关文件的上传会被取消

最佳实践建议

1. 如果文件需要长期存储，务必将其包含在发送的消息中
2. 对于临时上传，使用cancelPreliminaryUploadFile及时清理
3. 监控UpdateFile通知时，不要仅依赖isUploadingCompleted标志
4. 考虑实现重试机制处理上传中断的情况