Go Server SDK

SDK phía máy chủ chính thức cho Go — github.com/Captcha-La/captchala-go.

Ba việc SDK xử lý giúp bạn:

1. Xác minh — kiểm tra pass token pt_ từ SDK trình duyệt.
2. Phát hành — tạo một server token sct_ dùng một lần để gắn thử thách sắp tới với một hành động / IP / UID cụ thể.
3. Kiểm duyệt — kiểm duyệt nội dung đa phương thức (văn bản + hình ảnh) qua cùng pipeline tương thích OpenAI mà bảng điều khiển sử dụng.

Cài đặt

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

Chỉ dùng thư viện chuẩn. Không có phụ thuộc bên ngoài.

Xác minh (token pt_)

Hãy truyền IP của người dùng cuối (lấy từ CF-Connecting-IP / X-Forwarded-For, dự phòng bằng RemoteAddr). Tùy chọn, nhưng nên truyền — nó được dùng cho các kiểm tra rủi ro bổ sung.

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

client := captchala.NewClient(appKey, appSecret)

func handler(w http.ResponseWriter, r *http.Request) {
    token := r.FormValue("captcha_token")

    result, err := client.ValidateWithClientIP(token, false, clientIP(r))
    if err != nil || !result.Valid {
        http.Error(w, result.Error, http.StatusBadRequest)
        return
    }
    // Verification passed; proceed with the request.
    // result.CaptchaArgs has Platform / UserIP / Referer / Pkg / SolvedAt / RiskScore
}

// 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
}

Không có sẵn IP? Dùng client.Validate(token) — việc xác minh vẫn hoạt động, chỉ là thiếu tín hiệu rủi ro bổ sung dựa trên IP.

Nếu server_token ban đầu được phát hành với bind_uid, hãy so sánh:

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

Ngữ cảnh tại thời điểm giải thử thách cũng được trả về trong result.CaptchaArgs để bạn tham khảo:

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

Phát hành server token

Khuyến nghị cho các luồng quan trọng (đăng nhập, đăng ký, thanh toán): backend phát hành một token sct_ dùng một lần, trao cho trình duyệt, trình duyệt sử dụng nó làm prop serverToken. Dùng một lần, giới hạn theo hành động, có thể tùy chọn gắn IP/UID.

issue, err := client.IssueServerTokenWithOptions("login", captchala.IssueOptions{
    BindingIP: userIP,    // backend từ chối token nếu IP khác sử dụng
    TTL:       300,       // giây
    MaxUses:   5,         // ngân sách thử lại của SDK
    BindUID:   userID,    // ghép với ValidateResult.UID khi xác minh
})
if err != nil || !issue.OK {
    http.Error(w, issue.Error, http.StatusBadRequest)
    return
}
// trao issue.Token cho trình duyệt

Cách rút gọn chỉ dùng giá trị mặc định:

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

Kiểm duyệt nội dung

Đa phương thức — nhận một slice ModerationItem (text và/hoặc image_url ở định dạng tương thích OpenAI):

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") {
        // chặn cứng
    }
}

Cách rút gọn cho văn bản thuần:

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

Danh mục do model định nghĩa; hãy lặp qua result.Categories một cách phòng vệ thay vì gán cứng một tập cố định.

Kiểu dữ liệu

Kiểu	Trường
ValidateResult	Valid, Error, UID, ChallengeID, Action, Offline, ClientOnly, Warning, CaptchaArgs
CaptchaArgs (tham khảo)	Platform, UserIP, Referer, Pkg, SolvedAt, RiskScore
IssueResult	OK, Token, ExpiresIn, IssuedAt, Error, Message
IssueOptions	BindingIP, TTL, MaxUses, BindUID
ModerationItem	Type, Text, ImageURL (dùng helper TextItem() / ImageURLItem())
ModerationResult	OK, Flagged, Categories, ContentType, Raw, Error, Message; phương thức HasCategory(...names)

Liên kết

• pkg.go.dev · GitHub
• Tổng quan Web SDK · Tài liệu API