Go io/fs dan Embed

Definisi

io/fs adalah abstraction atas sistem berkas di Go: menyediakan interface fs.FS yang dipakai untuk membaca file secara uniform, baik dari disk, memory, maupun embed. embed memungkinkan menyematkan file (template, aset statis, SQL) langsung ke dalam binary pada saat compile.

Kapan dipakai

• embed: butuh aset ikut binary tanpa mengandalkan file external (CLI tool, web server tanpa folder static/, template HTML).
• fs.FS: ingin membaca banyak sumber secara seragam, atau menulis test dengan fstest.MapFS tanpa menyentuh disk.
• Jangan embed file yang harus bisa diubah saat runtime (konfigurasi dinamis) — embed bersifat read-only sejak compile.

Cara kerja

embed.FS

go

import "embed"
 
//go:embed templates/*.html
var templatesFS embed.FS
 
func render(name string) (string, error) {
    b, err := templatesFS.ReadFile("templates/index.html")
    if err != nil {
        return "", err
    }
    return string(b), nil
}

• Direktif //go:embed harus tepat di atas variabel bertipe embed.FS (atau []byte/string untuk satu file).
• Path relatif terhadap file Go yang memuat direktif.

fs.FS sebagai abstraction

go

func loadConfig(fsys fs.FS, name string) ([]byte, error) {
    return fs.ReadFile(fsys, name)
}

Fungsi di atas bisa menerima os.DirFS("configs"), embed.FS, atau fstest.MapFS di test.

Struktur alur

Contoh test tanpa disk

go

func TestLoadConfig(t *testing.T) {
    fsys := fstest.MapFS{
        "app.yaml": &fstest.MapFile{Data: []byte("debug: true")},
    }
    data, err := loadConfig(fsys, "app.yaml")
    if err != nil {
        t.Fatal(err)
    }
    if !bytes.Contains(data, []byte("debug")) {
        t.Fatal("konten salah")
    }
}

Catatan implementasi

• embed.FS tidak bisa di-write; untuk aset yang berubah runtime, simpan di disk/volume eksternal.
• Gunakan fs.WalkDir untuk iterasi isi fs.FS secara rekursif.
• os.DirFS membatasi akses ke dalam direktori tersebut (aman untuk batasi path traversal).

Kesalahan umum

• Path salah: lupa bahwa path di ReadFile harus sama persis dengan pola embed (termasuk prefix folder).
• Edit file embed tapi binary tidak di-rebuild: perubahan file sumber tidak otomatis masuk binary lama.
• Embed file terlalu besar: membesarkan ukuran binary tanpa perlu.
• Mencampur baca/write: embed.FS read-only; jangan asumsikan bisa WriteFile.

Referensi terkait

• Go JSON Encoding/Decoding, Validation, Time Handling
• Go CLI Commands, Flags, Argument Parsing
• Go Modules, Packages, Workspaces