suryaansh.dev

Central vs Modular Router Registration Tradeoffs

3 min read

When building web applications, one of the most fundamental design decisions is how you organize your routes. While both Go (Gin) and Python (FastAPI) are high-performance frameworks, they approach route registration with different philosophies.

In the Go world, you often encounter the Central Router pattern, whereas FastAPI champions the Modular Router (APIRouter) pattern.

The Central Router Pattern (Go / Gin)

In Gin, the gin.Engine is the heart of the application. The common pattern is to create this engine in your entry point and pass it into various “setup” functions across your packages.

// main.go
func main() {
    r := gin.Default()
    
    // Explicitly calling registration functions
    routes.RegisterUserRoutes(r)
    routes.RegisterOrderRoutes(r)
    
    r.Run()
}
 
// routes/user.go
func RegisterUserRoutes(r *gin.Engine) {
    users := r.Group("/users")
    {
        users.GET("/:id", GetUser)
    }
}

The Philosophy: Explicit & High Performance

  • The Engine is King: All routes eventually belong to the one Engine instance.
  • Top-Down Flow: You can see exactly which modules are being registered just by looking at main.go.
  • Performance: Gin’s tree-based router is optimized for speed. By centralizing registration, the framework can build its internal route tree efficiently at startup.

The Modular Router Pattern (Python / FastAPI)

FastAPI (and Starlette) uses the APIRouter class. Each module or feature is treated like a “mini-app” that defines its own routes independently and is later “included” into the main application.

# routers/users.py
from fastapi import APIRouter
 
router = APIRouter(prefix="/users", tags=["users"])
 
@router.get("/{id}")
def get_user(id: int):
    return {"user_id": id}
 
# main.py
from fastapi import FastAPI
from .routers import users
 
app = FastAPI()
app.include_router(users.router)

The Philosophy: Encapsulation & Decoupling

  • Self-Contained: The users.py module doesn’t need to know anything about the main app. It defines its own prefixes, tags, and dependencies.
  • Lazy Integration: The main application just acts as a “collector” of these pre-defined router objects.
  • Developer Velocity: This feels more natural for large teams where different people own different modules; you rarely have to touch the main entry point once the router is included.

Comparative Analysis

FeatureCentral (Gin)Modular (FastAPI)
ControlHigh. You see every registration call in one place.Medium. Details like prefixes are hidden in the module.
CouplingHigh. Sub-packages often need to import the framework types.Low. Modules define routers and export them.
Circular RefsRisk. Easy to hit circular imports if packages cross-reference.Minimal. Routers are usually leaf nodes in the import tree.
ScalabilityCan get messy in main.go without strict directory rules.Extremely scalable; scales naturally with the file system.

Why the Difference Matters

The “Circular Dependency” Trap in Go

In Go, if Package A imports Package B, Package B cannot import Package A. If you use a Central Router and try to have your routes package call a middleware package that also needs to know about routes, your build will fail. Gin developers often solve this by creating a “Router Interface” or keeping the registration logic very thin.

The “Tagging & Docs” Advantage in FastAPI

Because FastAPI’s APIRouter is modular, it can hold metadata. You can apply a “Dependency” (like Authentication) to an entire router in one line when including it. In Gin, you must remember to apply the middleware to the specific Group inside the registration function.

Which one should you use?

  • Use the Central Pattern when you prioritize performance and want to keep a strict, explicit map of your entire API in one or two files.
  • Use the Modular Pattern when building complex, domain-driven systems where “User” logic and “Payment” logic should be entirely decoupled.

Graph View