Zum Inhalt springen
Trainingslager IT-Trainingslager

Tag 3: Fehlerbehandlung und Module – envcheck

Ziel: Mit Sentinel-Fehlern, eigenem Fehlertyp, Wrapping und errors.Is/As das Tool envcheck bauen, das prüft, ob Werkzeuge, Umgebungsvariablen und Ports vorhanden sind – mit erster echter Abhängigkeit · Dauer: ca. 120 min · Voraussetzung: Tag 2

Briefing

  • Fehler sind Werte vom Typ error, kein Exception-Mechanismus. Jede Funktion, die scheitern kann, gibt (…, error) zurück; der Aufrufer entscheidet.
  • Sentinel-Fehler (var ErrNotSet = errors.New(…)) sind feste Werte; prüfen mit errors.Is.
  • Eigene Fehlertypen tragen Daten (welcher Check, welcher Name); herausholen mit errors.As oder – neu in Go 1.26 – errors.AsType.
  • Wrapping mit fmt.Errorf("kontext: %w", err) ergänzt Kontext, ohne die Ursache zu verlieren. errors.Join sammelt mehrere Fehler.
  • Abhängigkeiten stehen in go.mod (was) und go.sum (Prüfsummen); go mod tidy räumt auf.
 run() ──► config.Load ──► "config envcheck.yaml: keine Checks konfiguriert"
   │                         └─ %w ─► ErrEmpty                      ⇒ Exit 2
   └─► check.Port ──► *check.Error{Kind:"port", Name:"127.0.0.1:8099"}
                         └─ Err ─► "nicht erreichbar (connect: refused)"
                                     ├─ %w ─► ErrUnreachable
                                     └─ %w ─► syscall.ECONNREFUSED  ⇒ Exit 1

Drill 1: Modul und erste Abhängigkeit

mkdir -p ~/go-lab/tag03-envcheck && cd ~/go-lab/tag03-envcheck
go mod init example.com/envcheck
go get go.yaml.in/yaml/[email protected]
cat go.mod

Erwartet (gekürzt):

go: creating new go.mod: module example.com/envcheck
go: added go.yaml.in/yaml/v3 v3.0.5
module example.com/envcheck

go 1.26.9

require go.yaml.in/yaml/v3 v3.0.5 // indirect

Warum? go.yaml.in/yaml/v3 ist die vom YAML-Projekt weitergepflegte Fassung des bekannten gopkg.in/yaml.v3. Version immer explizit pinnen. // indirect steht da, weil noch kein Code das Paket importiert – das korrigiert go mod tidy in Drill 4.

Fortschritt speichern? Kostenlos registrieren

Drill 2: Sentinel-Fehler und ein eigener Fehlertyp

mkdir -p cmd/envcheck internal/check internal/config
cat > internal/check/errors.go <<'EOF'
// Package check prüft Werkzeuge, Umgebungsvariablen und Ports.
package check

import (
    "errors"
    "fmt"
)

// Sentinel-Fehler: feste Werte, vergleichbar mit errors.Is.
var (
    ErrNotFound    = errors.New("nicht im PATH")
    ErrNotSet      = errors.New("nicht gesetzt")
    ErrUnreachable = errors.New("nicht erreichbar")
)

// Error ist ein fehlgeschlagener Check. errors.As liefert dir die Felder.
type Error struct {
    Kind string // "tool", "env" oder "port"
    Name string // z. B. "kubectl", "HOME", "127.0.0.1:8099"
    Err  error  // die Ursache, meist ein Sentinel
}

func (e *Error) Error() string {
    return fmt.Sprintf("%s %s: %v", e.Kind, e.Name, e.Err)
}

// Unwrap macht die Ursache für errors.Is und errors.As sichtbar.
func (e *Error) Unwrap() error { return e.Err }
EOF
go vet ./...

Erwartet: keine Ausgabe.

Warum? Jeder Typ mit einer Methode Error() string erfüllt das Interface error. Unwrap() verrät errors.Is und errors.As, wo die Kette weitergeht. Der Receiver ist ein Pointer, also ist *check.Error der Fehlertyp – das musst du bei errors.As gleich wiederfinden.

Fortschritt speichern? Kostenlos registrieren

Drill 3: Die drei Checks

cat > internal/check/check.go <<'EOF'
package check

import (
    "errors"
    "fmt"
    "net"
    "os"
    "os/exec"
    "time"
)

// Tool sucht name im PATH und liefert den gefundenen Pfad.
func Tool(name string) (string, error) {
    path, err := exec.LookPath(name)
    if err != nil {
        return "", &Error{Kind: "tool", Name: name, Err: ErrNotFound}
    }
    return path, nil
}

// Env prüft, ob die Umgebungsvariable name gesetzt und nicht leer ist.
func Env(name string) error {
    if os.Getenv(name) == "" {
        return &Error{Kind: "env", Name: name, Err: ErrNotSet}
    }
    return nil
}

// Port prüft, ob auf addr (host:port) ein Dienst TCP-Verbindungen annimmt.
func Port(addr string, timeout time.Duration) error {
    conn, err := net.DialTimeout("tcp", addr, timeout)
    if err != nil {
        // errors.As holt den *net.OpError aus der Kette; sein Err ist kürzer.
        var opErr *net.OpError
        if errors.As(err, &opErr) {
            err = opErr.Err
        }
        // Zwei %w: Sentinel UND Ursache bleiben für errors.Is erreichbar.
        cause := fmt.Errorf("%w (%w)", ErrUnreachable, err)
        return &Error{Kind: "port", Name: addr, Err: cause}
    }
    return conn.Close()
}
EOF
go vet ./...

Erwartet: keine Ausgabe.

Warum? fmt.Errorf mit zwei %w (seit Go 1.20) hält beide Fehler in der Kette: Du kannst später auf ErrUnreachable und auf syscall.ECONNREFUSED prüfen. errors.As mit einem *net.OpError holt nur den kurzen Teil der Meldung heraus; ohne diesen Schritt stünde dial tcp 127.0.0.1:8099: doppelt in der Ausgabe.

Fortschritt speichern? Kostenlos registrieren

Drill 4: Config laden mit Kontext

cat > internal/config/config.go <<'EOF'
// Package config lädt die envcheck-Konfiguration aus einer YAML-Datei.
package config

import (
    "bytes"
    "errors"
    "fmt"
    "io"
    "os"
    "time"

    "go.yaml.in/yaml/v3"
)

// ErrEmpty meldet eine Konfiguration ohne einen einzigen Check.
var ErrEmpty = errors.New("keine Checks konfiguriert")

// Config beschreibt, was auf dem Rechner vorhanden sein muss.
type Config struct {
    Tools   []string      `yaml:"tools"`
    Env     []string      `yaml:"env"`
    Ports   []string      `yaml:"ports"`
    Timeout time.Duration `yaml:"timeout"`
}

// Load liest path. Jeder Fehler wird mit Kontext umhüllt (%w).
func Load(path string) (Config, error) {
    data, err := os.ReadFile(path)
    if err != nil {
        return Config{}, fmt.Errorf("config laden: %w", err)
    }
    var c Config
    dec := yaml.NewDecoder(bytes.NewReader(data))
    dec.KnownFields(true) // Tippfehler wie "tool:" sind Fehler
    if err := dec.Decode(&c); err != nil && !errors.Is(err, io.EOF) {
        return Config{}, fmt.Errorf("config %s: %w", path, err)
    }
    if len(c.Tools)+len(c.Env)+len(c.Ports) == 0 {
        return Config{}, fmt.Errorf("config %s: %w", path, ErrEmpty)
    }
    if c.Timeout <= 0 {
        c.Timeout = 2 * time.Second
    }
    return c, nil
}
EOF
go mod tidy
cat go.mod

Erwartet:

module example.com/envcheck

go 1.26.9

require go.yaml.in/yaml/v3 v3.0.5

Warum? Jede Ebene ergänzt mit %w nur, was sie weiß („config laden”, Dateiname) – die Ursache von os.ReadFile bleibt erhalten. KnownFields(true) macht aus einem Tippfehler im YAML einen Fehler statt eines stillen Nullwerts. Eine leere Datei liefert io.EOF; das ist hier kein Fehler, sondern führt zu ErrEmpty.

Fortschritt speichern? Kostenlos registrieren

Drill 5: main – Fehler auswerten, Exit-Code wählen

cat > cmd/envcheck/main.go <<'EOF'
// envcheck prüft, ob Werkzeuge, Umgebungsvariablen und Ports vorhanden sind.
// Tag 3 aus "Go zum Anfassen".
package main

import (
    "errors"
    "flag"
    "fmt"
    "io/fs"
    "os"

    "example.com/envcheck/internal/check"
    "example.com/envcheck/internal/config"
)

// Exit-Codes: 0 = alles da, 1 = Checks fehlgeschlagen, 2 = Aufruf/Config kaputt.
func main() {
    path := flag.String("config", "envcheck.yaml", "Pfad zur YAML-Konfiguration")
    flag.Parse()

    err := run(*path)
    if err == nil {
        return
    }
    var ce *check.Error
    if errors.As(err, &ce) { // mindestens ein Check ist fehlgeschlagen
        if errors.Is(err, check.ErrNotSet) {
            fmt.Fprintln(os.Stderr, "Tipp: fehlende Variablen mit export setzen")
        }
        os.Exit(1)
    }
    fmt.Fprintln(os.Stderr, "envcheck:", err)
    if errors.Is(err, fs.ErrNotExist) {
        fmt.Fprintln(os.Stderr, "Tipp: envcheck.yaml anlegen oder -config nutzen")
    }
    os.Exit(2)
}

// run lädt die Config, führt alle Checks aus und druckt eine Tabelle.
// Fehlgeschlagene Checks kommen gesammelt per errors.Join zurück.
func run(path string) error {
    cfg, err := config.Load(path)
    if err != nil {
        return err
    }
    var errs []error
    for _, name := range cfg.Tools {
        where, err := check.Tool(name)
        errs = append(errs, line("tool", name, where, err))
    }
    for _, name := range cfg.Env {
        errs = append(errs, line("env", name, "gesetzt", check.Env(name)))
    }
    for _, addr := range cfg.Ports {
        err := check.Port(addr, cfg.Timeout)
        errs = append(errs, line("port", addr, "offen", err))
    }
    joined := errors.Join(errs...) // nil-Einträge ignoriert Join
    if joined == nil {
        fmt.Printf("alle %d Checks bestanden\n", len(errs))
        return nil
    }
    failed := 0
    for _, err := range errs {
        if err != nil {
            failed++
        }
    }
    fmt.Printf("%d von %d Checks fehlgeschlagen\n", failed, len(errs))
    return joined
}

// line schreibt eine Ergebniszeile und reicht err unverändert durch.
func line(kind, name, ok string, err error) error {
    mark, detail := "✔", ok
    // Go 1.26: errors.AsType ist die generische Variante von errors.As.
    if ce, isCheck := errors.AsType[*check.Error](err); isCheck {
        mark, detail = "✘", ce.Err.Error()
    }
    fmt.Printf("%s %-5s %-16s %s\n", mark, kind, name, detail)
    return err
}
EOF
cat > envcheck.yaml <<'EOF'
# envcheck.yaml – was dieser Rechner für die Labs braucht
tools: [go, git, kubectl, helm]
env: [HOME, KUBECONFIG]
ports: ["127.0.0.1:8099"]
timeout: 500ms
EOF
go build -o bin/envcheck ./cmd/envcheck
./bin/envcheck; echo "exit=$?"

Erwartet (Pfade und Ergebnisse hängen von deinem Rechner ab):

✔ tool  go               /opt/homebrew/bin/go
✔ tool  git              /opt/homebrew/bin/git
✔ tool  kubectl          /opt/homebrew/bin/kubectl
✔ tool  helm             /opt/homebrew/bin/helm
✔ env   HOME             gesetzt
✘ env   KUBECONFIG       nicht gesetzt
✘ port  127.0.0.1:8099   nicht erreichbar (connect: connection refused)
2 von 7 Checks fehlgeschlagen
Tipp: fehlende Variablen mit export setzen
exit=1

Warum? main ist dünn: run liefert einen Fehler, main macht daraus einen Exit-Code. errors.As findet den ersten *check.Error auch durch errors.Join hindurch – damit weißt du „Checks gescheitert” (1) statt „Aufruf kaputt” (2). errors.Is(err, check.ErrNotSet) durchsucht dieselbe Kette nach dem Sentinel. In line siehst du errors.AsType: gleiche Wirkung, aber ohne vorher deklarierte Variable.

Fortschritt speichern? Kostenlos registrieren

Drill 6: Fehlerketten lesen

Jetzt die Fehlerpfade. Jede Meldung zeigt die Kette von außen nach innen:

./bin/envcheck -config nope.yaml; echo "exit=$?"
printf 'tool: [go]\n' > typo.yaml
./bin/envcheck -config typo.yaml; echo "exit=$?"
: > leer.yaml
./bin/envcheck -config leer.yaml; echo "exit=$?"
printf 'tools: [go]\ntimeout: zwei\n' > bad.yaml
./bin/envcheck -config bad.yaml; echo "exit=$?"
rm typo.yaml leer.yaml bad.yaml

Erwartet:

envcheck: config laden: open nope.yaml: no such file or directory
Tipp: envcheck.yaml anlegen oder -config nutzen
exit=2
envcheck: config typo.yaml: yaml: unmarshal errors:
  line 1: field tool not found in type config.Config
exit=2
envcheck: config leer.yaml: keine Checks konfiguriert
exit=2
envcheck: config bad.yaml: yaml: unmarshal errors:
  line 2: cannot unmarshal !!str `zwei` into time.Duration
exit=2

Warum? Der Tipp bei nope.yaml kommt aus errors.Is(err, fs.ErrNotExist): Unter deinem Wrapping steckt der *fs.PathError von os.ReadFile, und dessen Ursache gilt als fs.ErrNotExist. Vergleiche nie Fehlertexte mit strings.Contains; Texte ändern sich, Sentinels und Typen nicht.

Tipp: Ein Timeout-Fall zum Ausprobieren: ports: ["10.255.255.1:443"] mit timeout: 300ms liefert nicht erreichbar (i/o timeout) – die Adresse antwortet nie.

Fortschritt speichern? Kostenlos registrieren

Drill 7: Module pflegen und prüfen

go list -m all
go mod why go.yaml.in/yaml/v3
go mod verify
cat go.sum
go run golang.org/x/vuln/cmd/[email protected] ./...

Erwartet:

example.com/envcheck
go.yaml.in/yaml/v3 v3.0.5
# go.yaml.in/yaml/v3
example.com/envcheck/internal/config
go.yaml.in/yaml/v3
all modules verified
go.yaml.in/yaml/v3 v3.0.5 h1:N6y/pJk8buWs9NY5ERU2HSMfm+IuD/OtfdAnq6kESPw=
go.yaml.in/yaml/v3 v3.0.5/go.mod h1:HVTZu1O7/Vkt2N+BFy8Zza+lnLsABggaTM2ZpNIGuKg=
No vulnerabilities found.
Befehl Wozu
go list -m all alle Module im Build, auch transitive
go mod why <modul> welches deiner Pakete zieht es herein
go mod verify Cache-Inhalt gegen go.sum prüfen
govulncheck ./... bekannte CVEs – nur wenn der Code die Funktion wirklich aufruft

Warum? go.sum enthält Prüfsummen; die Werte gleicht Go außerdem mit der öffentlichen Checksum-Datenbank sum.golang.org ab. Wer ein Modul nachträglich manipuliert, fällt auf. go.mod und go.sum gehören beide ins Git.

Fortschritt speichern? Kostenlos registrieren

Drill 8: Das Tool ist fertig

Ein Dienst auf Port 8099 und eine gesetzte Variable – dann muss alles grün sein:

cd ~/go-lab/tag03-envcheck
python3 -m http.server 8099 --bind 127.0.0.1 >/dev/null 2>&1 &
sleep 1
KUBECONFIG=~/.kube/config ./bin/envcheck; echo "exit=$?"
kill %1

Erwartet:

✔ tool  go               /opt/homebrew/bin/go
✔ tool  git              /opt/homebrew/bin/git
✔ tool  kubectl          /opt/homebrew/bin/kubectl
✔ tool  helm             /opt/homebrew/bin/helm
✔ env   HOME             gesetzt
✔ env   KUBECONFIG       gesetzt
✔ port  127.0.0.1:8099   offen
alle 7 Checks bestanden
exit=0

Dein Modul:

tag03-envcheck/
├── cmd/envcheck/main.go          run(), Exit-Codes, Ausgabe
├── internal/check/errors.go      Sentinels, *check.Error
├── internal/check/check.go       Tool, Env, Port
├── internal/config/config.go     YAML laden, Wrapping
├── envcheck.yaml
├── go.mod
└── go.sum

Tipp: envcheck eignet sich als erster Schritt in Makefiles und CI-Jobs: Statt kryptischer Fehler mitten im Build steht gleich zu Beginn, was fehlt. Die Labs der nächsten Tage kannst du damit vorab prüfen.

Fortschritt speichern? Kostenlos registrieren

Kontrollpunkt

#!/usr/bin/env bash
check() { if eval "$2" >/dev/null 2>&1; then echo "✔ $1"; else echo "✘ $1"; fi; }
cd ~/go-lab/tag03-envcheck
check "gofmt sauber" "test -z \"\$(gofmt -l .)\""
check "go vet" "go vet ./..."
check "golangci-lint" "~/go-lab/bin/lint run ./..."
check "go.mod aufgeräumt" "go mod tidy -diff"
check "Prüfsummen ok" "go mod verify"
check "Exit 1 bei fehlendem Port" \
  "printf 'ports: [\"127.0.0.1:1\"]\n' > /tmp/ec.yaml;
   ./bin/envcheck -config /tmp/ec.yaml; test \$? -eq 1"
check "Exit 2 ohne Config" "./bin/envcheck -config /nix.yaml; test \$? -eq 2"
rm -f /tmp/ec.yaml

Erwartet:

✔ gofmt sauber
✔ go vet
✔ golangci-lint
✔ go.mod aufgeräumt
✔ Prüfsummen ok
✔ Exit 1 bei fehlendem Port
✔ Exit 2 ohne Config

go mod tidy -diff ändert nichts, sondern meldet nur, ob tidy etwas ändern würde – ideal für CI.

Challenge

Schreib ein zweites Kommando waitport im selben Modul: Es wartet, bis ein Port offen ist (waitport -timeout 10s 127.0.0.1:8099), und gibt bei jedem abgewiesenen Versuch „noch zu” aus. Benutze check.Port wieder und erkenne „Verbindung abgewiesen” ohne Textvergleich.

Hinweis: Dank der zwei %w in check.Port liegt syscall.ECONNREFUSED in der Fehlerkette.

Lösung

mkdir -p cmd/waitport
cat > cmd/waitport/main.go <<'EOF'
// waitport wartet, bis ein TCP-Port offen ist – etwa vor Integrationstests.
package main

import (
    "errors"
    "flag"
    "fmt"
    "os"
    "syscall"
    "time"

    "example.com/envcheck/internal/check"
)

func main() {
    timeout := flag.Duration("timeout", 10*time.Second, "maximale Wartezeit")
    flag.Parse()
    if flag.NArg() != 1 {
        fmt.Fprintln(os.Stderr, "Aufruf: waitport [-timeout 10s] host:port")
        os.Exit(2)
    }
    addr := flag.Arg(0)
    deadline := time.Now().Add(*timeout)
    for {
        err := check.Port(addr, time.Second)
        if err == nil {
            fmt.Println("offen:", addr)
            return
        }
        if time.Now().After(deadline) {
            fmt.Fprintln(os.Stderr, "waitport:", err)
            os.Exit(1)
        }
        // Die Kette aus Tag-3-Fehlern reicht bis zum Syscall-Fehler.
        if errors.Is(err, syscall.ECONNREFUSED) {
            fmt.Println("noch zu, neuer Versuch ...")
        }
        time.Sleep(500 * time.Millisecond)
    }
}
EOF
go build -o bin/waitport ./cmd/waitport
(sleep 1; python3 -m http.server 8099 --bind 127.0.0.1 >/dev/null 2>&1) &
./bin/waitport 127.0.0.1:8099; echo "exit=$?"
pkill -f 'http.server 8099'
./bin/waitport -timeout 1s 127.0.0.1:8099; echo "exit=$?"

Erwartet (die Zahl der Versuche variiert):

noch zu, neuer Versuch ...
noch zu, neuer Versuch ...
noch zu, neuer Versuch ...
offen: 127.0.0.1:8099
exit=0
noch zu, neuer Versuch ...
noch zu, neuer Versuch ...
waitport: port 127.0.0.1:8099: nicht erreichbar (connect: connection refused)
exit=1

Zwei Kommandos teilen sich ein internes Paket – das ist der Grund für das Layout cmd/<tool> plus internal/. Die Timeout-Variante (i/o timeout) zählt nicht als „abgewiesen” und läuft still bis zur Deadline. In Tag 15 (Challenge portwait) ersetzt du die Schleife durch context.WithTimeout und Backoff.

Fortschritt speichern? Kostenlos registrieren

Enterprise-Notiz

  • Fehlermeldungen sind Schnittstellen: Kontext rein (welche Datei, welcher Host), Secrets raus. Nie Tokens, Passwörter oder komplette Connection-Strings in fmt.Errorf packen.
  • Exit-Codes dokumentieren und stabil halten; Pipelines und Operatoren verlassen sich darauf.
  • GOPROXY, GOPRIVATE und GONOSUMDB für interne Module setzen; in Air-Gap-Umgebungen go mod vendor oder einen internen Proxy nutzen.
  • govulncheck gehört in jede CI-Pipeline, Abhängigkeiten aktualisiert Renovate oder Dependabot – mit go mod tidy -diff als Gate.
  • Lizenzen prüfen, bevor eine Abhängigkeit reinkommt (z. B. mit go-licenses); manche Kunden verbieten (A)GPL im ausgelieferten Binary.