坚果云WebDAV操作类开发文档

一、文档概述

本文档详细介绍了JianguoyunWebDAV类的开发背景、功能特性、使用方法、核心实现逻辑及注意事项，旨在帮助开发人员快速集成和使用该类完成坚果云WebDAV的相关操作。

1.1 开发背景

坚果云提供WebDAV接口用于文件和目录的管理，但原生WebDAV操作存在中文编码适配、大文件处理、请求频率限制等问题。该类封装了坚果云WebDAV的核心操作，解决了上述痛点，提供简洁、高效的开发接口。

1.2 功能特性

• 大文件处理：支持流式上传/下载，避免内存溢出，适配大文件传输。
• 中文编码适配：自动处理GBK/GB2312等编码与UTF-8的转换，支持中文路径和文件名。
• 非法字符过滤：仅过滤坚果云禁止的文件名/目录名非法字符，保留路径分隔符和盘符。
• 多级目录创建：递归创建远程多级目录，添加MKCOL请求间隔避免频率限制。
• 完整的文件操作：支持文件/目录的上传、下载、删除、列表查询。
• 日志记录：集成日志实例，记录操作异常信息（需自定义Log类）。

二、环境依赖

• PHP版本：5.6及以上（推荐7.0+）。
• 扩展依赖：curl扩展（必须，用于HTTP请求）、mbstring扩展（用于字符编码转换）、fileinfo扩展（用于获取文件MIME类型）。
• 其他：需自定义Log类（实现error方法用于日志记录）。

三、类结构与核心参数

3.1 私有属性

3.2 构造函数

public function __construct($server, $username, $password, $chunkSize = 10485760, $mkcolDelay = 0.5)

参数说明：

• $server：坚果云WebDAV服务器地址（必填）。
• $username：坚果云邮箱（必填）。
• $password：坚果云WebDAV专用密码（必填）。
• $chunkSize：流式分块大小，默认10MB（可选）。
• $mkcolDelay：MKCOL请求间隔，默认0.5秒（可选）。

四、核心方法详解

4.1 私有辅助方法

4.1.1 filterFileName：过滤文件名非法字符

private function filterFileName($name)

功能：过滤坚果云禁止的目录/文件名字符，替换为下划线_。
参数：$name（单个目录名/文件名，如test.txt、测试目录）。
返回值：过滤后的名称字符串。
禁止字符列表：/、\、:、*、?、"、<、>、|、\0。

4.1.2 encodePath：处理中文路径的URL编码

private function encodePath($path)

功能：分割路径为多个部分，分别过滤非法字符、转换为UTF-8、URL编码后拼接。
参数：$path（远程相对路径，如xmblog/测试/文件.txt）。
返回值：URL编码后的路径字符串。

4.1.3 decodePath：处理URL解码还原中文路径

private function decodePath($path)

功能：先URL解码，再转换为UTF-8编码，还原中文路径。
参数：$path（URL编码后的路径）。
返回值：解码后的UTF-8路径字符串。

4.1.4 toUtf8：字符串编码转换为UTF-8

private function toUtf8($str)

功能：检测字符串编码（支持UTF-8、GBK、GB2312、ISO-8859-1），转换为UTF-8。
参数：$str（原始字符串）。
返回值：UTF-8编码的字符串。

4.1.5 request：发送WebDAV请求（核心）

private function request($method, $path, $inFile = null, $fileSize = 0, $headers = [])

功能：封装curl请求，支持各类WebDAV HTTP方法，适配流式上传。
参数：

• $method：HTTP方法（GET/PUT/DELETE/PROPFIND/MKCOL等）。
• $path：文件/目录相对路径（可含中文）。
• $inFile：上传的文件句柄（PUT流式上传时使用）。
• $fileSize：文件大小（PUT流式上传时使用）。
• $headers：自定义请求头（数组）。
  返回值：数组，包含status（状态码）、headers（响应头）、body（响应体）。
  关键配置：
• 关闭SSL验证（生产环境建议开启，移除对应配置）。
• PUT方法时，设置CURLOPT_UPLOAD、CURLOPT_INFILE等实现流式上传。

4.2 公共业务方法

4.2.1 createRemoteDir：递归创建远程多级目录

public function createRemoteDir($remoteDir)

功能：递归创建远程多级目录，添加MKCOL请求间隔避免频率限制，支持中文路径。
参数：$remoteDir（远程目录路径，如xmblog/测试/子目录/）。
返回值：布尔值，true表示创建成功，false表示失败。
实现逻辑：

1. 处理路径编码和规范化，分割为多级目录。
2. 遍历每一级目录，过滤非法字符后，发送MKCOL请求。
3. 请求前添加延迟（usleep），处理201（创建成功）和405（已存在）状态码。
4. 记录异常日志，返回创建结果。

4.2.2 listFiles：获取目录下的文件列表

public function listFiles($path = '')

功能：发送PROPFIND请求，获取目录下的文件/目录列表及属性（名称、大小、修改时间、类型）。
参数：$path（远程目录路径，默认根目录）。
返回值：数组，每个元素包含name（名称）、path（路径）、size（大小）、mtime（修改时间戳）、is_dir（是否为目录）。
实现逻辑：

1. 构造PROPFIND的XML请求体，请求文件属性。
2. 发送请求，解析207（多状态响应）的XML结果。
3. 解码中文路径，过滤当前目录本身，提取文件属性并返回。

4.2.3 uploadFile：大文件流式上传

public function uploadFile($localFile, $remotePath)

功能：流式上传本地文件到坚果云，自动创建远程目录，支持中文路径和大文件。
参数：

• $localFile：本地文件路径（可含中文）。
• $remotePath：远程文件路径（包含文件名，可含中文）。
  返回值：布尔值，true表示上传成功，false表示失败。
  实现逻辑：
• 检查本地文件是否存在，处理路径编码和非法字符过滤。
• 提取远程目录部分，调用createRemoteDir创建目录。
• 以二进制模式打开本地文件，获取文件大小和MIME类型。
• 发送PUT请求流式上传，处理201（创建成功）和204（更新成功）状态码。
• 记录异常日志，返回上传结果。

4.2.4 downloadFile：大文件流式下载

public function downloadFile($remotePath, $localFile)

功能：流式下载坚果云文件到本地，支持中文路径，自动创建本地目录。
参数：

• $remotePath：远程文件路径（包含文件名，可含中文）。
• $localFile：本地文件路径（可含中文）。
  返回值：布尔值，true表示下载成功，false表示失败。
  实现逻辑：
• 处理远程路径和本地路径的编码、非法字符过滤。
• 创建本地目录（如果不存在）。
• 初始化curl，设置CURLOPT_FILE将响应体流式写入本地文件。
• 执行请求，处理200（成功）状态码，失败时删除空文件。
• 记录异常日志，返回下载结果。

4.2.5 deleteFile：删除远程文件/目录

public function deleteFile($remotePath)

功能：删除坚果云的文件或目录，支持中文路径。
参数：$remotePath（远程文件/目录路径，可含中文）。
返回值：布尔值，true表示删除成功，false表示失败。
实现逻辑：

1. 处理路径编码和非法字符过滤。
2. 发送DELETE请求，处理204（删除成功）和404（不存在）状态码。
3. 记录异常日志，返回删除结果。

五、使用示例

5.1 初始化类

// 自定义Log类（需实现error方法）
class Log {
    public function error($message) {
        // 示例：写入日志文件
        file_put_contents('jianguoyun_webdav.log', date('Y-m-d H:i:s') . ' - ' . $message . PHP_EOL, FILE_APPEND);
    }
}

// 坚果云WebDAV配置
$server = 'https://dav.jianguoyun.com/dav/';
$username = 'your_email@example.com'; // 坚果云邮箱
$password = 'your_webdav_password'; // 坚果云WebDAV专用密码

// 初始化类
$jianguoyun = new JianguoyunWebDAV($server, $username, $password);

5.2 创建远程目录

// 创建多级目录
$remoteDir = 'xmblog/测试目录/子目录/';
$createResult = $jianguoyun->createRemoteDir($remoteDir);
if ($createResult) {
    echo '目录创建成功';
} else {
    echo '目录创建失败';
}

5.3 上传文件

// 本地文件路径
$localFile = './本地文件/测试文件.txt';
// 远程文件路径
$remoteFile = 'xmblog/测试目录/测试文件.txt';
// 上传文件
$uploadResult = $jianguoyun->uploadFile($localFile, $remoteFile);
if ($uploadResult) {
    echo '文件上传成功';
} else {
    echo '文件上传失败';
}

5.4 下载文件

// 远程文件路径
$remoteFile = 'xmblog/测试目录/测试文件.txt';
// 本地保存路径
$localFile = './下载文件/测试文件_下载.txt';
// 下载文件
$downloadResult = $jianguoyun->downloadFile($remoteFile, $localFile);
if ($downloadResult) {
    echo '文件下载成功';
} else {
    echo '文件下载失败';
}

5.5 获取文件列表

// 获取目录下的文件列表
$fileList = $jianguoyun->listFiles('xmblog/测试目录/');
print_r($fileList);

5.6 删除文件/目录

// 删除文件
$remoteFile = 'xmblog/测试目录/测试文件.txt';
$deleteResult = $jianguoyun->deleteFile($remoteFile);
if ($deleteResult) {
    echo '文件删除成功';
} else {
    echo '文件删除失败';
}

// 删除目录
$remoteDir = 'xmblog/测试目录/';
$deleteDirResult = $jianguoyun->deleteFile($remoteDir);
if ($deleteDirResult) {
    echo '目录删除成功';
} else {
    echo '目录删除失败';
}

六、注意事项

6.1 安全配置

• 生产环境中，需移除CURLOPT_SSL_VERIFYPEER和CURLOPT_SSL_VERIFYHOST的关闭配置，开启SSL验证，避免安全风险。
• 坚果云WebDAV专用密码需妥善保管，不要硬编码在代码中（可通过配置文件、环境变量读取）。

6.2 编码处理

• 确保本地文件路径的编码与系统一致（如Windows为GBK，Linux为UTF-8），类中已通过toUtf8方法自动处理，无需额外转换。
• 远程路径的中文会被自动URL编码，坚果云返回的路径会被自动解码，无需手动处理。

6.3 频率限制

• 坚果云对MKCOL请求有频率限制，类中默认设置0.5秒间隔，可根据实际情况调整mkcolDelay参数。
• 大文件上传/下载时，建议使用默认的10MB分块大小，避免因分块过大导致内存溢出。

6.4 日志处理

• 类中依赖Log类的error方法记录日志，需自行实现该类（如写入文件、数据库等），否则会抛出实例化错误。

6.5 错误处理

• 各业务方法返回布尔值表示操作结果，同时记录异常日志，可通过日志文件排查问题。

• 常见状态码说明：

  • 201：创建成功（PUT/MKCOL）。
  • 204：更新/删除成功（PUT/DELETE）。
  • 404：文件/目录不存在（DELETE/DOWNLOAD）。
  • 405：目录已存在（MKCOL）。
  • 207：多状态响应（PROPFIND）。

0 赞 or 打赏

喜欢就打赏一点