Back to Details

go-create-chi-router

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Go Create Chi Router

Go 创建Chi路由器

Generate Chi router implementations for Go backend HTTP transport layer.
为Go后端HTTP传输层生成Chi路由器实现。

Router File Structure

路由器文件结构

Location: 
internal/modules/<module>/http/chi/router/<resource>_router.go
位置：
internal/modules/<module>/http/chi/router/<resource>_router.go

Router Implementation

路由器实现

go
package router

import (
	"github.com/cristiano-pacheco/bricks/pkg/http/server/chi"
	"github.com/cristiano-pacheco/pingo/internal/modules/<module>/http/chi/handler"
)

type ResourceRouter struct {
	handler *handler.ResourceHandler
}

func NewResourceRouter(h *handler.ResourceHandler) *ResourceRouter {
	return &ResourceRouter{handler: h}
}

func (r *ResourceRouter) Setup(server *chi.Server) {
	router := server.Router()
	router.Get("/api/v1/resources", r.handler.ListResources)
	router.Get("/api/v1/resources/:id", r.handler.GetResource)
	router.Post("/api/v1/resources", r.handler.CreateResource)
	router.Put("/api/v1/resources/:id", r.handler.UpdateResource)
	router.Delete("/api/v1/resources/:id", r.handler.DeleteResource)
}
go
package router

import (
	"github.com/cristiano-pacheco/bricks/pkg/http/server/chi"
	"github.com/cristiano-pacheco/pingo/internal/modules/<module>/http/chi/handler"
)

type ResourceRouter struct {
	handler *handler.ResourceHandler
}

func NewResourceRouter(h *handler.ResourceHandler) *ResourceRouter {
	return &ResourceRouter{handler: h}
}

func (r *ResourceRouter) Setup(server *chi.Server) {
	router := server.Router()
	router.Get("/api/v1/resources", r.handler.ListResources)
	router.Get("/api/v1/resources/:id", r.handler.GetResource)
	router.Post("/api/v1/resources", r.handler.CreateResource)
	router.Put("/api/v1/resources/:id", r.handler.UpdateResource)
	router.Delete("/api/v1/resources/:id", r.handler.DeleteResource)
}

Router Patterns

路由器模式

Basic CRUD Routes

基础CRUD路由

go
func (r *ResourceRouter) Setup(server *chi.Server) {
	router := server.Router()
	router.Get("/api/v1/resources", r.handler.ListResources)
	router.Get("/api/v1/resources/:id", r.handler.GetResource)
	router.Post("/api/v1/resources", r.handler.CreateResource)
	router.Put("/api/v1/resources/:id", r.handler.UpdateResource)
	router.Delete("/api/v1/resources/:id", r.handler.DeleteResource)
}
go
func (r *ResourceRouter) Setup(server *chi.Server) {
	router := server.Router()
	router.Get("/api/v1/resources", r.handler.ListResources)
	router.Get("/api/v1/resources/:id", r.handler.GetResource)
	router.Post("/api/v1/resources", r.handler.CreateResource)
	router.Put("/api/v1/resources/:id", r.handler.UpdateResource)
	router.Delete("/api/v1/resources/:id", r.handler.DeleteResource)
}

Custom Endpoints

自定义端点

go
func (r *ResourceRouter) Setup(server *chi.Server) {
	router := server.Router()
	
	// Standard CRUD
	router.Get("/api/v1/resources", r.handler.ListResources)
	router.Post("/api/v1/resources", r.handler.CreateResource)
	
	// Custom actions
	router.Post("/api/v1/resources/:id/activate", r.handler.ActivateResource)
	router.Post("/api/v1/resources/:id/deactivate", r.handler.DeactivateResource)
	
	// Nested resources
	router.Get("/api/v1/resources/:id/items", r.handler.ListResourceItems)
	router.Post("/api/v1/resources/:id/items", r.handler.AddResourceItem)
}
go
func (r *ResourceRouter) Setup(server *chi.Server) {
	router := server.Router()
	
	// 标准CRUD
	router.Get("/api/v1/resources", r.handler.ListResources)
	router.Post("/api/v1/resources", r.handler.CreateResource)
	
	// 自定义操作
	router.Post("/api/v1/resources/:id/activate", r.handler.ActivateResource)
	router.Post("/api/v1/resources/:id/deactivate", r.handler.DeactivateResource)
	
	// 嵌套资源
	router.Get("/api/v1/resources/:id/items", r.handler.ListResourceItems)
	router.Post("/api/v1/resources/:id/items", r.handler.AddResourceItem)
}

Route Groups (with middleware)

路由组（含中间件）

go
func (r *ResourceRouter) Setup(server *chi.Server) {
	router := server.Router()
	
	// Public routes
	router.Get("/api/v1/resources", r.handler.ListResources)
	router.Get("/api/v1/resources/:id", r.handler.GetResource)
	
	// Protected routes (if auth middleware needed)
	router.Group(func(r chi.Router) {
		// r.Use(middleware.Auth) // Example if auth middleware exists
		r.Post("/api/v1/resources", r.handler.CreateResource)
		r.Put("/api/v1/resources/:id", r.handler.UpdateResource)
		r.Delete("/api/v1/resources/:id", r.handler.DeleteResource)
	})
}
go
func (r *ResourceRouter) Setup(server *chi.Server) {
	router := server.Router()
	
	// 公开路由
	router.Get("/api/v1/resources", r.handler.ListResources)
	router.Get("/api/v1/resources/:id", r.handler.GetResource)
	
	// 受保护路由（若需要认证中间件）
	router.Group(func(r chi.Router) {
		// r.Use(middleware.Auth) // 示例：若存在认证中间件
		r.Post("/api/v1/resources", r.handler.CreateResource)
		r.Put("/api/v1/resources/:id", r.handler.UpdateResource)
		r.Delete("/api/v1/resources/:id", r.handler.DeleteResource)
	})
}

Multiple Handlers

多处理器

go
type ResourceRouter struct {
	resourceHandler *handler.ResourceHandler
	itemHandler     *handler.ItemHandler
}

func NewResourceRouter(
	resourceHandler *handler.ResourceHandler,
	itemHandler *handler.ItemHandler,
) *ResourceRouter {
	return &ResourceRouter{
		resourceHandler: resourceHandler,
		itemHandler:     itemHandler,
	}
}

func (r *ResourceRouter) Setup(server *chi.Server) {
	router := server.Router()
	
	// Resource routes
	router.Get("/api/v1/resources", r.resourceHandler.ListResources)
	router.Post("/api/v1/resources", r.resourceHandler.CreateResource)
	
	// Item routes (related resource)
	router.Get("/api/v1/items", r.itemHandler.ListItems)
	router.Post("/api/v1/items", r.itemHandler.CreateItem)
}
go
type ResourceRouter struct {
	resourceHandler *handler.ResourceHandler
	itemHandler     *handler.ItemHandler
}

func NewResourceRouter(
	resourceHandler *handler.ResourceHandler,
	itemHandler *handler.ItemHandler,
) *ResourceRouter {
	return &ResourceRouter{
		resourceHandler: resourceHandler,
		itemHandler:     itemHandler,
	}
}

func (r *ResourceRouter) Setup(server *chi.Server) {
	router := server.Router()
	
	// 资源路由
	router.Get("/api/v1/resources", r.resourceHandler.ListResources)
	router.Post("/api/v1/resources", r.resourceHandler.CreateResource)
	
	// 子项路由（关联资源）
	router.Get("/api/v1/items", r.itemHandler.ListItems)
	router.Post("/api/v1/items", r.itemHandler.CreateItem)
}

Fx Wiring

Fx 依赖注入配置

Add to 
internal/modules/<module>/fx.go
:
go
fx.Provide(
	fx.Annotate(
		router.NewResourceRouter,
		fx.As(new(chi.Route)),
		fx.ResultTags(`group:"routes"`),
	),
),
Multiple routers in same module:
go
fx.Provide(
	fx.Annotate(
		router.NewResourceRouter,
		fx.As(new(chi.Route)),
		fx.ResultTags(`group:"routes"`),
	),
	fx.Annotate(
		router.NewItemRouter,
		fx.As(new(chi.Route)),
		fx.ResultTags(`group:"routes"`),
	),
),
添加至 
internal/modules/<module>/fx.go
:
go
fx.Provide(
	fx.Annotate(
		router.NewResourceRouter,
		fx.As(new(chi.Route)),
		fx.ResultTags(`group:"routes"`),
	),
),
同一模块中的多个路由器:
go
fx.Provide(
	fx.Annotate(
		router.NewResourceRouter,
		fx.As(new(chi.Route)),
		fx.ResultTags(`group:"routes"`),
	),
	fx.Annotate(
		router.NewItemRouter,
		fx.As(new(chi.Route)),
		fx.ResultTags(`group:"routes"`),
	),
),

HTTP Methods & Semantics

HTTP方法与语义

Follow REST conventions:
  • GET
    : Retrieve resources (list or single)
  • POST
    : Create new resources
  • PUT
    : Update existing resources (full update)
  • PATCH
    : Partial update (if needed)
  • DELETE
    : Remove resources
遵循REST规范:
  • GET
    : 获取资源（列表或单个）
  • POST
    : 创建新资源
  • PUT
    : 更新现有资源（全量更新）
  • PATCH
    : 部分更新（若需要）
  • DELETE
    : 删除资源

URL Path Conventions

URL路径规范

  • Version prefix: 
    /api/v1/
  • Resource names: Plural nouns (
    /resources
    , 
    /contacts
    , 
    /monitors
    )
  • Resource ID: Use 
    :id
    param (
    /resources/:id
    )
  • Nested resources: 
    /resources/:id/items
  • Actions: Use verbs for non-CRUD (
    /resources/:id/activate
    )
  • 版本前缀: 
    /api/v1/
  • 资源名称: 复数名词（
    /resources
    , 
    /contacts
    , 
    /monitors
    ）
  • 资源ID: 使用
    :id
    参数（
    /resources/:id
    ）
  • 嵌套资源: 
    /resources/:id/items
  • 操作: 非CRUD操作使用动词（
    /resources/:id/activate
    ）

Critical Rules

关键规则

  1. Struct: Holds handler(s) only
  2. Constructor: MUST return pointer 
    *ResourceRouter
  3. Setup method: MUST be named 
    Setup
    and take 
    *chi.Server
  4. Router access: Get router via 
    server.Router()
  5. Route format: Always start with 
    /api/v1/
    prefix
  6. Resource naming: Use plural nouns for resources
  7. Handler naming: Match handler method names to actions (e.g., 
    ListResources
    , 
    CreateResource
    )
  8. Fx wiring: MUST use 
    fx.As(new(chi.Route))
    and 
    fx.ResultTags(\
    group:"routes"`)`
  9. No comments: Do not add redundant comments above methods
  10. Imports: Only import 
    bricks/pkg/http/server/chi
    and handler package
  11. Dependencies: Handlers are injected via constructor
  12. Validation: Run 
    make lint
    after generation
  1. 结构体: 仅包含处理器依赖
  2. 构造函数: 必须返回指针
    *ResourceRouter
  3. Setup方法: 必须命名为
    Setup
    且参数为
    *chi.Server
  4. 路由器获取: 通过
    server.Router()
    获取路由器
  5. 路由格式: 始终以
    /api/v1/
    前缀开头
  6. 资源命名: 资源使用复数名词
  7. 处理器命名: 处理器方法名需与操作匹配（例如
    ListResources
    , 
    CreateResource
    ）
  8. Fx配置: 必须使用
    fx.As(new(chi.Route))
    和
    fx.ResultTags(\
    group:"routes"`)`
  9. 无冗余注释: 方法上方请勿添加冗余注释
  10. 导入: 仅导入
    bricks/pkg/http/server/chi
    和处理器包
  11. 依赖: 处理器通过构造函数注入
  12. 验证: 生成后运行
    make lint
    进行验证

Router Naming

路由器命名规则

  • Struct: 
    <Resource>Router
    (PascalCase)
  • Constructor: 
    New<Resource>Router
  • File: 
    <resource>_router.go
    (snake_case)
  • 结构体: 
    <Resource>Router
    （大驼峰命名）
  • 构造函数: 
    New<Resource>Router
  • 文件: 
    <resource>_router.go
    （蛇形命名）

Workflow

工作流程

  1. Create router file in 
    internal/modules/<module>/http/chi/router/<resource>_router.go
  2. Define struct with handler dependency
  3. Implement constructor
  4. Implement 
    Setup(server *chi.Server)
    method with routes
  5. Add Fx wiring to module's 
    fx.go
  6. Run 
    make lint
    to verify
  1. 在
    internal/modules/<module>/http/chi/router/<resource>_router.go
    创建路由器文件
  2. 定义包含处理器依赖的结构体
  3. 实现构造函数
  4. 实现带有路由的
    Setup(server *chi.Server)
    方法
  5. 将Fx配置添加至模块的
    fx.go
  6. 运行
    make lint
    进行验证

Common Route Patterns

常见路由模式

List with filters

带过滤条件的列表

go
router.Get("/api/v1/resources", r.handler.ListResources) // query params in handler
go
router.Get("/api/v1/resources", r.handler.ListResources) // 处理器中处理查询参数

Nested resource access

嵌套资源访问

go
router.Get("/api/v1/resources/:resourceId/items/:itemId", r.handler.GetResourceItem)
go
router.Get("/api/v1/resources/:resourceId/items/:itemId", r.handler.GetResourceItem)

Bulk operations

批量操作

go
router.Post("/api/v1/resources/bulk", r.handler.BulkCreateResources)
router.Delete("/api/v1/resources/bulk", r.handler.BulkDeleteResources)
go
router.Post("/api/v1/resources/bulk", r.handler.BulkCreateResources)
router.Delete("/api/v1/resources/bulk", r.handler.BulkDeleteResources)