Tag 3: Fehlerbehandlung und Module – envcheck
Ziel: Mit Sentinel-Fehlern, eigenem Fehlertyp, Wrapping und
errors.Is/Asdas Toolenvcheckbauen, 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 miterrors.Is. - Eigene Fehlertypen tragen Daten (welcher Check,
welcher Name); herausholen mit
errors.Asoder – neu in Go 1.26 –errors.AsType. - Wrapping mit
fmt.Errorf("kontext: %w", err)ergänzt Kontext, ohne die Ursache zu verlieren.errors.Joinsammelt mehrere Fehler. - Abhängigkeiten stehen in
go.mod(was) undgo.sum(Prüfsummen);go mod tidyrä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.modErwartet (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.modErwartet:
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.yamlErwartet:
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"]mittimeout: 300msliefertnicht 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 %1Erwartet:
✔ 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:
envcheckeignet 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.yamlErwartet:
✔ 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.Errorfpacken. - Exit-Codes dokumentieren und stabil halten; Pipelines und Operatoren verlassen sich darauf.
GOPROXY,GOPRIVATEundGONOSUMDBfür interne Module setzen; in Air-Gap-Umgebungengo mod vendoroder einen internen Proxy nutzen.govulncheckgehört in jede CI-Pipeline, Abhängigkeiten aktualisiert Renovate oder Dependabot – mitgo mod tidy -diffals Gate.- Lizenzen prüfen, bevor eine Abhängigkeit reinkommt (z. B. mit
go-licenses); manche Kunden verbieten (A)GPL im ausgelieferten Binary.