RouterGroup 和路由

相关源文件

• fs.go
• fs_test.go
• gin_integration_test.go
• path.go
• path_test.go
• routergroup.go
• routergroup_test.go
• tree.go
• tree_test.go

本文档介绍了 Gin 框架中的 RouterGroup 组件和路由系统。RouterGroup 是一个基础机制，用于组织具有共同路径前缀和中间件的路由；而路由系统则能高效地将传入的 HTTP 请求匹配到相应的处理程序。

有关整体 Engine 架构的信息，请参阅 Engine。有关传递给处理程序的 Context 对象详情，请参阅 Context。

RouterGroup 概览

RouterGroup 是 Gin 的核心抽象，它允许将路由组织成逻辑组。它将路由与共同的路径前缀和共享的中间件处理程序关联起来。

来源：routergroup.go52-60 routergroup.go26-51

RouterGroup 结构

RouterGroup 类型定义如下字段

Engine 本身就嵌入了 RouterGroup，这意味着 Engine 继承了 RouterGroup 的所有方法。这就是为什么您可以直接在 Engine 实例上调用路由方法的原因。

来源：routergroup.go53-60

路由注册方法

RouterGroup 提供了用于注册不同 HTTP 方法路由的方法

方法	描述
GET(path, ...handlers)	注册一个 GET 路由
POST(path, ...handlers)	注册一个 POST 路由
PUT(path, ...handlers)	注册一个 PUT 路由
DELETE(path, ...handlers)	注册一个 DELETE 路由
PATCH(path, ...handlers)	注册一个 PATCH 路由
HEAD(path, ...handlers)	注册一个 HEAD 路由
OPTIONS(path, ...handlers)	注册一个 OPTIONS 路由
Any(path, ...handlers)	为所有 HTTP 方法注册路由
Match(methods, path, ...handlers)	为指定的方法注册路由

所有这些方法最终都会调用内部的 handle 方法，该方法会

1. 通过结合组的基本路径和路由的相对路径来计算绝对路径
2. 将组的中间件处理程序与路由特定的处理程序相结合
3. 将路由添加到 Engine 的路由树中

来源：routergroup.go93-162 routergroup.go86-91

请求路由流程

当收到请求时，Gin 会通过几个组件来路由它

来源：tree.go423-675

创建路由组

RouterGroup 最强大的方面在于能够创建嵌套组

要创建一个新组

此方法创建一个新组，具有

• 一个结合了父级路径和相对路径的基本路径
• 来自父级和任何新处理程序的中间件处理程序
• 对同一个 Engine 的引用

来源：routergroup.go70-78 routergroup.go241-252

路由组中的中间件

RouterGroup 的一个关键优势在于能够将中间件应用于一组路由

当匹配到组内的路由时，该组的所有中间件处理程序将在路由处理程序之前执行。执行顺序是：

1. 来自父组的中间件（从外到内）
2. 来自当前组的中间件
3. 路由特定的处理程序

来源：routergroup.go64-68 routergroup.go241-248

路径参数和通配符

Gin 的路由系统支持两种动态路径段

1. 路径参数（:param）：匹配单个路径段

   • 例如：/user/:id 匹配 /user/123，参数 id=123

2. 捕获所有参数（*param）：匹配路径的剩余部分

   • 例如：/files/*filepath 匹配 /files/images/logo.png，参数 filepath=/images/logo.png

这些参数可在 Context 的 Params 集合中访问。

来源：tree.go23-50 tree.go261-296

路由树

在 RouterGroup API 的底层，Gin 使用了一个高度优化的基数树（前缀树）来进行路由匹配

树由这些数据结构表示

对于每种 HTTP 方法（GET、POST 等），都有一个单独的树。该算法根据路径段遍历树来查找匹配的路由。

来源：tree.go52-66 tree.go100-118

静态文件服务

RouterGroup 提供了几种用于提供静态文件的服务方法

这些方法内部创建了用于处理静态文件请求的路由。它们还支持一个特殊的 OnlyFilesFS 文件系统包装器，可以禁用目录列表。

来源：routergroup.go164-238 fs.go12-51

路由注册示例

以下是一个如何使用 RouterGroup 来组织典型 API 的示例

来源：routergroup_test.go18-33 routergroup_test.go45-89

路径清理和规范化

在注册路由和匹配请求时，Gin 会规范化路径以确保一致的行为。 cleanPath 函数会

1. 确保路径以斜杠开头
2. 删除重复的斜杠
3. 解析相对路径段（. 和 ..）

例如，/users//profile/./ 会变成 /users/profile/。

来源：path.go8-123

结论

RouterGroup 是 Gin 中一个强大的抽象，它允许开发人员将路由组织成具有共享路径和中间件的逻辑组。结合 Gin 高性能的路由树，它既提供了定义路由的简洁 API，又实现了高效的请求匹配。

Engine 嵌入了 RouterGroup，继承了其所有方法，这使得可以直接在路由器上定义路由的流畅 API。路由系统支持各种模式，包括静态路径、路径参数和通配符，使其足够灵活以适应复杂的 API 设计。