cpp-httplib 大文件上传解决方案与实现

问题背景

在使用 cpp-httplib 进行 Web 开发时，处理大文件上传是一个常见需求。默认情况下，cpp-httplib 有一个 set_payload_max_length 参数限制请求体大小，当上传文件超过这个限制时，服务器会返回 413 Payload Too Large 错误。

问题分析

通过分析 cpp-httplib 的源码，我们发现当请求体大小超过限制时，会触发以下逻辑：

1. 服务器检查请求头中的 Content-Length
2. 如果 Content-Length 大于 payload_max_length，直接返回 413 错误
3. 否则才会继续处理请求内容

这种机制对于大文件上传来说不够友好，因为现代浏览器通常不会自动使用分块传输编码(Chunked Transfer Encoding)。

解决方案

前端实现

前端可以采用分片上传策略，将大文件切分为多个小块分别上传：

1. 计算文件总大小和需要分片的数量
2. 使用 File API 的 slice 方法获取文件片段
3. 使用 FormData 封装每个分片及元数据(文件名、分片索引、总分片数)
4. 通过 fetch API 逐个上传分片
5. 显示上传进度条

关键代码实现：

async function uploadFile() {
    const file = fileInput.files[0];
    const chunkSize = 1 * 1024 * 1024; // 1MB分片
    const totalChunks = Math.ceil(file.size / chunkSize);
    
    for(let currentChunk = 0; currentChunk < totalChunks; currentChunk++) {
        const chunk = file.slice(currentChunk * chunkSize, 
                               Math.min((currentChunk + 1) * chunkSize, file.size));
        
        const formData = new FormData();
        formData.append("chunk", chunk);
        formData.append("index", currentChunk);
        formData.append("filename", encodeURIComponent(file.name));
        formData.append("totalChunks", totalChunks);
        
        await fetch(uploadUrl, {
            method: "POST",
            body: formData
        });
        
        updateProgress(currentChunk, totalChunks);
    }
}

后端实现

服务器端需要处理分片上传的逻辑：

1. 验证请求是否为 multipart/form-data 格式
2. 从 FormData 中提取分片信息和文件数据
3. 检查是否为第一个分片，如果是则创建新文件
4. 以追加模式将分片数据写入文件
5. 如果是最后一个分片，完成上传并返回成功响应

关键代码实现：

if(req.is_multipart_form_data()) {
    std::string filename, index, totalChunks, chunkData;
    
    // 解析FormData字段
    for(const auto& item : req.files) {
        const auto& file = item.second;
        if(file.name == "filename") filename = file.content;
        else if(file.name == "index") index = file.content;
        else if(file.name == "totalChunks") totalChunks = file.content;
        else if(file.name == "chunk") chunkData = file.content;
    }
    
    // 验证字段完整性
    if(filename.empty() || index.empty() || totalChunks.empty() || chunkData.empty()) {
        res.status = 400;
        return;
    }
    
    // 写入文件分片
    std::ofstream ofs(filePath, std::ios::binary | std::ios::app);
    ofs.write(chunkData.c_str(), chunkData.size());
    ofs.close();
    
    // 检查是否为最后一个分片
    if(std::stoi(index) + 1 == std::stoi(totalChunks)) {
        res.status = 200;
    } else {
        res.status = 200;
    }
}

技术要点

1. 分片大小选择：1MB 是一个经验值，既能保证传输效率，又不会触发服务器的 payload 限制

2. 断点续传：可以在前端记录已上传的分片，实现断点续传功能

3. 文件完整性校验：上传完成后可以计算文件哈希值进行校验

4. 并发控制：可以适当增加并发上传数提高速度，但要注意服务器负载

5. 错误处理：实现重试机制处理网络不稳定的情况

性能优化建议

1. 使用 Web Workers 处理文件分片，避免阻塞主线程
2. 实现并行上传，提高大文件上传速度
3. 添加压缩选项，减少传输数据量
4. 实现上传暂停/恢复功能
5. 添加上传速度计算和预估剩余时间显示

总结

通过分片上传策略，我们成功绕过了 cpp-httplib 的 payload 大小限制，实现了稳定可靠的大文件上传功能。这种方案不仅适用于 cpp-httplib，也可以应用于其他类似的 HTTP 服务器框架。关键在于前后端的协同设计，确保分片信息的正确传递和文件数据的完整重组。