89 lines
4.5 KiB
Markdown
89 lines
4.5 KiB
Markdown
# 3.7 路由与元数据注册（RouteSpec）
|
||
|
||
:::tip 概述
|
||
本项目的路由**只有一处声明**：`router.go` 内每个控制器的 RouteSpec 表。注册、权限校验、操作日志、公开白名单、OpenAPI 文档全部从这一份声明派生，天然同步。
|
||
:::
|
||
|
||
## RouteSpec 字段
|
||
|
||
```go
|
||
// internal/router/bind.go
|
||
type RouteSpec struct {
|
||
Method string // HTTP 方法：GET/POST/PUT/DELETE（必填，否则不注册）
|
||
Path string // 路由模板，如 /api/link/detail/:id（必填）
|
||
Summary string // 接口摘要（OpenAPI）
|
||
Permission string // 权限节点 sys:link:page；空表示登录即可
|
||
Log string // 操作日志标题；空表示不记录
|
||
LogType string // 日志类型：query/add/update/delete/import/export/reset…
|
||
Public bool // 免登录（登录、验证码等）
|
||
}
|
||
```
|
||
|
||
## 注册写法
|
||
|
||
在 `internal/router/router.go` 的 `registerControllers` 内，为控制器集中声明（方法名 → 路由元数据，按字典序排列）：
|
||
|
||
```go
|
||
// internal/router/router.go
|
||
Bind(rg, new(handler.CExample), map[string]RouteSpec{
|
||
"Add": {Method: "POST", Path: "/api/example/add", Summary: "新增案例演示", Permission: "sys:example:add", Log: "案例演示-新增记录", LogType: "add"},
|
||
"BatchDelete": {Method: "DELETE", Path: "/api/example/batchDelete", Summary: "批量删除案例演示", Permission: "sys:example:batchDelete", Log: "案例演示-批量删除记录", LogType: "delete"},
|
||
"Delete": {Method: "DELETE", Path: "/api/example/delete/:id", Summary: "删除案例演示", Permission: "sys:example:delete", Log: "案例演示-删除记录", LogType: "delete"},
|
||
"Detail": {Method: "GET", Path: "/api/example/detail/:id", Summary: "案例演示详情", Permission: "sys:example:detail", Log: "案例演示-查询详情", LogType: "query"},
|
||
"Export": {Method: "GET", Path: "/api/example/export", Summary: "导出案例演示", Permission: "sys:example:export", Log: "案例演示-导出数据", LogType: "export"},
|
||
"Import": {Method: "POST", Path: "/api/example/import", Summary: "导入案例演示", Permission: "sys:example:import", Log: "案例演示-导入数据", LogType: "import"},
|
||
"List": {Method: "GET", Path: "/api/example/list", Summary: "案例演示列表", Permission: "sys:example:list", Log: "案例演示-查询列表", LogType: "query"},
|
||
"Page": {Method: "GET", Path: "/api/example/page", Summary: "案例演示分页", Permission: "sys:example:page", Log: "案例演示-查询分页记录", LogType: "query"},
|
||
"Status": {Method: "PUT", Path: "/api/example/status", Summary: "案例演示状态", Permission: "sys:example:status", Log: "案例演示-设置状态", LogType: "update"},
|
||
"Update": {Method: "PUT", Path: "/api/example/update", Summary: "修改案例演示", Permission: "sys:example:update", Log: "案例演示-修改记录", LogType: "update"},
|
||
})
|
||
```
|
||
|
||
## 注册后发生什么
|
||
|
||
`router.Bind` 反射扫描控制器：
|
||
|
||
```text
|
||
按签名筛选方法（ctx, *dto.Req）→（*dto.Res, error）
|
||
│
|
||
▼
|
||
按方法名查 RouteSpec 表 → rg.Handle(Method, Path, 包装函数)
|
||
│
|
||
▼
|
||
包装函数内：绑定解析（path > body > query）→ binding 校验 → 调 handler → 信封响应
|
||
│
|
||
▼
|
||
写入路由元数据表（方法名、路径、权限码、日志配置、公开标记）
|
||
│
|
||
▼
|
||
authz / operation_log / public / OpenAPI 从元数据表消费同一份声明
|
||
```
|
||
|
||
## 声明规约
|
||
|
||
| 项 | 规约 |
|
||
|---|---|
|
||
| 路径 | `/api/{模块}/{动作}`，路径参数用 `:id` |
|
||
| 方法映射 | 查询 GET / 新增 POST / 修改 PUT / 删除 DELETE |
|
||
| 权限码 | `sys:{模块}:{动作}`，动作与路径动词一致 |
|
||
| Permission 为空 | 登录即可访问（不校验权限点） |
|
||
| Log 为空 | 不记录操作日志；查询类是否记录还受 `operationLog.logQuery` 开关控制 |
|
||
| Public | 仅登录、验证码、令牌兑换等真正公开接口使用 |
|
||
| 顺序 | 表内按方法名字典序排列，与既有条目风格逐字一致 |
|
||
|
||
## 新增接口的完整动作
|
||
|
||
1. dto 加请求/响应结构
|
||
2. service 加方法
|
||
3. handler 加同签名方法
|
||
4. RouteSpec 表加一条声明
|
||
5. 需要权限点时在菜单管理中配置权限节点（见下一页）
|
||
|
||
## 底层机制深入
|
||
|
||
反射细节、元数据表结构、中间件如何消费元数据 → [4.4 反射元数据驱动机制](/zh/architecture/bind-mechanism.html)。
|
||
|
||
## 下一步
|
||
|
||
→ [3.8 参数校验与错误上抛](/zh/guide/validation.html)
|