URI Template 详解：掌握 RFC 6570
在构建 RESTful API 时，最核心的概念之一就是如何使用 URI 来表示资源。硬编码 URL 是脆弱的，且会导致维护难题。RFC 6570 (URI Template) 提供了一种标准化的方法，使用占位符描述 URI，这些占位符随后可以扩展为最终的 URI。
在本指南中，我们将深入探讨 URI 模板的工作原理、不同的表达式类型，以及为什么它们对现代 Web 开发至关重要。
什么是 URI Template？
URI Template 是一个包含在花括号 {} 中的变量字符串。这些变量在被称为 Expansion (扩展) 的过程中被实际值替换。
基础示例：
模板：http://api.example.com/users/{id}
变量：{ "id": "123" }
扩展结果：http://api.example.com/users/123
URI Template 的 8 个级别
RFC 6570 定义了几个不同复杂程度的扩展级别。以下是最常用的几种：
1. 简单字符串扩展 {var}
用于简单的路径段。
- 模板：
/{var} - 值：
{"var": "value"} - 结果：
/value
2. 预留字符扩展 {+var}
与简单扩展类似，但允许预留字符（如 /、?、#）而不进行百分号编码。
- 模板：
/{+path}/index.html - 值：
{"path": "foo/bar"} - 结果：
/foo/bar/index.html
3. 片段扩展 {#var}
用于 URI 片段（锚点）。
- 模板：
{#var} - 值：
{"var": "section1"} - 结果：
#section1
4. 带点的标签扩展 {.var}
常用于文件扩展名。
- 模板：
/config{.format} - 值：
{"format": "json"} - 结果：
/config.json
5. 路径段扩展 {/var}
自动添加前导斜杠。
- 模板：
{/var} - 值：
{"var": "user"} - 结果：
/user
6. 查询参数扩展 {?var}
API 搜索和过滤最常用的类型。
- 模板：
/search{?q,lang} - 值：
{"q": "test", "lang": "en"} - 结果：
/search?q=test&lang=en
变量修饰符
URI Template 还支持修饰符来控制变量的扩展方式。
- Explode (
*)：用于数组或对象。- 模板：
/users{?id*} - 值：
{"id": [1, 2, 3]} - 结果：
/users?id=1&id=2&id=3
- 模板：
- Prefix (
:n)：仅取前n个字符。- 模板：
/{var:3} - 值：
{"var": "abcdef"} - 结果：
/abc
- 模板：
为什么要使用 URI Template？
- 解耦：客户端无需知道如何构造 URL；它只需要模板和变量。
- HATEOAS：对于“将超媒体作为应用状态引擎”至关重要。服务器可以在响应中提供模板。
- 一致性：提供了一种跨不同编程语言和库处理查询参数和路径段的标准方式。
常见问题 FAQ
问：{var} 与许多路由中使用的 :var 是一样的吗？
答：概念上是一样的，但 RFC 6570 是在文档和超媒体中如何表示这些变量的官方标准。大多数路由框架（如 Express 或 React Router）使用的是简化的专有语法。
问：如何处理预留字符？
答：默认情况下，简单扩展 {var} 会对预留字符进行百分号编码。如果您想保持原样，请使用 {+var}。
问：URI 模板区分大小写吗？
答：根据规范，变量名是区分大小写的。{var} 和 {VAR} 是不同的变量。