Migration zu v3

​

Auf einen Blick

​

Konstruktion und Optionen

-import (
-	"github.com/squarecloudofc/sdk-api-go/v2/rest"
-	"github.com/squarecloudofc/sdk-api-go/v2/squarecloud"
-)
-client := rest.NewClient(token, rest.WithUserAgent(ua), rest.WithLogger(logger))
-api := rest.New(client)
-defer client.Close()
+import "github.com/squarecloudofc/sdk-api-go/v3"
+
+c := squarecloud.New(token, squarecloud.WithUserAgent(ua))

go get github.com/squarecloudofc/sdk-api-go/v3@v3.0.0

​

Methode für Methode

​

Typen

​

Fehler

// v2
if rest.IsRateLimit(err) { ... }

// v3
var apiErr *squarecloud.APIError
if errors.As(err, &apiErr) && apiErr.Status == 429 {
	fmt.Println(apiErr.Code, apiErr.Message) // KEEP_CALM or RATE_LIMITED
}

• Netzwerkfehler sind jetzt *APIError mit Status 0, Code NETWORK_ERROR oder TIMEOUT und dem Text der Ursache als Message, und sie lassen sich zur Ursache entpacken (errors.Is(err, context.Canceled) funktioniert).
• Ebenso lokale Prüfungen (Status 0: INVALID_ID, FILE_TOO_LARGE, INVALID_API_KEY) und ein 2xx-Body, der kein JSON ist (UNKNOWN_ERROR, Invalid JSON in HTTP <status> response).
• Ein 2xx-Body mit "status": "error" ist jetzt ein Fehler (v2 meldete ihn als Erfolg). Die Ablehnungen des Clusters beim Starten/Stoppen von Apps und Datenbanken kommen als 409 CONTAINER_ALREADY_STARTED, CONTAINER_ALREADY_STOPPED, CONTAINER_TEMPORARILY_SUSPENDED, CONTAINER_NOT_FOUND, CONTAINER_INSUFFICIENT_DISK_SPACE, CONTAINER_NETWORK_CONFLICT oder ACTION_FAILED, ohne Nachricht. Das SDK gibt eine „bereits“-Antwort als Fehler zurück: Behandle sie selbst als Erfolg, wenn du das brauchst.
• Eine Antwort ohne Code hat den Code UNKNOWN_ERROR.
• Ein abgelaufener API-Schlüssel ergibt 401 ACCESS_DENIED, wie ein unbekannter.
• Es gibt eine Code*-Konstante für jeden Code, den die API dokumentiert. Die API sendet jetzt 429 RATE_LIMITED (CodeRateLimited), wo sie RATE_LIMIT und RATE_LIMIT_EXCEEDED sendete; CodeRateLimit und CodeRateLimitExceeded bleiben erhalten, als veraltet markiert.
• Jeder Fehler von AI.Chat hat die Form von OpenAI mit einem kleingeschriebenen Code (access_denied, rate_limit_exceeded, server_overloaded, …), den Code unverändert enthält.
• Error() erzeugt squarecloud: <METHOD> <path>: HTTP <status> <CODE>: <message> (v2: squarecloud: <message> (<CODE>, HTTP <status>)). Prüfe die Felder, nicht den Text.

​

Verhaltensänderungen

• Leerer API-Schlüssel: New("") (oder ein nur aus Leerzeichen bestehender Schlüssel) gibt weiterhin einen Client zurück (es kann keinen Fehler zurückgeben), aber jeder Aufruf außer Service.Status schlägt lokal mit INVALID_API_KEY fehl.
• Snapshot 202: v2 gab einen *APIError mit StatusCode 202 zurück. v3 gibt ein SnapshotCreated mit Pending: true und einen nil-Fehler zurück.
• Realtime: Next gibt jetzt ein RealtimeEvent zurück. Verzweige nach ev.Event (system, status, logs, error, message). Für Logs gib ev.Line aus (das Byte \u0001/\u0002 wird entfernt; ev.Data bleibt der rohe Frame) und verwende ev.Stream für stdout/stderr. Für den Status verwende ev.Status: bei einem Status-Ereignis nie nil, flach über Frames und Neuverbindungen hinweg zusammengeführt. Nach REALTIME_DISCONNECTED gibt Next io.EOF zurück. Der Stream bricht nicht mehr nach 30 s ab, Neuverbindungen warten mindestens 5,5 s nach dem vorherigen Öffnen, und das Öffnen ist durch das Client-Timeout begrenzt, bis die Header eintreffen. Siehe Realtime.
• Timeouts: v2 verwendete für alles ein festes Timeout von 30 s im http.Client. v3 wendet eine Standard-Deadline nur an, wenn ctx keine hat: das Client-Timeout (WithTimeout, 30 s) für die meisten Aufrufe; mindestens 2 Minuten für Start/Stop/Restart, das Erstellen von Datenbanken, das Erstellen/Wiederherstellen von Snapshots und AI.Chat; keine für Uploads, Dateischreibvorgänge mit über 1 MiB Inhalt und Snapshot-Downloads. WithTimeout(0) deaktiviert sie alle.
• Leere Netzwerkfenster: Analytics, Errors und Performance geben nil-Zeiger zurück, wenn das Fenster keinen Verkehr hat.
• Header: Jede API-Anfrage sendet Accept: application/json (text/event-stream für Realtime). Der Standard-User-Agent hat sich von Square GO zu squarecloud-sdk-go/3.0.0 geändert (WithUserAgent überschreibt ihn weiterhin).
• IDs: Jede ID wird jetzt als ein Pfadsegment prozentkodiert (v2 fügte sie unverändert in den Pfad ein), und eine leere ID, . oder .. schlägt lokal mit INVALID_ID fehl.
• Dateischreibvorgänge: v2 sendete den Inhalt immer als String, was Binärdateien beschädigte, und konnte keine leere Datei schreiben. v3 sendet den Inhalt immer Base64-kodiert, sodass jedes Byte erhalten bleibt, leerer Inhalt eine leere Datei schreibt und Inhalt über 10 MB lokal mit FILE_TOO_LARGE fehlschlägt. Die API antwortet mit 400 INVALID_CONTENT auf Inhalt, den sie nicht dekodieren kann.
• Dateilesevorgänge: v3 fordert immer Base64 an und dekodiert es, statt des JSON-Byte-Arrays, das v2 las (und das die API als veraltet markiert hat). Eine Datei über 10 MB ergibt 413 FILE_TOO_LARGE.
• Dateiauflistung: Das Auflisten eines Verzeichnisses, das nicht existiert, ergibt 404 FILE_NOT_FOUND; früher war es eine leere Liste.
• Snapshots: Listeneinträge enthalten VersionID und URL von der API; aus Key wird nichts herausgeparst.
• Wiederholungen: neu. Netzwerkfehler bei GET, 503 UPLOAD_BUSY/ANALYTICS_BUSY und 503 DATABASE_UNAVAILABLE bei GET werden standardmäßig zweimal wiederholt; WithMaxRetries(0) stellt das Verhalten von v2 wieder her. DATABASE_UNAVAILABLE kann eintreffen, nachdem eine Mutation begonnen hat, daher wiederholt das SDK ihn bei anderen Methoden nie; wiederhole eine idempotente Mutation selbst, wenn du möchtest. Siehe Wiederholungen.
• Go-Version: Das Minimum ist von Go 1.24 auf Go 1.22 gesunken.