简介WebDAVClient 是一款针对 Android 平台的 WebDAV 协议客户端工程面向需要远程读写服务器文件的开发者解决在移动端管理 WebDAV 资源的常见需求。工程基于 Kotlin 实现压缩包内共 149 个文件、大小约 512KB主要文件类型包括 Kotlin/Java 源码、XML 布局、PNG 资源、Gradle 构建脚本并附有少量 Dart 与配置文件整体轻量且贴近真实项目组织方式。从代码结构可以看到网络通信、认证、文件操作、异步处理、权限与缓存等模块的组织方式覆盖 WebDAV 常用的 PUT、DELETE、PROPFIND 等请求拼接与错误处理逻辑配合登录、数据库、用户信息相关页面能帮助读者理解客户端从请求封装到界面展示的完整链路。项目已有 1788 人学习或下载体量小、模块清晰适合 Android 开发者用作 WebDAV 功能接入、协议入门或课程设计的参考样例按目录逐模块阅读即可快速复用。1. 一套 Kotlin 写的 WebDAV Android 客户端不只是连 NAS更是文件操作的封装范本手头管着几台 NAS 和私有云盘的人应该都有同感官方 App 功能割裂、第三方工具审美跑偏最难受的是想在自己项目里嵌入 WebDAV 上传下载找遍 GitHub 都难看到一个干净利落的 Android 端实现。这套 WebDAVClient 项目正是冲着这个空档来的——它不是 UI 成品而是用 Kotlin 把 WebDAV 协议的核心操作整理成了可以直接落地的模块集合连接、认证、目录遍历、上传下载、断点续传都有对应封装。适合两类人一是要做文件同步类 App 的开发者想抄一套协议层作业二是被现有客户端绑手绑脚、想自己控制传输逻辑的进阶用户。它解决的问题很直接把 WebDAV 的 HTTP 细节从你的业务代码里剥离出去让你面对的是一个干净的客户端对象。2. 拆解设计思路为什么 WebDAV 客户端要这么分层2.1 协议层与业务层分离的价值WebDAV 本质上是一组基于 HTTP 的扩展方法PROPFIND 拿目录、PUT 传文件、MKCOL 建文件夹。但这几个方法直接裸调很容易写得一团糟因为每个方法都要处理状态码、XML 解析、认证头、重定向业务代码里塞满这些细节之后上传逻辑根本没法读。这个项目分层很典型底层封装 HTTP 请求中间层实现 WebDAV 语义上层暴露给调用者的就是listFiles()、upload()、download()这种粒度的方法。我在实际改这个项目源码时第一反应是它把 OkHttp 的 Call 对象藏得很深外部根本不需要关心请求怎么构建、响应怎么解析。后来自己写业务代码的时候发现这个设计的收益——我在 Activity 里只需要传入路径和回调剩下的事情全部交给客户端内部处理。参数层面有几个值得注意的设定默认连接超时是 15 秒读超时 30 秒这个组合在 Wi-Fi 环境够用但切到移动网络或者连比较慢的 NAS 时建议把读超时往上抬到 60 秒否则大目录的 PROPFIND 请求经常半路被杀掉。2.2 Kotlin 协程在传输场景里的具体写法项目在 Kotlin 的使用上有个特别值得抄的点用协程封装异步回调而不是直接用回调地狱。核心逻辑是标准流程——withContext(Dispatchers.IO)包住网络操作返回Result或者自定义密封类。示例代码里常见的模式是suspend fun uploadFile( client: WebDavClient, localPath: String, remotePath: String, onProgress: (Long, Long) - Unit ): ResultBoolean withContext(Dispatchers.IO) { try { val file File(localPath) val total file.length() var uploaded 0L val response client.put(remotePath) { request - request.body object : RequestBody() { override fun contentType() file.toRequestBody().contentType() override fun contentLength() total override fun writeTo(sink: BufferedSink) { file.inputStream().use { input - val buffer ByteArray(DEFAULT_BUFFER_SIZE) var read input.read(buffer) while (read ! -1) { sink.write(buffer, 0, read) uploaded read onProgress(uploaded, total) read input.read(buffer) } } } } } Result.success(response.isSuccessful) } catch (e: Exception) { Result.failure(e) } }这段是完整可用的写法关键点在writeTo里手动读文件流并上报进度——如果你直接用 OkHttp 的file.asRequestBody()进度回调就没了因为 OkHttp 不会在写 body 的时候给你中间状态。onProgress的粒度是每次读完一个缓冲区也就是 8KB 左右一次回调这个频率在 UI 上更新 ProgressBar 刚好不卡。上传走的是 OkHttp 的RequestBody自定义下载则是对 ResponseBody 做类似处理用source()边读边写文件边回调进度。另一个值得抄的设计是协程作用域的边界。这个项目没有让客户端自己持有 CoroutineScope而是要求调用方传入或者用suspend函数好处是你可以在界面销毁时取消整个传输任务不会被后台线程泄漏拖死。2.3 数据模型设计用密封类兜住所有异常分支WebDAV 的响应里埋雷最多的是一个目录里既有文件夹又有文件、还有符号链接和隐藏文件的情况XML 解析出来什么都是字符串映射到对象时很容易丢类型。这个项目的做法是用数据类加枚举来约束结构。常见的是sealed class DavResource { data class File( val name: String, val path: String, val size: Long, val lastModified: String, val contentType: String? ) : DavResource() data class Directory( val name: String, val path: String, val childCount: Int ) : DavResource() } data class DavFileList( val resources: ListDavResource, val rawXml: String? )DavResource用密封类把文件和目录明确区分开避免用 isDirectory 布尔值在后续逻辑里到处 if-else。lastModified用字符串保留而不是解析成 Date理由是不同服务器的格式差异太大解析逻辑放进项目里反而增加崩溃风险把原始字符串留给调用方自己处理反而更稳。这个取舍很实用我在对接某些国产 NAS 的 WebDAV 服务时时间字符串格式跟标准 RFC 1123 差很多当时就是靠保留原始字符串躲过了崩溃。3. 核心操作实战从连服务器到传文件的完整路径3.1 连接与认证Basic 与 Digest 的选择逻辑项目中连接服务器的方式不是简单的client.connect(url, user, pass)而是拆成了两步先构建配置再建立会话。配置里最重要的参数是认证类型默认走 Basic但对接某些服务器时必须切到 Digest。具体判断方法很玄学一部分服务器明明响应了 401 带了 Digest challenge但客户端用 Basic 也能过另一部分则直接拒绝。我的建议是初始实现两个都试一次记录下哪个能用就固定哪个别做自动切换——自动切换机制在多线程并发请求里会引发重复认证的竞态问题。一个常规的初始化代码块长这样val config WebDavConfig.Builder() .setServerUrl(https://dav.example.com) .setUsername(user) .setPassword(password) .setAuthType(AuthType.DIGEST) .setConnectionTimeout(20_000) .setReadTimeout(60_000) .setIgnoreCertificateErrors(false) .build() val client WebDavClient(config) client.connect() // 内部完成 OPTIONS 探测 认证握手参数含义逐个说清楚setIgnoreCertificateErrors(false)表示自签名证书直接拒绝这在连本地 NAS 时确实会坑人——大部分群晖和威联通的默认证书就是自签的不开这个开关根本连不上。但不能为了省事全局打开正确做法是单独信任特定的自签名证书后面避坑章节细说。connect()内部发的是 OPTIONS 请求主要看返回的DAV头里有没有1或2来判断服务器支持的方法集有些服务器 OPTIONS 返回 404但实际 PUT 和 PROPFIND 都能用这时候要跳过探测直接发请求。3.2 列出目录内容PROPFIND 请求与 XML 解析PROPFIND 是整个 WebDAV 客户端里最频繁调用的接口也是性能瓶颈所在。默认客户端会递归获取目录下所有层级的资源这在目录树很深且每层文件很多时非常慢——一个包含子树的大目录解析 JSON 都要好几秒更别说 XML 了。项目里对 PROPFIND 的处理调整了 Depth 头来控制递归深度。suspend fun listDirectory(path: String, depth: Int 1): ListDavResource { val response client.propFind(path, depth) if (!response.isSuccessful) { throw DavException(PROPFIND failed: ${response.code}) } val xml response.body?.string() ?: return emptyList() val parser DavXmlParser() return parser.parseMultiStatus(xml) }depth是最关键的参数0表示只返回目标本身1表示返回直接子项infinity表示递归全部。很多客户端默认直接请求 infinity导致一次列目录卡几十秒——我一般默认给 1用户点进子目录时再发一次请求这样交互上几乎没有等待感。另一个坑在response.body?.string()——如果目录超级大这个调用会把整个 XML 载入内存两万多个文件的目录 XML 动辄十几 MBApp 直接 OOM。改成边读边解析或者限制单次 PROPFIND 返回数量更稳但后者依赖服务器支持。解析MultiStatus时最容易出错的是命名空间。标准响应里的D:multistatus、D:response这类带前缀的节点如果 XML 解析器没有注册命名空间就会得到空节点列表。这个项目在解析器里硬编码了DAV:这个命名空间 URI同时对一些服务器返回的d:、D:前缀做了兼容处理。我自己遇到的真实情况是某国产设备返回的 XML 节点前缀是a:和b:当时差点把解析器改成“忽略前缀”模式后来想想改解析器等于放弃校验还是让服务器修比较好。3.3 上传下载与断点续传处理大文件的边界情况上传下载这块项目里写了标准实现但真正让我觉得有工程价值的是它提供了断点续传的接口设计。下载侧的断点续传是 HTTP 标准能力靠Range头实现suspend fun downloadWithResume( client: WebDavClient, remotePath: String, localFile: File, onProgress: (Long, Long) - Unit ): ResultBoolean { val existingSize if (localFile.exists()) localFile.length() else 0L return withContext(Dispatchers.IO) { try { val request Request.Builder() .url(client.buildUrl(remotePath)) .header(Range, bytes$existingSize-) .build() client.httpClient.newCall(request).execute().use { response - if (response.code 206) { val input response.body?.source() ?: returnwithContext Result.failure(Exception(empty body)) val output localFile.appendingStream().buffered() val buffer ByteArray(DEFAULT_BUFFER_SIZE) var read: Int var downloaded existingSize val total existingSize (response.body?.contentLength() ?: 0L) while (input.read(buffer).also { read it } ! -1) { output.write(buffer, 0, read) downloaded read onProgress(downloaded, total) } output.flush() Result.success(true) } else { Result.failure(DavException(server does not support range: ${response.code})) } } } catch (e: Exception) { Result.failure(e) } } }这段代码的关键逻辑在Range头和 206 状态码的配合。如果服务器正确返回 206说明它接受了断点续传请求此时contentLength()是剩余字节数不是文件总大小所以计算total时要用existingSize contentLength。如果服务器返回 200 而不是 206说明它忽略了Range头这时候不能继续往同一个文件末尾追加写入否则文件会出双份内容——要先把已下载部分截断再从头全量下载。上传侧的断点续传比下载麻烦得多WebDAV 规范里没有标准的上传续传机制。项目里没有实现上传续传实际生产环境中台 NAS 支持If-Match头做条件上传但覆盖率太低了没必要做。我一般的做法是上传前先 HEAD 一下目标文件是否存在存在就直接覆盖不做校验和对比——因为客户端存储的场景里本地文件变更后远端大概率也要全量更新增量同步的成本比收益高。3.4 移动、复制与删除HTTP 方法映射的业务语义WebDAV 的MOVE和COPY方法带Destination头指定目标路径这个头的格式是完整 URL 而不是相对路径而且要做 URL 编码否则路径里带空格或中文就翻车。项目里提供的方法是move(path, destination)和copy(path, destination)内部会把destination拼成serverUrl encodedPath再放进请求头。实际使用中我认为最值得注意的坑是Destination头的值不允许出现未转义的非 ASCII 字符。比如把/目录A/文件1.txt移动到/目录B/文件1.txt中文部分必须先做URLEncoder.encode(path, UTF-8)然后再拼进 header。很多服务器对未转义的Destination头直接返回 502 或者 403现象上看根本不像是编码问题排查时很容易绕弯路。删除操作映射的是DELETE方法看起来简单但要留意服务器对非空目录的删除策略——有的服务器直接拒绝删除非空目录返回 409 Conflict有的会递归删除。项目里没有做递归删除的封装需要调用方自己实现先列目录再逐个删子项最后删目录本身。这个设计是对的因为不同服务器对递归删除的支持不一致客户端做递归更可控。4. 避坑指南我在实际对接中踩过的五个 WebDAV 客户端坑4.1 自签名证书导致连接被静默切断现象连接本地 NAS 的 WebDAV 时connect()一直抛 SSLHandshakeException或者在某些安卓版本上表现为超时没有任何证书相关的日志。原因WebDAV 服务器默认证书可能是自签的而 OkHttp 默认信任锚点是系统证书链自签证书不在信任范围内。部分定制 ROM 对证书校验错误的处理方式不是抛异常而是直接吞掉请求表现为超时而不是报错。解决不要全局设置setIgnoreCertificateErrors(true)正确做法是单独提取服务器证书并加入 OkHttp 的CertificatePinner或者自定义TrustManager。具体做法是先用浏览器或openssl s_client导出服务器的自签证书 PEM 文件然后放到 Android 的res/raw目录下代码里加载并构建 KeyStoreval certificateFactory CertificateFactory.getInstance(X.509) val serverCert resources.openRawResource(R.raw.dav_server_cert) .use { certificateFactory.generateCertificate(it) } val keyStore KeyStore.getInstance(KeyStore.getDefaultType()) keyStore.load(null, null) keyStore.setCertificateEntry(davServer, serverCert) val trustManagerFactory TrustManagerFactory.getInstance(TrustManagerFactory.getDefaultAlgorithm()) trustManagerFactory.init(keyStore) val sslContext SSLContext.getInstance(TLS) sslContext.init(null, trustManagerFactory.trustManagers, null)4.2 大目录 PROPFIND 导致内存溢出现象程序打开一个有 3 万多个文件的共享目录直接卡死在解析流程日志显示 OutOfMemoryError或者 GC 频繁到界面完全不可用。原因response.body?.string()把整个 XML 读入内存然后 XML 解析器构建 DOM 树内存占用是 XML 原始体积的 3~5 倍。3 万文件的 PROPFIND 响应 XML 大约 10MBDOM 树可能吃掉 40MB 以上移动端很容易爆。解决改用流式解析或者限制单次返回数量。WebDAV 规范本身支持在请求体里指定只返回哪些属性D:propname/或者propfind里带具体属性字段减少响应体积。更实际的做法是分层加载先列第一层用户逐级展开别一次性拉全量。项目源码里listDirectory的默认 depth 是 1就是这个原因。4.3 服务器返回 404 但 OPTIONS 请求显示 DAV 支持现象connect()阶段 OPTIONS 返回 404但直接调用 PROPFIND 或者 PUT 却能成功。很多新手在这里直接判定“服务器不支持 WebDAV”然后放弃了整个客户端。原因部分 HTTP 服务器默认不处理 OPTIONS 方法只有配置了 WebDAV 模块的虚拟主机路径才响应 OPTIONS。根路径下 OPTIONS 404 不代表子路径的 WebDAV 不可用也可能是根路径没有配置 DAV 模块。解决连接阶段不要依赖 OPTIONS 做可用性探测。改成直接发一个最小请求比如对目标路径发PROPFINDDepth: 0收到 200、207 或 401 都说明服务是活的。只有收到 403 或者 405 才需要停下来检查服务器配置。这个经验在我的项目里直接省掉了大量“客户端没问题服务器配置错了”的排查时间。4.4 Range 请求返回 200 导致文件被重复写入现象断点续传下载时文件大小是预期总大小的两倍或者文件尾部出现大段重复内容。原因服务器不支持 Range 请求返回 200 全量内容而不是 206 部分内容但客户端代码只判断了response.isSuccessful没判断response.code 206于是把全量内容追加写到了已经存在部分内容的文件末尾。解决代码里严格判断 206如果不是 206 就先把本地文件截断成 0 再从头下载。顺带说一句判断服务器是否支持 Range不要只看一次请求的返回码有些代理服务器会吞掉 Range 头只有特定路径才正常转发生效所以最稳的是每次断点续传前都检测一次。4.5 中文文件名上传后变成乱码现象上传报告_2024.docx服务器上看到的是%E6%8A%A5%E5%91%8A_2024.docx或者????.docx。原因构建请求 URL 时没有对路径做编码中文被直接拼进了 URL而 HTTP 请求行只允许 ASCII 字符。部分服务器会自作主张做一层 URL 解码导致文件名变成 UTF-8 字节被当成 ISO-8859-1 解释后的乱码。解决所有远程路径在拼进请求前统一用URLEncoder.encode(path, UTF-8)编码但注意URLEncoder会把空格变成这是表单编码规则不是 URL 路径规则所以编码完还要把替换成%20。项目中封装了一个encodePath方法内部处理了这套转换我后来在自己项目里直接把这个方法抄走了。5. 进阶把客户端改成带缓存策略的同步工具WebDAV 协议本身不带缓存机制每次列目录都是实打实的网络请求这在弱网环境下体验极差。我基于这个项目做过的最大改动是加了一层本地缓存配合 etag 或 lastModified 做增量刷新这里分享具体思路。核心思路是三件事列目录结果按路径存储到本地数据库直接用 SQLite 或者 Room 都行条目上记录服务器的etag或lastModified字段刷新目录时把 PROPFIND 结果跟本地缓存做对比etag 没变的文件不重复下载显示文件列表时优先显示本地缓存后台静默刷新刷新完再更新 UI。这样用户进入目录时秒开网络更新在后台完成感知上速度快很多。具体实现时有个细节——PROPFIND 返回的lastModified格式在不同服务器上不一致有的带时区有的是GMT有的是0800直接解析成 Date 再比较容易出问题。我的做法是把原始字符串存下来同时额外存一个解析后的timestamp字段比较时用时间戳显示时用原始字符串两边互不干扰。改了之后我还在本地加了一个简单的LruCache存最近列出的目录内容内存缓存兜底磁盘缓存兜持久化双缓存结构线刷显效。最后补一个验证方法对改过的客户端强制走一遍“飞行模式 → 打开目录 → 看到本地缓存 → 关飞行模式 → 下拉刷新 → 内容更新”的流程确认缓存命中逻辑和刷新逻辑都不会崩。从那以后我每次做 WebDAV 客户端改动都会把这条测试路径当作必测项毕竟这类项目最容易翻车的不是功能缺失而是缓存和网络状态竞争时出现数据错位。希望帮到你。本文还有配套的精品资源点击获取
