go-admingo-admin
  • Guide
  • Development
    • Advanced
    • Commands
  • Advanced
  • Help
  • GitHub
  • Changelog
⌘ K
Standard Practice
Standard Module Development
Backend Basics
Backend Directory Structure
Backend Config File
Starting the Backend
Frontend Basics
Frontend Directory Structure
Frontend Config File
Starting the Frontend
Development Patterns
Actions Pattern
Hand-Written Pattern
First API Endpoint
Layered Development
API Layer
Service Layer
DTO Definitions
Model Definitions
Router Registration
Multi-Environment Config
Database Table Conventions
Data Permissions
Response Format
Code Generation
Pre-Generation Setup
Generating Business Code
One-Click Menu Generation
Binding APIs to the Menu
Configuring Role Permissions
Verifying the Feature
Generating Code with an LLM
Advanced Capabilities
Runtime Core API
Authentication & Authorization
Logging
Request Tracing
Cache
Queue
File Upload
Rate Limiting
Scheduled Jobs
Air Hot Reload
Swagger Docs
Code Generation Tool
Last updated:
Open-source MIT Licensed | Copyright © 2020-present
Powered by go-admin-team

TABLE OF CONTENTS

‌
‌
‌
‌

Router Registration

Routing maps a URL to a handler, and decides which middleware that endpoint needs — whether login is required, whether role checks apply, whether data-permission scoping is injected.

go-admin's routes self-register through init() — there's no need to register anything by hand in a central file.

INFO

Every module needs this layer, whether it uses the Actions Pattern or the Hand-Written Pattern. The two patterns register routes differently: the former hangs a generic Action directly on the route, the latter calls a handler you wrote yourself.

package and import

go
package router


import (
	"github.com/gin-gonic/gin"
	jwt "github.com/go-admin-team/go-admin-core/sdk/pkg/jwtauth"
	"go-admin/app/admin/apis"
	"go-admin/common/middleware"
)

Registering Routes

MethodDescription
initthe package's init function
registerSyPostRouterroute registration — the built-in generic naming pattern go-admin uses

WARNING

go-admin's route registration function naming convention: Format: register{BusinessName}Router

If you're registering routes outside the code generator, follow this format.

go
func init() {
	routerCheckRole = append(routerCheckRole, registerSyPostRouter)
}


// Route code that requires authentication
func registerSyPostRouter(v1 *gin.RouterGroup, authMiddleware *jwt.GinJWTMiddleware) {
	api := apis.SysPost{}
	r := v1.Group("/post").Use(authMiddleware.MiddlewareFunc()).Use(middleware.AuthCheckRole())
	{
		r.GET("", api.GetPage)
		r.GET("/:id", api.Get)
		r.POST("", api.Insert)
		r.PUT("/:id", api.Update)
		r.DELETE("", api.Delete)
	}
}

The code above uses two middlewares:

  1. authMiddleware
  2. AuthCheckRole

So why these two?

Most systems need some level of security or permission control on their endpoints. These two middlewares handle that: one for login authentication, the other for role-based authorization.

Login Authentication Only

For endpoints that only need to confirm the caller is logged in, use just the authMiddleware middleware:

For example:

go
func init() {
	routerCheckRole = append(routerCheckRole, registerSyPostRouter)
}


// Route code that requires authentication
func registerSyPostRouter(v1 *gin.RouterGroup, authMiddleware *jwt.GinJWTMiddleware) {
	api := apis.SysPost{}
	r := v1.Group("/post").Use(authMiddleware.MiddlewareFunc())
	{
		r.GET("", api.GetPage)
		r.GET("/:id", api.Get)
		r.POST("", api.Insert)
		r.PUT("/:id", api.Update)
		r.DELETE("", api.Delete)
	}
}

Role-Based Authorization

For endpoints that need finer-grained permission control, combine both middlewares — authMiddleware and AuthCheckRole:

For example:

go
func init() {
	routerCheckRole = append(routerCheckRole, registerSyPostRouter)
}


// Route code that requires authentication
func registerSyPostRouter(v1 *gin.RouterGroup, authMiddleware *jwt.GinJWTMiddleware) {
	api := apis.SysPost{}
	r := v1.Group("/post").Use(authMiddleware.MiddlewareFunc()).Use(middleware.AuthCheckRole())
	{
		r.GET("", api.GetPage)
		r.GET("/:id", api.Get)
		r.POST("", api.Insert)
		r.PUT("/:id", api.Update)
		r.DELETE("", api.Delete)
	}
}

No Authorization Required

For endpoints that can be accessed anonymously, use neither authMiddleware nor AuthCheckRole:

For example:

go
func init() {
	routerNoCheckRole = append(routerNoCheckRole, registerSyPostRouter)
}


// Route code that does not require authentication
func registerSyPostRouter(v1 *gin.RouterGroup) {
	api := apis.SysPost{}
	r := v1.Group("/post")
	{
		r.GET("", api.GetPage)
		r.GET("/:id", api.Get)
		r.POST("", api.Insert)
		r.PUT("/:id", api.Update)
		r.DELETE("", api.Delete)
	}
}

WARNING

Note the difference between the two registration slices (defined in app/admin/router/router.go):

  • routerCheckRole: authenticated routes, function signature func(v1 *gin.RouterGroup, authMiddleware *jwt.GinJWTMiddleware)
  • routerNoCheckRole: unauthenticated routes, function signature func(v1 *gin.RouterGroup)

A route that needs no authorization must be registered to routerNoCheckRole — otherwise it still gets folded into the authenticated group's traversal.

WARNING

Where to get help:

If anything in this guide is unclear, please open an issue.