了解路径模板

在 API Gateway 中，可以根据路径模板路由传入的请求。路径模板包含三个主要组件：

  • 完全匹配
  • 单通配符匹配
  • 双通配符匹配

以下各部分介绍了其中每个组件及其在 API Gateway 环境中的工作原理。

完全匹配

不含任何单个或双重通配符段（* 或 **）的模板化路径会转换为完全路径匹配。例如，网关 API 配置的 OpenAPI 规范可能包含如下部分：

...
paths:
  /shelves:
    get:
      summary: List shelves
...

在此示例中，网关仅接受对 /shelves 的请求，而不接受其他路径。

单个通配符匹配

如果模板化路径包含变量和/或单个通配符段（例如 {var} 或 {var=*}），则网关将允许符合以下条件的传入请求：

  • 请求不包含额外的正斜杠 (/)，这意味着变量将仅匹配一个路径段。
  • 请求至少包含一个字符。
  • 请求可以包含一个额外的尾随斜杠（如果路径末尾处存在斜杠）。

例如，网关 API 配置的 OpenAPI 规范可能包含如下所示的部分：

...
paths:
  /shelves/{shelf}/books/{book}: # Equivalent to /shelves/{shelf=*}/books/{book=*}
    get:
      summary: Retrieve a book
...

在此示例中，网关将接受与以下正则表达式匹配的请求：

^/shelves/[^/]+/books/[^/]+/?$

双通配符匹配

如果模板化路径包含由双通配符段表示的变量（例如 {var=**}），则网关将允许符合以下条件的传入请求：

  • 请求可以包含所有字符，包括正斜杠 (/)。
  • 请求可以包含 0 个或多个字符。
  • 请求可以包含一个额外的尾随斜杠（如果路径末尾处存在斜杠）。

例如，网关 API 配置的 OpenAPI 规范可能包含如下所示的部分：

...
paths:
  /shelves/{shelf=*}/books/{book=**}:
    get:
      summary: Retrieve a book
...

在此示例中，网关将接受与以下正则表达式匹配的请求：

^/shelves/[^/]+/books/.*/?$

网址编码正斜线

API Gateway 遵循 RFC 3986，在匹配网址路径或安全决策时，不会将网址编码的正斜杠 (%2F) 视为实际斜杠。如果需要使用网址编码斜杠，您的后端应相应地处理这些请求。

例如，请考虑以下 OpenAPI 规范：

securityDefinitions:
  api_key:
    type: "apiKey"
    name: "key"
    in: "query"
paths:
  /shelves/{shelf}:
      get:
        parameters:
        - in: path
          name: shelf
          type: string
          required: true
          description: Shelf ID.
        summary: List shelves
        operationId: GetShelf
          responses:
            '200':
              description: A successful response
              schema:
                type: string
    /shelves/{shelf}/books/{book}:
      get:
        parameters:
        - in: path
          name: shelf
          type: string
          required: true
          description: Shelf ID.
        - in: path
          name: book
          type: string
          required: true
          description: Book ID
        summary: Retrieve a book
        operationId: GetBook
          responses:
            '200':
              description: A successful response
              schema:
                type: string
         security:
         - api_key: []

在此示例中，/shelves/{shelf}/books/{book} 操作需要 API 密钥，但 /shelves/{shelf} 操作不受限制。

如果用户向 /shelves/shelf_1%2Fbooks%2Fbook_2 发送请求，则执行以下操作：

  • 网关会将请求作为书架 ID shelf_1%2Fbooks%2Fbook_2 的 GetShelf 操作处理。在这种情况下，API 密钥检查未强制执行。
  • 如果在后端进行任何请求处理之前将 %2F 标准化，则请求可能会作为图书 ID book_2 的 GetBook 操作进行处理。换句话说，后端将 /shelves/shelf_1%2Fbooks%2Fbook_2 处理为 /shelves/shelf_1/books/book_2。

在此示例中，后端期望 GetBook 操作在网关执行 API 密钥检查。但是，由于网关以 GetShelf 操作的形式读取请求，因此未执行 API 密钥检查。

多个相邻正斜线的标准化

API Gateway 遵循 RFC 3986，指出具有多个相邻正斜杠的路径将被视为与具有单正斜杠的路径不同。例如，包含/shelves///将未由网关进行标准化到请求路径/shelves/在匹配 URI 路径模板之前或转发到指定的后端时。