PHP Uri\Rfc3986怎样把 URL 规范化结果用于缓存键

如果同一个接口既收到 HTTPS://Example.com/a/../b?lang=zh#top，又收到 https://example.com/b?lang=zh#comments，直接把原始 URL 拼进缓存键，就会得到两个键。PHP 8.5+ 提供的 Uri\Rfc3986\Uri 可以先按 RFC 3986 重组规范化 URI，再把结果交给缓存层。

官方地址：https://www.php.net/manual/en/book.uri.php

缓存键的核心做法是：先用 Uri\Rfc3986\Uri::toString() 得到规范化字符串，再根据接口契约显式处理 fragment、查询参数和键空间版本。URI 规范化只能解决 URI 表示差异，不能替应用猜测“两个查询顺序是否等价”。

• 适用环境：PHP 8.5+，因为 Uri\Rfc3986\Uri 类在官方手册中标注为 PHP 8.5+。
• 规范化结果：scheme、host 大小写、百分号编码和路径点段会按 RFC 3986 重组。
• 缓存边界：服务端通常不读取页面 fragment，但如果业务把 fragment 当作资源维度，就必须保留它。

先分清 URL 表示差异和缓存业务语义

缓存键要回答的是“这一次请求应该复用哪一份结果”，而不是“两个字符串看起来是否相似”。scheme 和 host 的大小写、未保留字符的百分号表示、路径中的 . 或 ..，属于 URI 的表示层差异；而 query 是否可换序、某个参数是否是追踪参数，则属于接口业务规则。

fragment 只在客户端定位页面资源，通常不会随 HTTP 请求发送到服务端，所以常规接口缓存可以不让 #top 和 #comments 影响键。但这不是无条件的删除规则：如果你的应用把 fragment 交给前端渲染不同资源，或者在内部协议中使用它，就要把它纳入键设计。

用 toString 生成规范化 URI 基线

Uri\Rfc3986\Uri::toString() 会重新组合规范化 URI。官方说明包括：十六进制转义序列转为大写、百分号编码的未保留字符解码、scheme 与 host 转小写，以及移除路径点段。它适合作为缓存键的输入基线，但返回值仍然是完整 URI 字符串，不是已经按接口规则筛选过的缓存键。

toString();
}

$normalized = normalizeUri('HTTPS://Example.com/a/../b?lang=zh');
echo $normalized;
?>

这里的输出应作为“规范化基线”保存或继续加工。不要用对象直接参与字符串拼接来代替 toString()；PHP 官方 RFC 说明 URI 类没有提供隐式的 __toString()，显式调用能让缓存键的输入更清楚。

移除 fragment，再加上可升级的键空间前缀

对于典型的服务端接口，缓存键通常只关心服务端真正收到的资源定位信息。可以先把 fragment 设为 null，再取规范化字符串，并加上固定前缀。前缀既能隔离不同用途，也能在改变规范化策略时通过版本号主动放弃旧键。

withFragment(null)->toString();

    // 版本号用于区分未来的参数白名单或排序策略变化。
    return 'http-cache:v1:' . hash('sha256', $cacheUri);
}

try {
    $key = cacheKeyForUri('HTTPS://Example.com/a/../b?lang=zh#top');
    echo $key;
} catch (\Throwable $error) {
    // 生产代码应记录可定位的输入摘要，但不要把敏感 URL 原文写入公共日志。
    error_log('URI cache key rejected: ' . $error->getMessage());
}
?>

示例使用 SHA-256 只是为了让键长度稳定；如果缓存系统能安全承受完整 URI，也可以把 $cacheUri 直接放在带前缀的键中。无论选择哪种形式，都要在所有读取和写入路径复用同一个函数。

查询参数排序和过滤必须由接口契约决定

toString() 负责 URI 层的规范化，不等于会替你判断 query 参数的业务等价关系。例如 ?page=1&lang=zh 与 ?lang=zh&page=1 是否命中同一缓存，要看后端路由是否把参数当作无序集合；某些签名接口、重复参数接口和数组参数接口不能随意排序。

如果接口契约明确规定参数无序，可以在应用层解析 query、按参数名和约定的重复值规则排序，再重新组装 URI；如果契约没有明确规定，就保留 getQuery() 规范化后的原顺序。追踪参数也不能凭经验删除，应维护接口级白名单或明确的过滤配置，避免把两个实际不同的资源压成一个键。

withFragment(null);
    $query = $uri->getQuery();

    // 只有接口明确允许时才筛选参数，避免凭经验改变资源语义。
    if ($query !== null) {
        parse_str($query, $parameters);
        $parameters = array_intersect_key($parameters, array_flip($allowedQueryNames));
        ksort($parameters);
        $uri = $uri->withQuery(http_build_query($parameters, '', '&', PHP_QUERY_RFC3986));
    }

    // 键前缀与策略版本保持稳定，策略变化时递增 v2。
    return 'product-page:v1:' . hash('sha256', $uri->toString());
}
?>

这段代码只适合“参数可以转成普通键值表、重复参数语义已被接口约定”的接口。若接口依赖重复参数顺序、空值区分或嵌套数组，应写专门的规范化器，不要直接套用 parse_str() 后排序。

上线前把读取、写入和升级边界收拢

最后把缓存读取和写入都接到同一套键函数上，并为异常输入设置明确处理。观察命中率时，至少区分“原始 URL 不同但规范化结果相同”和“业务参数确实不同”两类情况；这能帮助定位是键策略重复，还是接口本身存在不一致。

常见问题

Uri\Rfc3986\Uri 能在旧版 PHP 上直接使用吗？

官方类手册标注为 PHP 8.5+。旧版环境不能假设存在该内置类，应先按项目支持版本选择兼容的 URI 解析方案，不要只复制本文的类名。

toString() 会自动把 query 参数排序吗？

不能把它当作业务排序器。它负责 RFC 3986 语义下的 URI 重组；参数是否无序、重复参数如何处理、哪些参数可过滤，都需要接口契约单独规定。

为什么不直接用 equals() 判断缓存命中？

equals() 适合比较两个同规范 URI 对象是否等价，默认排除 fragment；缓存系统仍需要一个稳定的字符串或哈希键，以及键空间、过期和升级策略。

缓存键应该存完整 URL 还是哈希值？

完整 URL 便于排查，哈希值长度稳定且适合有键长限制的后端。无论选择哪一种，都应保留版本前缀，并让读取与写入共享同一规范化函数。