Struktur Proyek Go Skala Besar: Panduan Praktik Terbaik

Waduh, project Go kamu udah mulai membengkak kayak adonan kue lebaran? Mau nambah fitur dikit aja rasanya udah kayak gali kuburan? Nah, pas banget nih! Kali ini, kita bakal bedah tuntas gimana sih caranya bangun struktur proyek Go skala besar yang rapi jali, biar vibes codingnya tetap mantul dan nggak bikin pusing tujuh keliling! Gaspol, gaes!

Kenapa Struktur Proyek Itu Penting Banget, Ngab?

Coba bayangin, kalo kamu punya koleksi sepatu branded tapi nyimpennya acak-acakan di mana-mana. Mau nyari sepasang aja udah kayak treasure hunt. Sama kayak kode, ngab! Struktur proyek yang solid itu kunci utama buat:

• Maintenance Gampang: Nambah fitur baru, benerin bug, atau refactor code jadi lebih cepet dan nggak bikin kepala cenat-cenut.
• Skalabilitas Mantul: Project kamu siap buat di-scale up tanpa harus bongkar ulang semua.
• Kolaborasi Asik: Tim bisa kerja bareng tanpa tabrakan atau bingung nyari file. Developer baru pun bisa cepat adaptasi.
• Code Readability Tinggi: Kode jadi lebih bersih, mudah dibaca, dan intents-nya jelas.

Intinya, struktur yang bagus itu investasi jangka panjang biar project kamu nggak jadi "neraka" di masa depan.

Melampaui "Standard Go Project Layout"

Mungkin kalian udah sering denger "Standard Go Project Layout" yang ada di GitHub itu kan? Itu mantul banget buat project-project yang ukurannya masih medium atau startup yang lagi ngebut MVP. Tapi, jujur aja nih, buat project skala sultan yang udah gede banget, kita butuh "sedikit" modifikasi biar lebih fleksibel dan sesuai sama kebutuhan arsitektur yang kompleks, misalnya Clean Architecture, DDD, atau Layered Architecture.

Fokus kita adalah pada modularitas dan Separation of Concerns (SoC). Setiap bagian punya tugasnya sendiri dan nggak saling nyampur.

Trio Maut yang Wajib Ada

Apapun modifikasinya, tiga folder ini hampir selalu jadi fondasi:

• cmd/: Ini tempat semua aplikasi executable kamu, gaes. Tiap subfolder di sini adalah aplikasi yang bisa di-build. Misalnya, cmd/api untuk server API, cmd/worker untuk background worker, cmd/cli untuk command-line tool. Tiap main.go ada di sini.
• internal/: Ini adalah surga buat kode-kode private yang cuma boleh diakses di dalam project kamu sendiri. Modul di luar project nggak bisa import folder ini. Ideal banget buat logic bisnis inti (core business logic), service, repository, atau konfigurasi spesifik aplikasi. Pokoknya, yang nggak mau kamu ekspos ke dunia luar, taruh sini!
• pkg/: Nah, kalo ini kebalikannya internal. Ini buat kode-kode public yang bisa di-import dan dipakai ulang oleh project lain (misal, library utility umum, shared DTOs, atau komponen reusable yang spesifik Go). Kalo kamu berencana bikin reusable library yang bisa dipakai lintas project, ini tempatnya. Tapi hati-hati, jangan semua ditaruh di sini biar nggak jadi tempat sampah.

Struktur Tambahan Buat Project Sultan

Selain trio maut di atas, ini beberapa folder lain yang sering nongol di project Go skala besar, apalagi kalo pake arsitektur berlapis:

.
├── cmd/
│   ├── api/             # Aplikasi server HTTP utama (misal: REST API, gRPC)
│   │   └── main.go
│   ├── worker/          # Background worker atau consumer pesan
│   │   └── main.go
│   └── cli/             # Command-line tool
│       └── main.go
├── internal/
│   ├── app/             # Konfigurasi & bootstrapping aplikasi inti
│   │   ├── server/      # Konfigurasi server HTTP/gRPC
│   │   │   └── server.go
│   │   └── worker/      # Konfigurasi worker
│   │       └── worker.go
│   ├── core/            # Logic bisnis inti (Domain Layer)
│   │   ├── domain/      # Entitas, aggregate roots, value objects (definisi murni, tanpa implementasi db)
│   │   │   └── user.go
│   │   ├── ports/       # Interface untuk service, repository, handler (contract)
│   │   │   ├── user_service.go
│   │   │   └── user_repository.go
│   │   └── services/    # Implementasi logic bisnis yang menggunakan domain & repository (Application Layer)
│   │       └── user_service.go
│   ├── infrastructure/  # Implementasi infrastruktur (Persistence Layer, External Services)
│   │   ├── database/    # Implementasi repository ke database (misal: PostgreSQL, MongoDB)
│   │   │   └── postgres/
│   │   │       └── user_repository.go
│   │   ├── cache/       # Implementasi cache (misal: Redis)
│   │   └── httpclient/  # Klien untuk eksternal API
│   ├── handler/         # Adaptor untuk API (Delivery/Presentation Layer)
│   │   ├── http/        # HTTP Handlers
│   │   │   └── user_handler.go
│   │   └── grpc/        # gRPC Handlers
│   │       └── user_grpc_handler.go
│   ├── config/          # Konfigurasi aplikasi yang spesifik internal (e.g., database URLs)
│   │   └── config.go
│   └── util/            # Utility function internal yang spesifik aplikasi
│       └── validator.go
├── pkg/                 # Kode public yang bisa di-import oleh project lain
│   ├── common/          # Struktur data/utility umum (misal: Response DTO)
│   │   └── response.go
│   └── errors/          # Custom error types
│       └── errors.go
├── api/                 # Definisi API (proto files untuk gRPC, OpenAPI specs untuk REST)
│   ├── protobuf/
│   │   └── user.proto
│   └── openapi/
│       └── swagger.yaml
├── web/                 # Static assets, template HTML
│   ├── static/
│   └── templates/
├── scripts/             # Skrip automasi (build, deploy, migrate)
├── migrations/          # Skrip migrasi database
│   └── 001_create_users_table.up.sql
├── deploy/              # File konfigurasi deployment (Dockerfiles, Kubernetes YAMLs)
├── vendor/              # Dependencies Go Modules (jika di-vendorkan)
├── .env                 # Environment variables
├── go.mod
├── go.sum
└── README.md

Penjelasan Singkat Setiap Bagian:

• internal/app: Di sini kita setup aplikasi. server.go akan jadi entry point HTTP/gRPC server kamu, yang nge-register route dan nge-start listen. Ini semacam orchestrator-nya.
• internal/core/domain: Tempat kamu define struktur data inti (models) dan behavior bisnis murni. Nggak ada embel-embel database atau HTTP di sini. Murni domain logic.
• internal/core/ports: Interface! Ini penting banget buat decoupling. UserService dan UserRepository di sini cuma interface, yang akan diimplementasikan di layer lain. Ini bikin kode kamu testable dan fleksibel.
• internal/core/services: Implementasi dari interface ports.UserService. Di sinilah bisnis logic utama kamu hidup. Dia akan menggunakan ports.UserRepository untuk berinteraksi dengan data.
• internal/infrastructure: Ini layer paling bawah yang berinteraksi dengan "dunia luar": database, cache, eksternal API, dll. Implementasi dari ports.UserRepository akan ada di sini (misalnya internal/infrastructure/database/postgres/user_repository.go).
• internal/handler: Ini layer yang menerima request dari user (HTTP, gRPC, dll) dan memanggil services di layer core. Dia bertanggung jawab untuk parsing request, validasi input, dan formatting response.

Contoh Kode Singkat: Flow Request-Response

Bayangkan kita ingin membuat API untuk mendapatkan data user.

1. internal/core/domain/user.go (Definisi entitas domain)

package domain

import "time"

// User merepresentasikan entitas pengguna dalam sistem
type User struct {
	ID        string    `json:"id"`
	Username  string    `json:"username"`
	Email     string    `json:"email"`
	CreatedAt time.Time `json:"created_at"`
	UpdatedAt time.Time `json:"updated_at"`
}

2. internal/core/ports/user_service.go & user_repository.go (Interface sebagai kontrak)

package ports

import (
	"context"
	"your_project_name/internal/core/domain"
)

// UserService mendefinisikan operasi bisnis terkait user
type UserService interface {
	GetUserByID(ctx context.Context, id string) (*domain.User, error)
	// ... operasi lain seperti CreateUser, UpdateUser
}

// UserRepository mendefinisikan operasi penyimpanan data user
type UserRepository interface {
	FindByID(ctx context.Context, id string) (*domain.User, error)
	// ... operasi lain seperti Save, Update, Delete
}

3. internal/core/services/user_service.go (Implementasi bisnis logic)

package services

import (
	"context"
	"errors"
	"your_project_name/internal/core/domain"
	"your_project_name/internal/core/ports"
)

type userService struct {
	userRepo ports.UserRepository
}

// NewUserService membuat instance baru dari UserService
func NewUserService(repo ports.UserRepository) ports.UserService {
	return &userService{userRepo: repo}
}

func (s *userService) GetUserByID(ctx context.Context, id string) (*domain.User, error) {
	if id == "" {
		return nil, errors.New("user ID cannot be empty")
	}
	user, err := s.userRepo.FindByID(ctx, id)
	if err != nil {
		return nil, err // Handle specific errors from repo if needed
	}
	// Di sini bisa ada bisnis logic tambahan sebelum mengembalikan user
	return user, nil
}

4. internal/infrastructure/database/postgres/user_repository.go (Implementasi interaksi database)

package postgres

import (
	"context"
	"database/sql"
	"your_project_name_name/internal/core/domain"
	"your_project_name_name/internal/core/ports"
)

type userRepository struct {
	db *sql.DB // Atau ORM lainnya seperti GORM/sqlx
}

// NewUserRepository membuat instance baru dari UserRepository
func NewUserRepository(db *sql.DB) ports.UserRepository {
	return &userRepository{db: db}
}

func (r *userRepository) FindByID(ctx context.Context, id string) (*domain.User, error) {
	var user domain.User
	query := `SELECT id, username, email, created_at, updated_at FROM users WHERE id = $1`
	err := r.db.QueryRowContext(ctx, query, id).Scan(
		&user.ID, &user.Username, &user.Email, &user.CreatedAt, &user.UpdatedAt,
	)
	if err != nil {
		if errors.Is(err, sql.ErrNoRows) {
			return nil, nil // Atau custom error "NotFound"
		}
		return nil, err
	}
	return &user, nil
}

5. internal/handler/http/user_handler.go (HTTP endpoint)

package http

import (
	"net/http"
	"your_project_name/internal/core/ports"

	"github.com/gorilla/mux" // Contoh router
)

type userHandler struct {
	userService ports.UserService
}

// NewUserHandler membuat instance baru dari UserHandler
func NewUserHandler(service ports.UserService) *userHandler {
	return &userHandler{userService: service}
}

func (h *userHandler) GetUserByID(w http.ResponseWriter, r *http.Request) {
	vars := mux.Vars(r)
	userID := vars["id"]

	user, err := h.userService.GetUserByID(r.Context(), userID)
	if err != nil {
		// handle error, kirim response error
		http.Error(w, err.Error(), http.StatusInternalServerError)
		return
	}
	if user == nil {
		http.Error(w, "User not found", http.StatusNotFound)
		return
	}

	// Kirim response sukses (misal: JSON)
	w.Header().Set("Content-Type", "application/json")
	w.WriteHeader(http.StatusOK)
	// Marshal user ke JSON dan tulis ke w
}

// RegisterRoutes meregistrasikan rute untuk UserHandler
func (h *userHandler) RegisterRoutes(router *mux.Router) {
	router.HandleFunc("/users/{id}", h.GetUserByID).Methods("GET")
}

6. internal/app/server/server.go (Orchestrator server HTTP)

package server

import (
	"database/sql"
	"fmt"
	"log"
	"net/http"
	"your_project_name/internal/core/services"
	"your_project_name/internal/infrastructure/database/postgres"
	userHandler "your_project_name/internal/handler/http" // Alias untuk menghindari konflik nama
	"github.com/gorilla/mux"
)

// RunHTTP serves the HTTP API
func RunHTTP(db *sql.DB, port int) {
	// Initialize repositories
	userRepo := postgres.NewUserRepository(db)

	// Initialize services
	userService := services.NewUserService(userRepo)

	// Initialize handlers
	handler := userHandler.NewUserHandler(userService)

	// Setup router
	router := mux.NewRouter()
	handler.RegisterRoutes(router) // Register user routes

	// Start server
	addr := fmt.Sprintf(":%d", port)
	log.Printf("Server starting on %s", addr)
	log.Fatal(http.ListenAndServe(addr, router))
}

7. cmd/api/main.go (Entry point aplikasi API)

package main

import (
	"database/sql"
	"log"
	"os"
	"strconv"
	"your_project_name/internal/app/server"
	"github.com/joho/godotenv" // Untuk load .env
	_ "github.com/lib/pq"     // Driver PostgreSQL
)

func main() {
	// Load environment variables
	err := godotenv.Load()
	if err != nil {
		log.Println("Error loading .env file, assuming env vars are set")
	}

	// Get config
	dbConnStr := os.Getenv("DATABASE_URL")
	apiPortStr := os.Getenv("API_PORT")
	if dbConnStr == "" || apiPortStr == "" {
		log.Fatal("DATABASE_URL and API_PORT must be set")
	}

	apiPort, err := strconv.Atoi(apiPortStr)
	if err != nil {
		log.Fatalf("Invalid API_PORT: %v", err)
	}

	// Connect to database
	db, err := sql.Open("postgres", dbConnStr)
	if err != nil {
		log.Fatalf("Failed to connect to database: %v", err)
	}
	defer db.Close()

	if err = db.Ping(); err != nil {
		log.Fatalf("Failed to ping database: %v", err)
	}
	log.Println("Successfully connected to database!")

	// Run the HTTP server
	server.RunHTTP(db, apiPort)
}

Dengan struktur ini, setiap layer punya tanggung jawabnya sendiri. Kalo mau ganti database dari PostgreSQL ke MySQL, kamu cuma perlu ngubah implementasi di internal/infrastructure/database, tanpa menyentuh layer service atau handler! Mantap kan?

Tips Praktis Biar Project Makin Glowing!

1. Konsistensi Itu Kunci: Pilih satu gaya penamaan, satu cara handle error, satu format kode, lalu patuhi! Go punya go fmt dan go vet, pakai itu! Tambah linter kayak golangci-lint biar makin rapi.
2. Mulai Simpel, Refactor Nanti: Jangan over-engineering dari awal. Mulai dengan struktur yang cukup, dan refactor (struktur, bukan cuma kode) ketika kompleksitasnya mulai terasa.
3. Tulis README.md yang Jelas: Ini penting banget buat onboarding developer baru. Jelaskan cara setup, run, test, dan deploy project.
4. Tes, Tes, Tes!: Dengan struktur modular, nulis unit test jadi lebih gampang. Test coverage tinggi bikin tidur nyenyak.
5. Dokumentasi API: Kalo project kamu punya API, pake Swagger/OpenAPI atau gRPC Protobuf. Biar developer lain atau frontend nggak bingung.
6. Automasi CI/CD: Setup pipeline CI/CD biar setiap push ke main (atau master) langsung di-build, di-test, dan dideploy otomatis. Bikin proses release makin sat-set!
7. Code Review itu Wajib: Biar semua orang di tim punya pemahaman yang sama dan bisa saling belajar. Temuin bug atau potensi masalah lebih awal.

Kesimpulan: Gaspol Bikin Go Project yang Cetar Membahana!

Membangun proyek Go skala besar itu bukan cuma soal coding cepet-cepetan, tapi juga soal fondasi yang kokoh, gaes. Dengan struktur yang terencana dan praktik terbaik, project kamu nggak cuma bisa survive, tapi juga bakal berkembang pesat kayak roket Elon Musk!

Ingat, setiap project itu unik, jadi adaptasi struktur ini sesuai kebutuhan tim dan arsitektur yang kalian pilih. Yang penting, tetap jaga kebersihan dan kerapian kode biar vibes ngodingnya tetap asik dan produktif. Skuy, tunjukkan kalo Go bukan cuma cepet di runtime, tapi juga cepet di maintainabilitas! Semoga bermanfaat ya, ngab!