当 cargo build、cargo test 和 cargo clippy 全部亮起绿灯时，多数 Rust 开发者心里会松一口气，仿佛程序已经拿到了“无缺陷通行证”。我的 notionless 守护进程正是在这种自信中推向生产环境的，它是一种小型的 Rust 守护程序，能将 Notion 数据库以 Markdown 格式镜像到自托管的文档归档系统 Paperless-ngx 里，让笔记和其他自建内容一起纳入全文搜索。编译、测试、检查全部一次性通过，却在指向真实的互联网 Paperless 实例后，连续显露了两个潜藏于单元测试盲区的 Bug——一个动摇了认证令牌的安全性，另一个直接把上传结果吞入黑洞。

这两个 Bug 之所以“隐身”，和一种常见的认知错位有关：代码逻辑正确 ≠ 网络行为可靠。单元测试模拟的是受控的调用链条，而真实基础设施中的反向代理、协议切换、异步任务队列，往往会制造出各种协议层“惊喜”。对于依赖 HTTP 客户端库的工程来说，这类惊极易被框架的默认行为掩盖，直到数据大面积丢失或接口持续 401 时才会浮出水面。

Bug 1：重定向中悄悄消失的 Authorization 头

Paperless-ngx 的分页结果会通过 next 字段返回下页的完整 URL。在我搭建的环境中，Paperless 运行在反向代理之后，却没有设置 X-Forwarded-Proto 头，因此它总认为自己的协议是 http://，而实际对外的访问全部以 https:// 承载。我的客户端最初直接拿 next 中的 URL 发起请求：

let response = client
.get(&url) // url 直接取自 Paperless 的 next
.header("Authorization", format!("Token {}", token))
.send().await?
.json::().await?;

第一页顺利返回，从第二页开始接收到 401 状态码，并且紧接着 JSON 解析失败——因为 401 的响应体不符合我预期的结构体。原来，代理将 http:// 透明重定向到 https:// 时，reqwest 默认跟随重定向，但由于协议变更被视为跨域，Authorization 头被自动剥离。最终抵达 Paperless 服务的请求根本没带任何令牌，自然被服务端拒之门外。

修复的要点不是简单地强制升级为 https，那样会破坏 Paperless 直连内网纯 http 地址的常见场景。我转而从 next 中仅提取路径和查询部分，再基于配置中的基础 URL 重新组装，无论内网实例保留 http 还是代理实例保持 https，令牌都能稳定随每个页面传递：

fn normalize_next_url(next: &str, base: &str) -> String {
let path_and_query = match next.find("://") {
Some(scheme_end) => {
let after_scheme = &next[scheme_end + 3..];
match after_scheme.find('/') {
Some(path_start) => &after_scheme[path_start..],
None => "/",
}
}
None => next,
};
format!("{}{}", base, path_and_query)
}

Bug 2：HTTP 成功不等于业务成功

Paperless 采用异步方式处理上传：当向 /api/documents/post_document/ 发起 POST 请求后，服务端立即返回 200 和一个任务 ID，此时文件的实际验证、重复检测、存储都尚未发生。文档究竟是顺利入库，还是因重复被忽略，甚至彻底失败，全都要到另一个任务状态查询接口才能得知。我的初版代码将 200 视为“成功”并立刻继续后续流程，结果那些被静默拒绝的上传（例如完全相同的文件已存在）直接消失，既不报错也不留日志。

修正的做法是持续轮询任务状态接口直到得到明确结果，并把返回类型从简单的 Result<(), E> 替换成一个清晰的任务结果枚举：

enum TaskResult {
Success,
Failure
}

这样一来，“服务端说了 No”和“HTTP 请求本身没失败”这两种截然不同的情况，才能被上层逻辑正确区分和处理。

单元测试的理想与真实

这两个缺陷都绕开了单元测试覆盖的所有分支。单元测试擅长验证纯粹的函数逻辑、明确的状态转换，但无法模拟 HTTP 客户端库在真实网络层遇到的重定向剥离头部行为，也察觉不到后端异步处理带来的语义鸿沟。在“代码质量全部绿灯”的幻觉里，很多开发者会误以为已经穷举了所有风险，而忽略掉运行时依赖的外部协议特性。

更值得警惕的是，这类问题往往不是源自代码写得不够严谨，而是库的默认行为与业务预期存在偏差。reqwest 之所以在重定向时删掉 Authorization 头，是出于跨域安全考量，这个设计本身合理，但对使用者来说，它变成了一条静默生效的规则。类似地，Paperless 的异步上传接口设计简单，却把“可靠性”责任转移到了调用方，少一次状态轮询就可能造成数据丢失。

所以，当项目从本地测试环境走向真实基础设施时，仅靠测试覆盖率数字不足以衡量信心。在集成阶段针对关键路径补充协议层验证，或者直接部署一份“影子实例”走一遍完整的网络通道，才是把这类幽灵缺陷提前揪出来的方式。毕竟，如果三个绿灯就能代表一切正确，那就不会有两轮看似莫名其妙的 401 和悄无声息丢失的上传了。