@fedify/uri-template

中文文档
2.4.6发布于 2026/11/17MITTypeScriptESM + CJS零依赖构建来源已验证近 30 天下载 6.4万

RFC 6570 URI 模板扩展和回合模式匹配

中文使用文档
文档目录7 节
  1. 为什么 @fedify/uri-template ? 吗?
  2. 为什么替换 url 模板 与 Template ? 吗?
  3. 为什么替换 里- 后期- 路由器 与 Router ? 吗?
  4. 特征
  5. HTTP 路径相容性
  6. 路线可变制约因素
  7. 安装

@fedify/uri-template: Counter-trip RFC 6570 URI (英语). 模板库

JSR npm

此软件包提供了 RFC 6570 (法语) 执行的 URI 模板执行 扩展和图案都与往返验证相匹配。 这是其中的一部分 页:1 联邦 框架,但可以独立使用.

为什么 @fedify/uri-template? 吗?

合并以前依赖两个独立的第三方实施: url 模板 用于 URI 模板扩展和 里- 后期- 路由器 页:1 路径匹配. @fedify/uri-template 用一个严格的RFC 6570取代两者 解析器和一个扩展/匹配模型.

为什么替换 url 模板 与 Template? 吗?

url 模板 自我描述为 RFC 6570 执行,但其行为 并不足以满足Fedify的URI路由和往返匹配需求. 测试在 旧/url-template.ts 记录与 npm:url-template@^3.1.1。 。 。 .

主要的失败是:

  • 它以可变名称命名时的 pct-encod 三重码 运算符发出可变名称。 譬如说, {?abc%20def} 扩展至 ?abc%2520def=spaced 改为 ?abc%20def=spaced。 。 。 . RFC 6570 第2.3节 允许 pct-encoded 内部 varname 并把它当作 变量名称. RFC 6570 第3.2.8节 以字面形式发出变量名称 字符串,以及 RFC 6570 第2.1节 许可 pct-encoded 字义. 因此 %20 财务报告和审定财务报表 %41 必须保存,不得再次编码为 %2520 财务报告和审定财务报表 %2541。 。 。 .
  • 它接受畸形模板而不是报告语法错误. RFC 6570 第2节 要求用匹配的括号来定义表达式, RFC 6570 第2.1节 不包括原始括号、控制字符、空格、原始 % 除了一个被编码的三胞胎 和其他被禁的字形字符之外 RFC 6570 第3节 表示语法错误应显示其位置和类型 适用于援引的申请. @fedify/uri-template 报告这些案件为: 输入错误.
  • 它对列表和 关联阵列. RFC 6570 第2.4.1节 表示前缀修改符不是 适用于具有复合值的变量,因此 {list:3}, (中文(简体) ), {keys:3}, (中文(简体) ), 财务报告和审定财务报表 {count:2} 必须失败.

Template 被写成一个新的执行而不是包 url 模板 因为 Fedify 需要严格的 RFC 6570 扩展, 键入语法 错误,以及往返检查的匹配行为. 需要申请 较宽松的剖析器可以明确选择: strict: false 传阅和扩展 错误到 report 没有扔, 和习惯 report 函数可以允许 所有出错或只为所选出错类别投出.

为什么替换 里- 后期- 路由器 与 Router? 吗?

上一个路由器形状结合了两个独立的第三方 执行: url 模板 用于构建 URL 和 里- 后期- 路由器 页:1 匹配 URL. (原始内容存档于2013-10-12). old/uri-template-router.ts 定义旧形状为 尽可能紧密地使差异可见于同一路由 API 下.

重要的区别是:

  • 构建、匹配和可变提取均使用相同的严格RFC 6570 par. 上一个路由器以 url 模板 但与之相匹配的是 里- 后期- 路由器,因此一个值可以通过一个执行编码 由另一个有不同规则的人解码.
  • 路线匹配已检查 。 只接受候选路线 当恢复的值被扩展回精确输入URI时. 这个拒绝 符合解码后看起来合理但不能复制的 (原始内容存档于2013-10-10). Introduct URI. 默认情况下,匹配与输入的URI精确. trailingSlashInsensitive 能够使用更松散的路径查找 跟踪斜线差异,然后进行相同的回程检查.
  • Pct-encoded 三胞胎被保存在RFC 6570将其当作语法处理的地方. 字形三进制, pct- 编码可变名称, 并命名查询参数 例如 {?abc%20def} 保留 %20 而不是成为 %2520。 。 。 .
  • 预留的扩展值保持其编码形式,如果 (原始内容存档于2013-10-12). URI introduct. 在之前的匹配路径下, /files/a%2Fb 可能会 报告为 a/b, (中文(简体) ), /files/%30%23 作为 0#,且已编码的 UTF-8 octets 为 Unicode 文本 。 这些值不绕行到原始URI 同样的模板.
  • 路径模板由 Router.compile() 登记前. 独立的路由器接受普通的斜线前缀路径和 引导路径扩展窗体——以 {/var} 表达式,例如 {/identifier}/inbox。接受这种形状是一种 独立路线能力,独立于联邦:联邦 调度器路由对所需的标识符适用非空约束 (单位:千美元)nullable 默认为 false),因此是一条领先的路径扩展路线 注册,但仅在变量实际绑定时匹配 对于召回的路由,联邦建设者可能会拒绝这种形状 合同需要混凝土 identifier。 。 。 .
  • Router.variables() 财务报告和审定财务报表 Router.compile() 显示可变提取 不改变路由器。 遗产 Router.add() 返回变量为 登记路线的副作用.
  • 候选人查询将符号级状态三进制和倒置前缀相结合 翠丝 可索引路径模板——其表达式各有一个 变量 "", (中文(简体) ), /,或 + 操作员,永远不要直接坐着 与另一个表达方式相邻 翠丝 无法安全索引的形状会回到前缀 trie 键入每个路由的初始字面前缀。 两者的候选人 尝试被合并,去重复, 按字面顺序命令 长度、初始字面前缀长度、可变数和插入顺序 在轮回比赛前.
  • 克隆和路由替换不取决于复制可变个人 状态从 里- 后期- 路由器。路由器存储编译的模板和 活动路由条目直接, 使执行保持独立 和无依赖的运行时间.

与以前相比的具体差异 url 模板 财务报告和审定财务报表 里- 后期- 路由器 库被编码为只兼容寄存器 试验 软件包/设备/旧/旧 中. 这些测试在运行时故意失败 deno task test:old 因为他们 对 Fedify 的预期行为执行旧的库并记录 已知的遗产差距.

特征

  • 所有表达式类型的全RFC 6570扩展 (单位:千美元){var}, (中文(简体) ), {+var}, (中文(简体) ), {#var}, (中文(简体) ), {.var}, (中文(简体) ), {/var}, (中文(简体) ), {;var}, (中文(简体) ), {?var}, (中文(简体) ), {&var}(中文(简体) )
  • 与镜像扩展匹配的圆通模式:何时 match(uri) 返回数值, expand(values) === uri
  • 可变匹配制约(nullable, (中文(简体) ), multiple安全带 默认
  • 严格无脚本类型 any 在公众表面
  • 零运行时间依赖关系

HTTP 路径相容性

一些HTTP客户端,包括Mastodon,解码 %3A 改为 : 在请求路径中. 过 { allowUnencodedColon: true } 改为 Router.route() 以接受字义 在可变值中冒出可扩展值 %3A数字 :

const router = new Router([["/users/{identifier}", "actor"]]);
router.route("/users/alice:work", { allowUnencodedColon: true });
// { name: "actor", template: "/users/{identifier}",
//   values: { identifier: "alice:work" } }

精确匹配,包括配置的后继斜线重试,优先进行 超过与结肠相匹配的匹配。 文字模板文本仍然完全匹配, 和其他百分数编码字符保持其现有的匹配规则. 当模板使用冒号来分隔变量时,在数值中解码出冒号 可使边界模糊; 匹配遵循已有的后轨 秩序。 秩序.

为收到的HTTP请求提供此选项。 URI 生成和 Context.parseUri() 保持他们现有的行为。 独立 Template.match() 财务报告和审定财务报表 Router.route() 没有选择权,也保持精确.

路线可变制约因素

Router 登记每个 RFC 6570 运算符,但匹配受到限制 每个模板变量. Router.add(), (中文(简体) ), Router.register(),则 构造器,以及 Router.from() 接受路由为 [pathOrPattern, name, options?] tuple,其中可选的第三个元素 是每条路由选项对象 :

import { Router } from "@fedify/uri-template";

const router = new Router();
router.add("/users/{identifier}", "actor");
router.add("/search{?q}", "search", {
  variables: { q: { nullable: true } },
});

options.variables 将变量名称映射到部分约束; 任何 字段中省略到默认值,任何模板变量 不列出清单仍然受到所有违约限制的限制。 这个 制约领域是:

  • nullable 默认为 false: 未绑定或绑定的变量 改为空值使路由不匹配(路由器返回到 下一个候选人。 过 { nullable: true } 选择退出,所以 可选运算符,例如 {?q} 可能与 q 缺席。 因为 此默认路径、可选操作路径和主路径扩展路径 注册成功, 但仅在变量实际时匹配 现相而无空相.
  • multiple 来源于可变规格:爆炸 (单位:千美元){tags*}隐含 true 并绑定 readonly string[]; 前缀 修改者({id:3}隐含 false; 普通变量默认为 false (有约束力) string但无论哪种方式,都可以设定。 指定a multiple 与衍生值相矛盾,或使用相同的 具有相冲突爆炸/前缀修改器的可变名称({x} 财务报告和审定财务报表 {x*}),投掷 ConflictingVarSpecError 在注册时间.
  • duplicable 默认为 false: 一个变量,出现在更多 大于同一模板内的一个可变规格 DuplicateRouteVariableError 在注册时间。 准备吧 true (a) 允许重复发生 URI 匹配 .
  • prefixable 默认为 false(单位:千美元) {var:N} 前缀修改符 规格抛出 DisallowedVarSpecModifierError 除非 变量已标记 { prefixable: true }。 。 。 .
  • explodable 默认为 false: 这是一个 登记 权限,而不是输出形状声明。 A 类 {var*} 爆炸修改器规格抛出 DisallowedVarSpecModifierError 除非该变量被标记 { explodable: true }; 选项 本身不会将一个值变成列表。 一个值成为 readonly string[] 仅在模板实际使用爆炸时 修改者({var*}),因为这个 verspec 是决定 multiple 改为 true。同样的 { explodable: true } 设定在非爆炸光谱上 例如 /users/{id} 仍会绑起平板 string 在运行时间.
  • operatables 默认为 [],允许每个操作员. 当设置为非空运算符列表时( W)"", (中文(简体) ), "+", (中文(简体) ), "#", (中文(简体) ), ".", (中文(简体) ), "/", (中文(简体) ), ";", (中文(简体) ), "?", (中文(简体) ), "&"),使用任意运算符下的变量 列表外抛出 DisallowedOperatorError 登记时 时间.

选项对象也接受 exact,默认为 true数字 : 当你提供 variables 对象,其密钥必须匹配模板的 变量 – 每个模板变量必须列出,没有未知 密钥可能出现, 否则注册丢弃 RouteTemplateOptionsNotMatchedError设置 { exact: false } 放松点 如此未列出的变量保持其默认值,未知的密钥是 被忽略 。 未注册的路由 variables 对象不受影响 并保持所有默认值.

const router = new Router();

// Throws RouteTemplateOptionsNotMatchedError: `id` is not listed.
router.add("/posts/{slug}/{id}", "post", {
  variables: { slug: { nullable: true } },
});

// OK: opt out of the exact-keys check.
router.add("/posts/{slug}/{id}", "post", {
  exact: false,
  variables: { slug: { nullable: true } },
});

// OK: explode requires opting in.
router.add("/tags{/tags*}", "tags", {
  variables: { tags: { explodable: true } },
});

Router.route() 通用于约束图,所以 values 缩进 因此:

const constraints = {
  identifier: { nullable: false, multiple: false },
} as const;
router.add("/users/{identifier}", "actor", { variables: constraints });

const matched = router.route<typeof constraints>("/users/alice");
if (matched != null) {
  const id: string = matched.values.identifier;
}

收缩类型来源于 multiple 财务报告和审定财务报表 nullable 只是,从来没有 从 explodable。自 explodable 管辖登记,而不是 解析值形状,爆炸路线必须携带 multiple: true 在类型参数中——不仅仅是 explodable: true- 因为 values 缩小 改为 readonly string[]数字 :

const tagConstraints = {
  tags: { explodable: true, multiple: true },
} as const;
router.add("/tags{?tags*}", "tags", { variables: tagConstraints });

const matched = router.route<typeof tagConstraints>("/tags?tags=a&tags=b");
if (matched != null) {
  const tags: readonly string[] = matched.values.tags;
}

安装

deno add jsr:@fedify/uri-template  # Deno
npm  add     @fedify/uri-template  # npm
pnpm add     @fedify/uri-template  # pnpm
yarn add     @fedify/uri-template  # Yarn
bun  add     @fedify/uri-template  # Bun

版本与发布记录

@fedify/uri-template 共发布 238 个版本,首次发布于 2025/11/04;过去 12 个月发布了 237 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
2.4.6latest2026/11/17今天
2.5.0-dev.2855dev2026/11/17今天
2.3.162026/11/17今天
2.3.16-dev.28452026/11/17今天
2.5.0-dev.28442026/11/17今天
2.3.16-dev.28412026/11/17今天

其他发布通道:pr-809 → 2.3.0-pr.809.39,pr-934 → 2.4.0-pr.934.40,pr-936 → 2.4.0-pr.936.41,pr-1020 → 2.4.0-pr.1020.43,pr-1006 → 2.4.0-pr.1006.44,dev → 2.5.0-dev.2855。

关于 @fedify/uri-template 的常见问题

@fedify/uri-template 是什么?

RFC 6570 URI 模板扩展和回合模式匹配

如何安装 @fedify/uri-template?

在项目目录运行 npm install @fedify/uri-template,或使用 pnpm add / yarn add / bun add。

@fedify/uri-template 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@fedify/uri-template 支持 ESM 还是 CommonJS?

同时提供 ES Module 与 CommonJS 入口,import 和 require() 都可以使用,打包工具会自动选择合适的版本。

@fedify/uri-template 需要什么版本的 Node.js?

package.json 的 engines 字段要求 Node.js >=22.0.0。版本不符时 npm 默认只给出警告,开启 engine-strict 后会拒绝安装。

@fedify/uri-template 可以商用吗?

@fedify/uri-template 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@fedify/uri-template 的下载量有多少?

根据 npm 官方下载统计,@fedify/uri-template 在 2026/10/15 – 2026/11/13 这 30 天内被下载 64,464 次,日均约 2,149 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@fedify/uri-template 还在维护吗?

最新版本 2.4.6 发布于 2026/11/17(今天);至今共发布 238 个版本,其中过去 12 个月发布了 237 个;首次发布于 2025/11/04。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。