Tujuan Pembelajaran
Setelah menyelesaikan proyek ini, Anda mampu:
- menyusun CLI menjadi domain, penyimpanan, dan entry point;
- memvalidasi input serta mempertahankan invariant data;
- menyimpan JSON dengan penggantian file atomik;
- menghasilkan pesan error dan exit code yang berguna;
- menguji perilaku penting dengan table-driven tests;
- memverifikasi format, analisis statis, coverage, dan data race.
1. Spesifikasi
Aplikasi bernama task mendukung perintah:
Code
task add <judul>
task list
task done <id>
task delete <id>
Data disimpan dalam JSON. Flag global -file dapat menentukan lokasi file; jika tidak diberikan, aplikasi menggunakan direktori konfigurasi pengguna.
Aturan domain:
- judul dipangkas dan tidak boleh kosong;
- judul maksimum 200 byte pada versi ini;
- ID berupa bilangan bulat positif, unik, dan tidak dipakai ulang;
done dan delete gagal jika ID tidak ditemukan;- kegagalan membaca atau decode tidak boleh ditafsirkan sebagai data kosong;
- perubahan baru dianggap berhasil setelah penyimpanan berhasil.
2. Arsitektur
Memuat diagram…
main menangani argumen, output, dan exit code. Package task memiliki aturan aplikasi. JSONStore menangani file. Interface didefinisikan di sisi pemakai agar kontraknya kecil.
3. Struktur File
Code
taskcli/
├── go.mod
├── cmd/
│ └── task/
│ └── main.go
└── internal/
└── task/
├── task.go
├── app.go
├── app_test.go
├── jsonstore.go
└── jsonstore_test.go
Buat module:
Code
mkdir taskcli
cd taskcli
go mod init example.com/taskcli
mkdir -p cmd/task internal/task
4. Model Domain
Code
package task
import "errors"
const MaxTitleBytes = 200
var (
ErrEmptyTitle = errors.New("judul tidak boleh kosong")
ErrLongTitle = errors.New("judul terlalu panjang")
ErrNotFound = errors.New("tugas tidak ditemukan")
)
type Task struct {
ID int `json:"id"`
Title string `json:"title"`
Done bool `json:"done"`
}
Sentinel error memungkinkan pemanggil menggunakan errors.Is. Batas byte sederhana dan deterministik. Jika kebutuhan berubah menjadi batas karakter pengguna, gunakan perhitungan rune dan tetapkan aturan Unicode dengan jelas.
5. Logika Aplikasi
Code
package task
import (
"fmt"
"strings"
)
type Store interface {
Load() ([]Task, error)
Save([]Task) error
}
type App struct {
store Store
}
func NewApp(store Store) App {
return App{store: store}
}
func (a App) Add(title string) (Task, error) {
title = strings.TrimSpace(title)
if title == "" {
return Task{}, ErrEmptyTitle
}
if len(title) > MaxTitleBytes {
return Task{}, ErrLongTitle
}
tasks, err := a.store.Load()
if err != nil {
return Task{}, fmt.Errorf("muat tugas: %w", err)
}
maxID := 0
for _, t := range tasks {
if t.ID > maxID {
maxID = t.ID
}
}
created := Task{ID: maxID + 1, Title: title}
tasks = append(tasks, created)
if err := a.store.Save(tasks); err != nil {
return Task{}, fmt.Errorf("simpan tugas: %w", err)
}
return created, nil
}
func (a App) List() ([]Task, error) {
tasks, err := a.store.Load()
if err != nil {
return nil, fmt.Errorf("muat tugas: %w", err)
}
return tasks, nil
}
func (a App) Done(id int) error {
if id < 1 {
return ErrNotFound
}
tasks, err := a.store.Load()
if err != nil {
return fmt.Errorf("muat tugas: %w", err)
}
for i := range tasks {
if tasks[i].ID == id {
tasks[i].Done = true
if err := a.store.Save(tasks); err != nil {
return fmt.Errorf("simpan tugas: %w", err)
}
return nil
}
}
return ErrNotFound
}
func (a App) Delete(id int) error {
if id < 1 {
return ErrNotFound
}
tasks, err := a.store.Load()
if err != nil {
return fmt.Errorf("muat tugas: %w", err)
}
for i := range tasks {
if tasks[i].ID == id {
tasks = append(tasks[:i], tasks[i+1:]...)
if err := a.store.Save(tasks); err != nil {
return fmt.Errorf("simpan tugas: %w", err)
}
return nil
}
}
return ErrNotFound
}
Aplikasi melakukan load-modify-save. Desain ini cukup untuk satu proses dan data kecil. Dua proses yang menulis bersamaan dapat mengalami lost update; tambahkan file locking atau database ketika multiwriter menjadi kebutuhan nyata.
6. JSON Store dengan Penulisan Atomik
Code
package task
import (
"encoding/json"
"errors"
"fmt"
"os"
"path/filepath"
)
type JSONStore struct {
Path string
}
func (s JSONStore) Load() ([]Task, error) {
data, err := os.ReadFile(s.Path)
if errors.Is(err, os.ErrNotExist) {
return []Task{}, nil
}
if err != nil {
return nil, fmt.Errorf("baca %q: %w", s.Path, err)
}
if len(data) == 0 {
return []Task{}, nil
}
var tasks []Task
if err := json.Unmarshal(data, &tasks); err != nil {
return nil, fmt.Errorf("decode %q: %w", s.Path, err)
}
if tasks == nil {
tasks = []Task{}
}
return tasks, nil
}
func (s JSONStore) Save(tasks []Task) error {
data, err := json.MarshalIndent(tasks, "", " ")
if err != nil {
return fmt.Errorf("encode tugas: %w", err)
}
data = append(data, '\n')
dir := filepath.Dir(s.Path)
if err := os.MkdirAll(dir, 0o700); err != nil {
return fmt.Errorf("buat direktori %q: %w", dir, err)
}
tmp, err := os.CreateTemp(dir, ".tasks-*.tmp")
if err != nil {
return fmt.Errorf("buat file sementara: %w", err)
}
name := tmp.Name()
defer func() {
tmp.Close()
os.Remove(name)
}()
if err := tmp.Chmod(0o600); err != nil {
return fmt.Errorf("atur permission file sementara: %w", err)
}
if _, err := tmp.Write(data); err != nil {
return fmt.Errorf("tulis file sementara: %w", err)
}
if err := tmp.Sync(); err != nil {
return fmt.Errorf("sync file sementara: %w", err)
}
if err := tmp.Close(); err != nil {
return fmt.Errorf("tutup file sementara: %w", err)
}
if err := os.Rename(name, s.Path); err != nil {
return fmt.Errorf("ganti file data: %w", err)
}
return nil
}
File sementara berada pada direktori yang sama agar Rename tidak melintasi filesystem. Deferred cleanup menghapus temp file pada jalur error.
7. Entry Point dan Parsing CLI
Code
package main
import (
"errors"
"flag"
"fmt"
"io"
"os"
"path/filepath"
"strconv"
"strings"
"example.com/taskcli/internal/task"
)
func defaultPath() (string, error) {
dir, err := os.UserConfigDir()
if err != nil {
return "", fmt.Errorf("tentukan direktori konfigurasi: %w", err)
}
return filepath.Join(dir, "taskcli", "tasks.json"), nil
}
func usage(w io.Writer) {
fmt.Fprintln(w, "penggunaan:")
fmt.Fprintln(w, " task [-file path] add <judul>")
fmt.Fprintln(w, " task [-file path] list")
fmt.Fprintln(w, " task [-file path] done <id>")
fmt.Fprintln(w, " task [-file path] delete <id>")
}
func parseID(value string) (int, error) {
id, err := strconv.Atoi(value)
if err != nil || id < 1 {
return 0, errors.New("ID harus berupa bilangan bulat positif")
}
return id, nil
}
func run(args []string, stdout, stderr io.Writer) error {
path, err := defaultPath()
if err != nil {
return err
}
flags := flag.NewFlagSet("task", flag.ContinueOnError)
flags.SetOutput(stderr)
file := flags.String("file", path, "lokasi file data JSON")
if err := flags.Parse(args); err != nil {
return err
}
args = flags.Args()
if len(args) == 0 {
usage(stderr)
return errors.New("perintah wajib diberikan")
}
app := task.NewApp(task.JSONStore{Path: *file})
switch args[0] {
case "add":
if len(args) < 2 {
return errors.New("judul wajib diberikan")
}
created, err := app.Add(strings.Join(args[1:], " "))
if err != nil {
return err
}
fmt.Fprintf(stdout, "tugas %d ditambahkan\n", created.ID)
return nil
case "list":
if len(args) != 1 {
return errors.New("list tidak menerima argumen")
}
tasks, err := app.List()
if err != nil {
return err
}
for _, t := range tasks {
mark := " "
if t.Done {
mark = "x"
}
fmt.Fprintf(stdout, "[%s] %d %s\n", mark, t.ID, t.Title)
}
return nil
case "done", "delete":
if len(args) != 2 {
return fmt.Errorf("%s memerlukan tepat satu ID", args[0])
}
id, err := parseID(args[1])
if err != nil {
return err
}
if args[0] == "done" {
err = app.Done(id)
} else {
err = app.Delete(id)
}
if err != nil {
return err
}
fmt.Fprintf(stdout, "tugas %d diperbarui\n", id)
return nil
default:
usage(stderr)
return fmt.Errorf("perintah tidak dikenal: %s", args[0])
}
}
func main() {
if err := run(os.Args[1:], os.Stdout, os.Stderr); err != nil {
fmt.Fprintln(os.Stderr, "error:", err)
os.Exit(1)
}
}
Logika run dapat diuji tanpa menjalankan subprocess karena menerima argumen dan writer. main tetap kecil dan menjadi satu-satunya tempat yang memanggil os.Exit.
8. Pengujian Table-Driven
Code
package task
import (
"errors"
"testing"
)
type memoryStore struct {
tasks []Task
loadErr error
saveErr error
}
func (s *memoryStore) Load() ([]Task, error) {
return append([]Task(nil), s.tasks...), s.loadErr
}
func (s *memoryStore) Save(tasks []Task) error {
if s.saveErr != nil {
return s.saveErr
}
s.tasks = append([]Task(nil), tasks...)
return nil
}
func TestAddValidation(t *testing.T) {
tests := []struct {
name string
title string
wantErr error
}{
{name: "kosong", title: " ", wantErr: ErrEmptyTitle},
{name: "valid", title: " Belajar Go "},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
store := &memoryStore{}
got, err := NewApp(store).Add(tt.title)
if !errors.Is(err, tt.wantErr) {
t.Fatalf("Add() error = %v, ingin %v", err, tt.wantErr)
}
if tt.wantErr == nil && got.Title != "Belajar Go" {
t.Errorf("Title = %q, ingin %q", got.Title, "Belajar Go")
}
})
}
}
func TestDoneNotFound(t *testing.T) {
err := NewApp(&memoryStore{}).Done(99)
if !errors.Is(err, ErrNotFound) {
t.Fatalf("Done() error = %v, ingin ErrNotFound", err)
}
}
Code
package task
import (
"os"
"path/filepath"
"testing"
)
func TestJSONStoreRoundTrip(t *testing.T) {
path := filepath.Join(t.TempDir(), "data", "tasks.json")
store := JSONStore{Path: path}
want := []Task{{ID: 1, Title: "Uji persistensi", Done: true}}
if err := store.Save(want); err != nil {
t.Fatalf("Save() error = %v", err)
}
got, err := store.Load()
if err != nil {
t.Fatalf("Load() error = %v", err)
}
if len(got) != 1 || got[0] != want[0] {
t.Fatalf("Load() = %#v, ingin %#v", got, want)
}
}
func TestJSONStoreRejectsBrokenJSON(t *testing.T) {
path := filepath.Join(t.TempDir(), "tasks.json")
if err := os.WriteFile(path, []byte("{"), 0o600); err != nil {
t.Fatal(err)
}
if _, err := (JSONStore{Path: path}).Load(); err == nil {
t.Fatal("Load() error = nil, ingin error decode")
}
}
Tambahkan test untuk save error, load error, ID maksimum, delete, file tidak ada, dan argumen CLI. Test run dapat memakai bytes.Buffer sebagai stdout dan stderr.
9. Validasi dan Penanganan Error
Validasi dilakukan pada dua batas:
- CLI: jumlah argumen, nama perintah, dan format ID.
- Domain: judul kosong/panjang dan keberadaan tugas.
Error I/O dibungkus memakai %w agar konteks terbaca tanpa kehilangan penyebab. Jangan mencetak error pada setiap lapisan; kembalikan error sampai main, lalu cetak sekali ke stderr. Output normal masuk stdout agar dapat dipipe.
Exit code versi ini:
0: operasi berhasil;1: input, domain, atau operasi gagal.
Jika otomasi nantinya perlu membedakan kesalahan penggunaan dari kegagalan penyimpanan, petakan error ke exit code khusus di main. Jangan menambahkan klasifikasi sebelum ada konsumen nyata.
10. Build dan Penggunaan
Code
gofmt -w .
go build -o task ./cmd/task
./task -file ./tmp/tasks.json add "Belajar Go"
./task -file ./tmp/tasks.json list
./task -file ./tmp/tasks.json done 1
./task -file ./tmp/tasks.json delete 1
Flag global harus muncul sebelum subcommand karena flag.FlagSet berhenti memproses flag pada argumen non-flag pertama.
11. Perintah Verifikasi
Jalankan seluruh pemeriksaan dari root module:
Code
gofmt -w .
go vet ./...
go test ./...
go test -shuffle=on -count=10 ./...
go test -race ./...
go test -coverprofile=coverage.out ./...
go tool cover -func=coverage.out
go build ./cmd/task
go mod tidy
go mod verify
Verifikasi perilaku kegagalan:
Code
./task -file ./tmp/tasks.json add ""
./task -file ./tmp/tasks.json done abc
./task -file ./tmp/tasks.json done 999
printf '{' > ./tmp/broken.json
./task -file ./tmp/broken.json list
Perintah di atas harus gagal tanpa mengganti file JSON rusak. Periksa stdout, stderr, dan exit status:
Code
./task -file ./tmp/tasks.json list >/tmp/task.out 2>/tmp/task.err
printf 'exit=%s\n' "$?"
12. Kriteria Selesai
- semua contoh dikompilasi dengan versi Go pada
go.mod;
- data bertahan setelah proses berhenti;
- file tidak ada dianggap daftar kosong, tetapi JSON rusak dilaporkan;
- write memakai temp file pada direktori tujuan dan rename;
- input tidak valid menghasilkan pesan jelas di stderr dan status nonzero;
- test tidak membaca atau menulis data pengguna;
go vet, go test, dan go test -race berhasil;- binary dapat dibangun tanpa dependency eksternal.
Kesalahan Umum
- Menaruh seluruh logika di
main. Pisahkan parsing dari domain dan penyimpanan.
- Mengabaikan save error setelah mutasi. Laporkan kegagalan; jangan mengumumkan keberhasilan.
- Menimpa JSON rusak dengan daftar kosong. Bedakan
os.ErrNotExist dari decode error.
- Menghasilkan ID dari panjang slice. Penghapusan dapat menyebabkan ID dipakai ulang; cari ID maksimum.
- Mencetak error di banyak lapisan. Error menjadi duplikat; cetak sekali di batas proses.
- Menggunakan file produksi dalam test. Selalu gunakan
t.TempDir() atau fake store.
- Menganggap atomic write menyelesaikan multiwriter. Ia mencegah file parsial, bukan lost update.
- Menambahkan framework CLI terlalu dini. Pustaka standar cukup untuk empat subcommand sederhana.
Latihan dan Pengembangan
- Tambahkan perintah
edit <id> <judul> beserta table-driven tests.
- Tambahkan filter
list --done dan list --pending; tentukan posisi flag secara konsisten.
- Uji fungsi
run menggunakan bytes.Buffer untuk stdout dan stderr.
- Tambahkan field waktu dengan clock yang dapat diinjeksi agar test deterministik.
- Tambahkan validasi duplikasi ID ketika membaca data.
- Jika benar-benar membutuhkan dua proses penulis, evaluasi locking lintas platform atau database transaksional dan dokumentasikan trade-off.
- Tambahkan sinkronisasi direktori setelah rename untuk kebutuhan durability yang lebih ketat pada platform yang mendukungnya.
Ringkasan
- Proyek memisahkan antarmuka CLI, aturan aplikasi, dan persistensi tanpa abstraksi berlebihan.
- Validasi ditempatkan pada batas input dan domain; error dibungkus lalu dicetak sekali.
- JSON store memakai permission terbatas dan pola temp-write-sync-close-rename.
- Table-driven tests, fake store, dan
t.TempDir() menjaga pengujian cepat serta terisolasi.
- Format, vet, test, race detector, coverage, dan build membentuk verifikasi sebelum rilis.
