路径参数

路径参数是端点路径模板（例如/orders/{id} ）中的一个占位符，客户端会填充该占位符以访问特定实例。与查询参数不同，路径参数是资源标识的一部分： /orders/42和/orders/43是不同的资源，而/orders ?status=open 则是对同一资源的另一种访问方式。

工作原理

服务器将路径与其模板进行匹配，提取路径段并进行验证：如果预期为数字的 ID 为非数字，则返回 400；如果 ID 格式正确但后面没有任何内容，则返回 404。值必须进行百分比编码——否则，值中的斜杠会将路径拆分为不同的路由。

误解

404 错误通常意味着 URL 中存在拼写错误。对于路径参数，它更常意味着资源已被删除、从未存在过，或者资源存在但调用者可能并不知道——某些 API 会故意返回 404 而不是 403，以避免确认 ID 的真实性。

点击这里试试

每个 API 的路径中都包含 ID。Voxel Worlds API 在 GET /voxel/v1/worlds/{id}/blocks/{x}/{y}/{z}中一次接受三个 ID，而 World Cup API 在 GET /worldcup/v1/groups/{letter}/standings.

相关内容

• HTTP 404 Not Found
• 查询参数

资料来源

• HTTP semantics — RFC 9110
• OpenAPI Initiative

其他术语

• 查询参数 — URL 中问号后面的键值对，用于过滤、排序、分页或调整端点返回的内容。
• REST API — 将系统建模为可寻址资源的 API，可通过标准 HTTP 方法进行操作。
• API 端点 — 一个 URL 加上一个 HTTP 方法——客户端可以调用的最小 API 单元。
• HTTP 标头 — 每个请求和响应都会发送名称-值元数据，与请求体分开。
• HTTP 状态码 — 每个 HTTP 响应开头的三位数，在响应体之前，表示发生了什么。
• 内容谈判 — 客户端和服务器通过标头而不是单独的 URL 来约定响应格式。

阅读英文版

所有术语 · 测试技巧 · 全部 39 个模拟 REST API

最后更新时间 2026年10月16日