---
title: Go Server SDK
---

# Go Server SDK

SDK sisi pelayan Go rasmi — `github.com/Captcha-La/captchala-go`.

Tiga tugas yang dikendalikan SDK untuk anda:

1. **Sahkan** — sahkan token pass `pt_` daripada SDK pelayar.
2. **Keluarkan** — cetak token pelayan `sct_` sekali guna untuk mengikat cabaran yang akan datang kepada tindakan / IP / UID tertentu.
3. **Kawal selia** — pengawasan kandungan pelbagai mod (teks + imej) terhadap saluran serasi-OpenAI yang sama digunakan oleh papan pemuka.

## Pemasangan

```bash
go get github.com/Captcha-La/captchala-go
```

Stdlib sahaja. Tiada kebergantungan luaran.

## Sahkan (token `pt_`)

```go
import captchala "github.com/Captcha-La/captchala-go"

client := captchala.NewClient(appKey, appSecret)

result, err := client.ValidateWithClientIP(token, false, clientIP(r))
if err != nil || !result.Valid {
    http.Error(w, result.Error, http.StatusBadRequest)
    return
}
// proceed with the request

// Real end-user IP behind a CDN / proxy
func clientIP(r *http.Request) string {
    if ip := r.Header.Get("CF-Connecting-IP"); ip != "" {
        return ip
    }
    if xff := r.Header.Get("X-Forwarded-For"); xff != "" {
        return strings.TrimSpace(strings.Split(xff, ",")[0])
    }
    host, _, _ := net.SplitHostPort(r.RemoteAddr)
    return host
}
```

Jika `server_token` asal dikeluarkan dengan `bind_uid`, bandingkan:

```go
if result.UID != expectedUserID {
    http.Error(w, "user mismatch", http.StatusBadRequest)
    return
}
```

Argumen IP `ValidateWithClientIP` adalah **pilihan tetapi disyorkan** — hantar IP
pengguna akhir daripada permintaan masuk anda; ia digunakan untuk pemeriksaan
risiko tambahan. Selamat untuk ditinggalkan (kemudian gunakan `Validate` /
`ValidateWithOptions`). Konteks masa penyelesaian turut dikembalikan dalam
`result.CaptchaArgs` untuk rujukan anda:

```go
ip := result.CaptchaArgs.UserIP   // visitor IP recorded at solve time
```

## Keluarkan token pelayan

Disyorkan untuk aliran bernilai tinggi (log masuk, pendaftaran, pembayaran): backend mencetak
token `sct_` sekali guna, menyerahkannya kepada pelayar, dan pelayar menggunakannya sebagai
prop `serverToken`. Sekali guna, terhad kepada tindakan, secara pilihan diikat IP/UID.

```go
issue, err := client.IssueServerTokenWithOptions("login", captchala.IssueOptions{
    BindingIP: userIP,    // backend menolak token jika IP berbeza menebusnya
    TTL:       300,       // saat
    MaxUses:   5,         // bajet cuba semula SDK
    BindUID:   userID,    // pasangkan dengan ValidateResult.UID semasa pengesahan
})
if err != nil || !issue.OK {
    http.Error(w, issue.Error, http.StatusBadRequest)
    return
}
// serahkan issue.Token kepada pelayar
```

Pintasan lalai sahaja:

```go
issue, err := client.IssueServerToken("login")
```

## Kawal selia kandungan

Pelbagai mod — menerima keping `ModerationItem` (teks dan/atau image_url dalam
format serasi-OpenAI):

```go
result, err := client.ModerationCheck([]captchala.ModerationItem{
    captchala.TextItem(userComment),
    captchala.ImageURLItem(uploadedImageURL),
}, userID)

if err != nil || !result.OK {
    http.Error(w, result.Error, http.StatusBadRequest)
    return
}

if result.Flagged {
    if result.HasCategory("violence", "csam") {
        // sekatan keras
    }
}
```

Pintasan teks biasa:

```go
result, err := client.ModerationText("user comment here", userID)
```

Kategori ditakrifkan oleh model; lelarkan `result.Categories` secara defensif dan bukannya
mengekod set tetap.

## Jenis

| Jenis | Medan |
|---|---|
| `ValidateResult` | `Valid`, `Error`, `UID`, `ChallengeID`, `Action`, `Offline`, `ClientOnly`, `Warning`, `CaptchaArgs` |
| `CaptchaArgs` | `Platform`, `UserIP`, `Referer`, `Pkg`, `SolvedAt`, `RiskScore` (untuk maklumat sahaja) |
| `IssueResult` | `OK`, `Token`, `ExpiresIn`, `IssuedAt`, `Error`, `Message` |
| `IssueOptions` | `BindingIP`, `TTL`, `MaxUses`, `BindUID` |
| `ModerationItem` | `Type`, `Text`, `ImageURL` (gunakan pembantu `TextItem()` / `ImageURLItem()`) |
| `ModerationResult` | `OK`, `Flagged`, `Categories`, `ContentType`, `Raw`, `Error`, `Message`; kaedah `HasCategory(...names)` |

## Pautan

- [pkg.go.dev](https://pkg.go.dev/github.com/Captcha-La/captchala-go) · [GitHub](https://github.com/Captcha-La/captchala-go)
- [Gambaran Web SDK](/ms/web-sdk) · [Rujukan API](/ms/api-reference)