استفاده از SDKهای Go تولیدشده در Postman

این راهنما روش استفاده از SDKهای Go تولیدشده با Postman SDK Generator را توضیح می‌دهد. SDK Go به صورت module قابل نصب است و برای کار با context، error handling، environment، retry و validation آماده می‌شود.

ساختار SDK Go

• client.go: client اصلی SDK.
• services/: serviceها و methodهای API.
• models/: structهای request/response و error modelها.
• config/: تنظیمات authentication، base URL، timeout و retry.
• go.mod: module name و dependencyها.

اجرای نمونه SDK

هر SDK پوشه examples/ دارد. اول نمونه را اجرا کنید تا الگوی استفاده روشن شود.

cd examples
go mod tidy
go run main.go

package main

import (
    "context"
    "fmt"

    sdk "github.com/your-org/your-sdk"
)

func main() {
    client := sdk.NewClient(sdk.Config{
        APIKey: "your-api-key",
        BaseURL: "https://api.example.com",
    })

    user, err := client.Users.GetUser(context.Background(), "123")
    if err != nil {
        fmt.Println("Error:", err)
        return
    }

    fmt.Println("User:", user)
}

نصب SDK Go

نصب با go get

go get github.com/your-org/your-sdk

نصب از مسیر local

برای توسعه محلی، در go.mod از replace استفاده کنید.

require github.com/your-org/your-sdk v0.0.0

replace github.com/your-org/your-sdk => ../path/to/your-sdk

go mod tidy

انتشار به عنوان Go module

Go معمولا package registry جداگانه لازم ندارد. کافی است repository عمومی یا قابل دسترس باشد، module path درست باشد و release tag بسازید.

git tag v1.0.0
git push origin v1.0.0

بعد از tag، کاربران می‌توانند با go get github.com/your-org/your-sdk@v1.0.0 نصب کنند.

انتشار نسخه جدید

git tag v1.0.1
git push origin v1.0.1

بهترین کارها برای Go SDK

• module path را از ابتدا درست انتخاب کنید.
• از semantic versioning استفاده کنید.
• برای major versionهای جدید، قوانین Go module مثل /v2 را رعایت کنید.
• قبل از release، go test ./... و go vet ./... را اجرا کنید.
• README و exampleهای کوتاه ارائه دهید.

Authentication

client := sdk.NewClient(sdk.Config{
    APIKey: "your-api-key",
})

client := sdk.NewClient(sdk.Config{
    AccessToken: "your-bearer-token",
})

client := sdk.NewClient(sdk.Config{
    Username: "your-username",
    Password: "your-password",
})

Error handling

در Go خطاها با مقدار error برگردانده می‌شوند. برای API errorها می‌توانید type assertion یا errors.As استفاده کنید.

user, err := client.Users.GetUser(ctx, "123")
if err != nil {
    var apiErr *sdk.APIError
    if errors.As(err, &apiErr) {
        fmt.Println("Status:", apiErr.StatusCode)
        fmt.Println("Response:", apiErr.ResponseBody)
        return
    }
    fmt.Println("Unexpected error:", err)
    return
}

if apiErr.StatusCode == 404 {
    fmt.Println("User not found")
}

Environment management

client := sdk.NewClient(sdk.Config{
    Environment: sdk.Production,
    APIKey: "your-api-key",
})

customClient := sdk.NewClient(sdk.Config{
    BaseURL: "https://custom.api.example.com",
    APIKey: "your-api-key",
})

Hierarchical configuration

در SDKهای Go هم می‌توانید تنظیمات را در سطح client، service، method یا request override کنید؛ بسته به خروجی generator.

reqCfg := sdk.RequestConfig{
    Timeout: 30 * time.Second,
    BaseURL: "https://legacy-api.example.com",
}

user, err := client.Users.GetUser(ctx, "123", reqCfg)

Timeout و retry

client := sdk.NewClient(sdk.Config{
    APIKey: "your-api-key",
    Timeout: 10 * time.Second,
    Retry: sdk.RetryConfig{
        Attempts: 3,
        Delay: 1 * time.Second,
        MaxDelay: 30 * time.Second,
        BackoffFactor: 2,
    },
})

برای timeoutهای خاص request، از context.WithTimeout استفاده کنید.

ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()

user, err := client.Users.GetUser(ctx, "123")

Validation

SDK constraintهای OpenAPI را قبل از ارسال request بررسی می‌کند. اگر مقدارها معتبر نباشند، خطای validation دریافت می‌کنید و می‌توانید مسیر field و پیام خطا را بررسی کنید.

Optional و nullable fieldها

در Go معمولا pointerها برای نمایش nullable یا optional بودن fieldها استفاده می‌شوند. این کمک می‌کند SDK فرق بین مقدار صفر، مقدار null و field حذف‌شده را بهتر نگه دارد.

name := "new name"
req := sdk.UpdateUserRequest{
    Name: &name,
}

منابع داخل SDK

• پوشه documentation/ برای مستندات serviceها و modelها.
• پوشه examples/ برای نمونه‌های اجرایی.
• go.mod برای module و dependencyها.
• نمونه‌های context، error handling و retry داخل exampleها.

منبع آموزشی: Postman Docs، بازنویسی و ساده‌سازی‌شده برای کاربران فارسی‌زبان.