坚果云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 私有属性

属性名	类型	说明
$server	string	坚果云WebDAV服务器地址（如`https://dav.jianguoyun.com/dav/`）
$username	string	坚果云用户名（注册邮箱）
$password	string	坚果云WebDAV专用密码（需在坚果云后台生成）
$chunkSize	int	流式处理的分块大小（默认10MB，单位：字节）
$log	object	日志实例（需自定义Log类，含error方法）
$mkcolDelay	float	MKCOL请求间隔（默认0.5秒，避免坚果云频率限制）

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表示失败。 实现逻辑：

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

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

public function listFiles($path = '')

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

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

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表示失败。 实现逻辑：

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

五、使用示例

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）。

蓝奏云

提取码：密码:kxiu

下