Package dan Organisasi
Proyek Backend Go

Di Go, folder bukan sekadar tempat menaruh file, folder adalah batas package.

Di React kamu memecah kode ke component, hook, dan folder feature. Di Laravel kamu punya App\Models, App\Services, dan App\Http\Controllers. Di Go, unit pemecahan utamanya adalah package, dan satu folder selalu satu package.

Sejak modul fungsi dan error, lalu modul struct dan method, kita sudah diam-diam menulis baris seperti package product dan package order di atas setiap file, plus import seperti github.com/kamu/skincare-backend/internal/product. Modul ini akhirnya menjelaskan mesin di balik baris-baris itu: kenapa folder menentukan package, kenapa huruf besar membuka akses, dan kenapa import tertentu ditolak compiler.

Saat backend online shop skincare masih kecil, semua kode bisa saja hidup di satu main.go. Tetapi begitu ada katalog produk, checkout, order, payment, inventory, dan worker, satu file berubah menjadi lumpur. Package memberi batas yang jelas: kode mana milik domain produk, kode mana milik order, dan kode mana hanya menjadi entry point aplikasi.

Go sengaja membuat organisasi kode terasa eksplisit, dan aturannya cuma segelintir. Satu direktori adalah satu package. Import dilakukan lewat path package, bukan nama file. Nama yang boleh dipakai dari luar package ditentukan oleh huruf awal. Folder bernama internal punya arti khusus yang dipaksakan compiler. Sederhana, tetapi keempat aturan ini sangat membentuk cara kamu mendesain backend.

Acuan resmi yang kita pakai sepanjang modul: panduan resmi Organizing a Go module, Effective Go bagian Names dan Packages, Go Specification tentang exported identifiers, dan dokumentasi internal directories pada cmd/go.

Satu package istimewa yang menghasilkan binary, dipisahkan dari logic aplikasi.

Go membedakan package yang menghasilkan program executable dari package yang dipakai sebagai library internal. Pembedanya adalah nama package itu sendiri: main.

package main adalah package khusus. Kalau sebuah direktori berisi package main dan punya func main(), direktori itu bisa dikompilasi menjadi program yang bisa dijalankan. Untuk backend kita, cmd/api/main.go menjalankan HTTP API, sedangkan cmd/worker/main.go menjalankan background worker untuk email, sinkronisasi stok, atau retry payment webhook.

Package biasa, seperti product, order, payment, atau inventory, tidak punya func main(). Package ini berisi tipe, fungsi, interface, dan aturan domain yang dipakai oleh entry point. Inilah tempat tinggal Product, Order, MarkPaid, dan Reserve yang sudah kamu bangun di modul struct dan method.

Contoh paling kecil untuk API server, melanjutkan net/http yang sudah kamu kenal dari modul sebelumnya.

cmd/api/main.goSalin
package main

import (
	"fmt"
	"log"
	"net/http"
)

func main() {
	mux := http.NewServeMux()
	mux.HandleFunc("GET /health", func(w http.ResponseWriter, r *http.Request) {
		fmt.Fprintln(w, "ok")
	})

	log.Println("api listening on :8080")
	if err := http.ListenAndServe(":8080", mux); err != nil {
		log.Fatal(err)
	}
}

Kode di atas sengaja masih sederhana. Nanti saat masuk Roadmap 2, router chi, handler, dan dependency akan dipindah ke package internal supaya main.go tetap tipis.

flowchart LR
  SRC["cmd/api (package main)"] -->|"go build"| BIN["binary api"]
  BIN -->|"dijalankan"| RUN["func main berjalan"]
  RUN --> WIRE["baca config, susun dependency, daftar route"]
  WIRE --> SERVE["http.ListenAndServe"]

Gambar 1. Hanya package main dengan func main yang bisa dikompilasi menjadi binary. Tugas main adalah merangkai, bukan menyimpan aturan bisnis.

Kapital bukan gaya penulisan, kapital adalah aturan akses yang dicek compiler.

Di Go, huruf pertama sebuah nama menentukan apakah nama itu bisa dipakai dari package lain. Tidak ada keyword public, private, atau protected.

Nama yang diawali huruf besar adalah exported, bisa dipakai dari package lain. Nama yang diawali huruf kecil adalah unexported, hanya bisa dipakai dari package yang sama. Aturan ini berlaku seragam untuk function, type, const, var, method, dan field struct. Spesifikasi Go menyebutnya tepat: sebuah identifier exported jika karakter pertamanya huruf kapital Unicode dan ia dideklarasikan di package block, atau ia adalah nama field atau nama method.

Kamu sebenarnya sudah memanfaatkan aturan ini sejak modul struct. Saat kita menulis Product.PriceRupiah dengan huruf besar, itu bukan kebetulan estetika; itu keputusan agar package order dan httpapi bisa membacanya.

Contoh nyata di package product. Tipe dan field yang dibutuhkan package lain dibuat exported, sedangkan helper internal dibiarkan unexported.

internal/product/product.goSalin
package product

type ProductStatus string

const (
	ProductStatusDraft      ProductStatus = "draft"
	ProductStatusActive     ProductStatus = "active"
	ProductStatusArchived   ProductStatus = "archived"
	ProductStatusOutOfStock ProductStatus = "out_of_stock"
)

func (s ProductStatus) IsSellable() bool {
	return s == ProductStatusActive
}

type Product struct {
	ID          int64
	SKU         string
	Name        string
	Category    string
	PriceRupiah int64
	Quantity    int
	Status      ProductStatus
}

Helper seperti normalisasi SKU adalah detail internal package product. Karena tidak ada package lain yang perlu memanggilnya, ia dibuat unexported.

internal/product/sku.goSalin
package product

import "strings"

// normalizeSKU huruf kecil: hanya dipakai di dalam package product.
func normalizeSKU(input string) string {
	return strings.ToUpper(strings.TrimSpace(input))
}

Dari package lain, kamu bisa memakai product.Product, product.ProductStatusActive, dan method IsSellable. Tetapi normalizeSKU tidak akan terlihat sama sekali; menulis product.normalizeSKU(...) dari package order adalah compile error.

flowchart TD
  subgraph PKG["package product (satu folder)"]
    EXP["exported: Product, ProductStatus, IsSellable"]
    UNEXP["unexported: normalizeSKU"]
  end
  ORDER["package order"] -->|"product.Product OK"| EXP
  ORDER -. "product.normalizeSKU DITOLAK" .-> UNEXP

Gambar 2. Batas package adalah garis tegas. Nama exported menjadi API yang boleh diseberangi package lain, nama unexported tetap terkurung di dalam folder package-nya.

Kapan sebuah nama harus exported?

Ekspor nama hanya kalau package lain benar-benar membutuhkannya. Untuk package product, tipe Product wajar exported karena order perlu membaca produk di dalam cart item. Tetapi helper seperti normalizeSKU sebaiknya unexported karena itu detail internal yang bisa berubah kapan saja.

Nama exported adalah kontrak. Begitu banyak package lain bergantung padanya, mengubah nama atau signature menjadi mahal karena merembet ke seluruh pemakai. Karena itu, perlakukan huruf kapital sebagai janji, bukan default.

Import menunjuk ke package, bukan ke file, dan path-nya berasal dari go.mod.

Di Go, import menunjuk ke package path. Package path dibentuk dari module path di go.mod ditambah subdirektori package, bukan dari nama file.

go.mod proyek kita mendeklarasikan satu baris module path yang menjadi akar semua import internal. Inilah path yang sudah kita pakai diam-diam sejak modul fungsi.

go.modSalin
module github.com/kamu/skincare-backend

go 1.26

Karena module path-nya github.com/kamu/skincare-backend, package yang berada di direktori internal/product diimpor memakai path module ditambah subdirektori itu.

internal/checkout/cart.goSalin
package checkout

import "github.com/kamu/skincare-backend/internal/product"

type CartItem struct {
	Product product.Product
	Qty     int
}

func (item CartItem) LineTotal() int64 {
	return item.Product.PriceRupiah * int64(item.Qty)
}

Perhatikan bahwa import tidak menyebut product.go atau cart.go. Go mengompilasi semua file .go dalam satu direktori yang memakai nama package sama menjadi satu package. Kalau direktori internal/product berisi product.go, behavior.go, inventory.go, dan sku.go, keempatnya menjadi satu package product dan saling memakai nama tanpa import antar file.

Package name pendek, import path lengkap

Effective Go mendorong nama package yang pendek, huruf kecil, satu kata, tanpa underscore atau camelCase. Karena pemakai akan menulis product.Service atau order.NewOrder, nama di dalam package tidak perlu mengulang nama package.

internal/product/service.goSalin
package product

type Service struct {
	repo Repository
}

func NewService(repo Repository) *Service {
	return &Service{repo: repo}
}

Dari package lain, tipe itu dibaca sebagai product.Service. Karena itu, menulis ProductService di dalam package product justru menjadi repetitif saat dipakai: product.ProductService. Konvensi yang sama berlaku untuk fungsi; product.New sudah jelas membuat produk, jadi product.NewProduct sering terasa berlebihan kecuali package itu membuat beberapa jenis tipe.

Dua folder konvensi yang membentuk tulang punggung backend Go.

Untuk proyek server, panduan resmi Go menyarankan pola yang sama: cmd untuk program executable dan internal untuk logic aplikasi yang tidak ingin diekspor.

Folder cmd berisi entry point binary. Satu subfolder di dalam cmd adalah satu program. Dalam proyek skincare, kita punya minimal dua: cmd/api untuk HTTP request, dan cmd/worker untuk pekerjaan async. Keduanya berbagi package domain yang sama.

Folder internal lebih dari sekadar konvensi rapi; ia punya arti khusus yang dipaksakan compiler. Package di dalam internal hanya boleh diimpor oleh kode yang berakar di parent dari folder internal itu. Untuk module github.com/kamu/skincare-backend, ini berarti package di internal/product hanya bisa diimpor dari dalam module yang sama. Module lain di internet tidak akan pernah bisa import "github.com/kamu/skincare-backend/internal/product"; Go menolaknya saat compile.

Karena backend kita bukan library publik, hampir semua kode aplikasi pantas hidup di internal. Ini membebaskan kita merefactor tipe dan signature kapan saja tanpa khawatir menjadi kontrak publik bagi proyek orang lain. Hanya kalau sebuah package memang sengaja dirancang untuk dipakai proyek luar, ia keluar dari internal.

flowchart TD
  API["cmd/api main"] --> APP["susun dependency di main"]
  WORKER["cmd/worker main"] --> APP
  APP --> PRODUCT["internal/product"]
  APP --> ORDER["internal/order"]
  APP --> PAYMENT["internal/payment"]
  APP --> INVENTORY["internal/inventory"]
  PRODUCT --> PLATFORM["internal/platform"]
  ORDER --> PLATFORM
  PAYMENT --> PLATFORM
  INVENTORY --> PLATFORM
  EXTERNAL["module lain di internet"] -. "import internal DITOLAK compiler" .-> PRODUCT

Gambar 3. cmd menjalankan aplikasi, package di internal menyimpan logic, dan platform menjadi fondasi bersama. Garis putus dari module luar menunjukkan pagar internal yang dipaksakan compiler.

Memetakan domain yang sudah kita bangun ke package per fitur.

Package sebaiknya mengikuti bahasa domain, bukan jenis file teknis. Untuk online shop skincare, domainnya sudah jelas dari modul-modul sebelumnya: product, checkout, order, payment, dan inventory.

Folder per domain lebih mudah dibaca daripada folder generik models, controllers, dan services yang menumpuk semua domain di satu tempat. Saat kamu ingin mengubah aturan order, kamu cukup membuka internal/order, bukan menyusuri tiga folder teknis berbeda. Inilah Student Outcome modul ini: backend yang tertata jadi modul product, order, payment, dan inventory.

Perhatikan bahwa setiap entitas yang kita bangun di modul struct dan method kini punya rumah yang jelas. Inventory tinggal serumah dengan Product di internal/product karena keduanya bicara stok katalog yang sama. CartItem hidup di internal/checkout, lalu diimpor oleh internal/order saat menyusun order.

internal/order/order.goSalin
package order

import (
	"errors"
	"time"

	"github.com/kamu/skincare-backend/internal/checkout"
)

type OrderStatus string

const (
	OrderStatusPending   OrderStatus = "pending"
	OrderStatusPaid      OrderStatus = "paid"
	OrderStatusCancelled OrderStatus = "cancelled"
)

type Order struct {
	ID        int64
	UserID    int64
	Items     []checkout.CartItem
	Total     int64
	Status    OrderStatus
	PaymentID int64
	PaidAt    *time.Time
	CreatedAt time.Time
}

func (o *Order) MarkPaid(paymentID int64, paidAt time.Time) error {
	if o.Status != OrderStatusPending {
		return errors.New("order must be pending before it can be paid")
	}

	o.Status = OrderStatusPaid
	o.PaymentID = paymentID
	o.PaidAt = &paidAt
	return nil
}

Garis import antar package domain membentuk peta ketergantungan. Yang sehat adalah arah yang searah, dari yang dekat checkout menuju yang lebih fondasi, tanpa ada panah yang berbalik.

flowchart LR
  CHECKOUT["internal/checkout"] --> PRODUCT["internal/product"]
  ORDER["internal/order"] --> CHECKOUT
  ORDER --> USER["internal/user"]
  PAYMENT["internal/payment"] --> ORDER
  HTTPAPI["internal/httpapi"] --> ORDER
  HTTPAPI --> PRODUCT
  HTTPAPI --> PAYMENT

Gambar 4. Arah import yang sehat selalu searah. product adalah leaf package yang tidak bergantung pada siapa pun di domain, sedangkan httpapi di atas merakit semuanya. Tidak ada panah yang membentuk lingkaran.

Go menolak import yang berputar, dan justru itu menyelamatkan desainmu.

Circular dependency terjadi saat package A mengimpor B, lalu B mengimpor A, langsung maupun lewat rantai. Di Go, ini adalah compile error yang tegas.

Di Node.js, circular import kadang tetap berjalan walau hasilnya bisa aneh karena salah satu module belum selesai dievaluasi saat dipakai. Di Go, compiler menghentikannya sejak awal dengan pesan seperti import cycle not allowed. Terasa ketat, tetapi sangat membantu: ia memaksa setiap ketergantungan punya arah yang jelas.

Contoh yang sengaja salah. Bayangkan order perlu membuat payment, lalu payment perlu membaca order untuk mencatat order id.

internal/order/service.goSalin
package order

import "github.com/kamu/skincare-backend/internal/payment"

type Service struct {
	payments payment.Service
}

internal/payment/service.goSalin
package payment

import "github.com/kamu/skincare-backend/internal/order"

type Service struct{}

func (s Service) Charge(o order.Order) error {
	return nil
}

Dua package itu saling menarik: order butuh payment, dan payment butuh order. Compiler menolaknya.

TerminalSalin
import cycle not allowed
package github.com/kamu/skincare-backend/internal/order
	imports github.com/kamu/skincare-backend/internal/payment
	imports github.com/kamu/skincare-backend/internal/order

flowchart LR
  ORDER["internal/order"] -->|"butuh Service"| PAYMENT["internal/payment"]
  PAYMENT -->|"butuh Order"| ORDER

Gambar 5. Lingkaran import yang ditolak Go. Selama panah membentuk siklus seperti ini, kode tidak akan pernah compile, dan itu sinyal bahwa boundary package perlu dibenahi.

Ada tiga teknik baku untuk memutus siklus. Kita pakai teknik paling idiomatik: jadikan dependency searah dengan membuat package peminta mendefinisikan interface kecil atas kemampuan yang ia butuhkan. Konsep interface ini baru kamu dalami di Chapter 9, dan di sinilah ia membayar dirinya untuk organisasi package.

Versi yang sehat: order cukup tahu perilaku yang ia butuhkan, yaitu kemampuan men-charge sebuah order, lewat interface lokal. order tidak lagi mengimpor payment.

internal/order/payment.goSalin
package order

import "context"

// ChargeResult adalah tipe milik order, bukan import dari payment.
type ChargeResult struct {
	PaymentID   int64
	ReferenceNo string
}

// PaymentCharger adalah interface kecil yang DIBUTUHKAN order.
// Implementasinya datang dari package payment, tetapi order tidak mengimpornya.
type PaymentCharger interface {
	Charge(ctx context.Context, orderID, amountRupiah int64) (ChargeResult, error)
}

type Service struct {
	charger PaymentCharger
}

func NewService(charger PaymentCharger) *Service {
	return &Service{charger: charger}
}

Package payment lalu mengimpor order untuk mengisi kontrak itu, tetapi panahnya hanya satu arah: payment → order. Tidak ada balik.

internal/payment/gateway.goSalin
package payment

import (
	"context"

	"github.com/kamu/skincare-backend/internal/order"
)

type Gateway struct {
	provider string
}

func NewGateway(provider string) *Gateway {
	return &Gateway{provider: provider}
}

// Gateway memenuhi order.PaymentCharger tanpa membuat order mengimpor payment.
func (g *Gateway) Charge(ctx context.Context, orderID, amountRupiah int64) (order.ChargeResult, error) {
	return order.ChargeResult{
		PaymentID:   orderID, // disederhanakan untuk contoh
		ReferenceNo: g.provider + "-REF-001",
	}, nil
}

Yang menyatukan keduanya adalah composition root di cmd/api/main.go. Di sinilah implementasi konkret dipasang ke interface, persis seperti dependency injection manual.

cmd/api/main.goSalin
package main

import (
	"github.com/kamu/skincare-backend/internal/order"
	"github.com/kamu/skincare-backend/internal/payment"
)

func main() {
	gateway := payment.NewGateway("midtrans")
	orderService := order.NewService(gateway) // gateway memenuhi order.PaymentCharger
	_ = orderService
}

flowchart TD
  MAIN["cmd/api main"] --> ORDER["internal/order"]
  MAIN --> PAYMENT["internal/payment"]
  PAYMENT -->|"import untuk pakai tipe"| ORDER
  PAYMENT -. "memenuhi" .-> CONTRACT["order.PaymentCharger"]
  ORDER -->|"mendefinisikan"| CONTRACT

Gambar 6. Siklus terputus karena order hanya mendefinisikan interface yang ia butuhkan. payment memenuhinya, dan cmd/api menyambungkan keduanya. Semua panah import sekarang searah.

Dari satu main.go menjadi struktur yang siap tumbuh, plus rasakan pagar internal.

Latihan ini memindahkan model dan fungsi pembuat product keluar dari main.go ke package product, lalu memakainya dari cmd/api. Tidak butuh database.

TerminalSalin
mkdir -p cmd/api internal/product
go mod init github.com/kamu/skincare-backend

Fungsi pembuat meneruskan gaya (Data, error) dari modul fungsi dan error. ErrInvalidPrice exported agar pemanggil bisa memeriksanya dengan errors.Is.

internal/product/product.goSalin
package product

import "errors"

var ErrInvalidPrice = errors.New("product price must be greater than zero")

type Product struct {
	ID          int64
	SKU         string
	Name        string
	PriceRupiah int64
}

// New exported: package main memanggilnya untuk membuat product yang valid.
func New(id int64, sku, name string, priceRupiah int64) (Product, error) {
	if priceRupiah <= 0 {
		return Product{}, ErrInvalidPrice
	}

	return Product{
		ID:          id,
		SKU:         normalizeSKU(sku),
		Name:        name,
		PriceRupiah: priceRupiah,
	}, nil
}

// normalizeSKU unexported: detail internal package product.
func normalizeSKU(input string) string {
	return input
}

cmd/api/main.goSalin
package main

import (
	"fmt"
	"log"

	"github.com/kamu/skincare-backend/internal/product"
)

func main() {
	serum, err := product.New(1, "SKN-SERUM-NIA-30", "Niacinamide Serum 30ml", 129000)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Printf("%s: Rp%d\n", serum.Name, serum.PriceRupiah)
}

TerminalSalin
go run ./cmd/api

Output yang diharapkan:

TerminalSalin
Niacinamide Serum 30ml: Rp129000

Sekarang buktikan dua aturan modul ini dengan tangan sendiri.

Untuk meyakinkan dirimu bahwa pemecahan ini tidak mengubah perilaku, tambahkan test kecil di dalam package product. Test berada di package yang sama sehingga bisa memeriksa hasil fungsi exported tanpa import path.

internal/product/product_test.goSalin
package product

import (
	"errors"
	"testing"
)

func TestNewRejectsInvalidPrice(t *testing.T) {
	_, err := New(1, "SKN-001", "Test", 0)
	if !errors.Is(err, ErrInvalidPrice) {
		t.Fatalf("expected ErrInvalidPrice, got %v", err)
	}
}

func TestNewBuildsValidProduct(t *testing.T) {
	p, err := New(1, "SKN-SERUM-NIA-30", "Niacinamide Serum 30ml", 129000)
	if err != nil {
		t.Fatalf("unexpected error: %v", err)
	}

	if p.PriceRupiah != 129000 {
		t.Fatalf("price mismatch: got %d want 129000", p.PriceRupiah)
	}
}

TerminalSalin
go test ./...

Sebagian masalah organisasi Go lahir dari membawa kebiasaan Node.js dan Laravel mentah-mentah.

Aturan package Go sedikit, tetapi beberapa di antaranya berlawanan dengan refleks developer JavaScript dan PHP.

Checklist organisasi awal

• Apakah cmd/api/main.go hanya merangkai aplikasi, bukan menyimpan aturan bisnis?
• Apakah package domain bernama pendek dan tunggal, seperti product, order, payment, dan inventory?
• Apakah nama exported hanya yang benar-benar dipakai package lain?
• Apakah import memakai module path lengkap dari go.mod, bukan path relatif?
• Apakah arah import searah, tanpa ada dua package yang saling mengimpor?
• Apakah logic aplikasi tinggal di internal agar bebas direfactor?

Package adalah cara Go membuat batas desain yang sederhana, tegas, dan bisa diperiksa compiler, dari nama sampai folder.

Pemetaan ke proyek online shop skincare