backend-golang

Backend Development Guidelines (Golang)

Code Organization

Package Structure

Follow the backend/internal/ package layout:

• models/ - Data structures and DTOs
• handlers/ - HTTP request handlers
• middleware/ - HTTP middleware functions
• database/ - Database connection and utilities
• api/ - Route definitions and setup
• utils/ - Shared utility functions

Handler Pattern

All handlers follow the pattern in handlers/orders.go:

type OrderHandler struct {
    db *sql.DB
}

func NewOrderHandler(db *sql.DB) *OrderHandler {
    return &OrderHandler{db: db}
}

func (h *OrderHandler) GetOrders(c *gin.Context) {
    // Implementation
}

Database Operations

Raw SQL Usage

• Use parameterized queries to prevent SQL injection
• Follow the patterns in handlers/orders.go for database operations
• Always handle sql.ErrNoRows explicitly
• Use transactions for multi-table operations

Example Query Pattern:

func (h *Handler) getRecord(id uuid.UUID) (*Model, error) {
    var record Model
    query := `SELECT id, field1, field2 FROM table WHERE id = $1`
    
    err := h.db.QueryRow(query, id).Scan(&record.ID, &record.Field1, &record.Field2)
    if err == sql.ErrNoRows {
        return nil, fmt.Errorf("record not found")
    }
    if err != nil {
        return nil, fmt.Errorf("database error: %w", err)
    }
    
    return &record, nil
}

Authentication & Security

JWT Middleware

Use the authentication middleware from middleware/auth.go:

• Protected routes must use authMiddleware
• Role-based access with RequireRoles([]string{"admin", "manager"})
• Extract user info with GetUserFromContext(c)

Error Handling

Follow the API response pattern from models/models.go:

c.JSON(http.StatusBadRequest, models.APIResponse{
    Success: false,
    Message: "User-friendly error message",
    Error:   stringPtr("error_code"),
})