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

این راهنما روش استفاده از SDKهای Kotlin تولیدشده با Postman SDK Generator را توضیح می‌دهد. خروجی Kotlin برای پروژه‌های JVM مناسب است و معمولا با Gradle یا Maven وارد پروژه می‌شود. ساختار کلی آن شبیه SDKهای Java است، اما نمونه‌ها و importها برای Kotlin نوشته شده‌اند.

ساختار SDK Kotlin

• [SdkName].kt: client اصلی SDK که با config ساخته می‌شود.
• services/: کلاس‌های service برای endpointها، با methodهای synchronous و asynchronous.
• models/: data classها، enumها، builderها و exceptionهای typed.
• config/: تنظیمات authentication، timeout، retry و base URL.
• pom.xml یا فایل‌های Gradle: وابستگی‌هایی مثل OkHttp، Jackson و Kotlin runtime.

اجرای نمونه SDK

هر SDK تولیدشده پوشه examples/ دارد. ابتدا همان نمونه را اجرا کنید تا مطمئن شوید SDK و authentication درست تنظیم شده‌اند.

cd examples
./run.sh

اگر بخواهید دستی اجرا کنید:

cd path/to/your-sdk
mvn clean install
cd examples
mvn clean install
mvn exec:java

val config = SdkConfig.builder()
    .apiKeyAuthConfig(
        ApiKeyAuthConfig.builder()
            .apiKey("your-api-key")
            .build()
    )
    .build()

val sdk = Sdk(config)

try {
    val user = sdk.usersService.getUser("123")
    println("User: $user")
} catch (e: Exception) {
    println("Error: ${e.message}")
}

Import کردن SDK به صورت local

روش Gradle

ابتدا SDK را در local Maven repository نصب کنید، سپس dependency را به پروژه Gradle خود اضافه کنید.

cd path/to/your-sdk
mvn clean install

dependencies {
    implementation("com.example:your-sdk:1.0.0")
}

روش Maven local repository

<dependency>
    <groupId>com.example</groupId>
    <artifactId>your-sdk</artifactId>
    <version>1.0.0</version>
</dependency>

روش project file path

اگر پروژه parent دارید، SDK را به عنوان module اضافه کنید و بعد به آن dependency بدهید.

<modules>
    <module>../path/to/your-sdk</module>
    <module>your-app</module>
</modules>

انتشار در Maven Central

برای انتشار SDK Kotlin هم مثل Java به حساب Sonatype Central Portal، namespace تاییدشده و GPG key نیاز دارید.

gpg --gen-key
gpg --list-keys
gpg --keyserver keys.openpgp.org --send-keys YOUR_KEY_ID

در pom.xml اطلاعات package، license، developer، SCM و pluginهای source، Javadoc، GPG و Central Publishing را تنظیم کنید. سپس deploy کنید:

mvn clean deploy

برای نسخه‌های بعدی، version را بالا ببرید و دوباره deploy کنید:

mvn versions:set -DnewVersion=1.0.1
mvn versions:commit
mvn clean deploy

Authentication

SDK بر اساس security schemeهای API شما، روش‌های authentication را تولید می‌کند. نمونه‌های رایج:

val config = SdkConfig.builder()
    .apiKeyAuthConfig(
        ApiKeyAuthConfig.builder().apiKey("your-api-key").build()
    )
    .build()

val config = SdkConfig.builder()
    .accessToken("your-bearer-token")
    .build()

sdk.setApiKey("new-api-key")
sdk.setAccessToken("new-token")
sdk.setBasicAuthCredentials("new-username", "new-password")

فراخوانی sync و async

methodهای service معمولا دو نسخه دارند: نسخه sync که همان لحظه خروجی را برمی‌گرداند، و نسخه async که با CompletableFuture کار می‌کند.

val pet = sdk.petService.getPetById(123)
println("Pet: ${pet.name}")

val futurePet = sdk.petService.getPetByIdAsync(123)
futurePet.thenAccept { p ->
    println("Pet: ${p.name}")
}.exceptionally { e ->
    println("Error: ${e.message}")
    null
}

Environment و تنظیمات چندسطحی

sdk.setEnvironment(Environment.PRODUCTION)
sdk.setBaseUrl("https://custom.api.example.com")

در SDKهای Kotlin می‌توانید تنظیمات را در سطح SDK، service، method و request override کنید. تنظیمات request خاص‌ترین سطح است.

val config = SdkConfig.builder()
    .baseUrl("https://api.example.com")
    .timeout(10000)
    .build()

sdk.usersService.setConfig(RequestConfig.builder().timeout(15000L).build())

val user = sdk.usersService.getUser(
    "123",
    RequestConfig.builder().timeout(30000L).build()
)

Error handling

برای خطاهای API، SDK exceptionهایی مثل APIError و exceptionهای typed تولید می‌کند. برای status codeهای خاص می‌توانید switch یا when بنویسید.

try {
    val user = sdk.usersService.getUser("123")
    println(user)
} catch (e: APIError) {
    println("API error: ${e.message}")
    println("Status code: ${e.status}")
    println("Response: ${e.response}")
} catch (e: Exception) {
    println("Unexpected error: ${e.message}")
}

Timeout، retry و validation

val retryConfig = RetryConfig.builder()
    .maxRetries(3)
    .initialDelay(150)
    .maxDelay(5000)
    .backoffFactor(2.0)
    .jitter(50)
    .build()

SDK constraintهای OpenAPI مثل minLength، maxLength، pattern، min، max و uniqueItems را قبل از ارسال request بررسی می‌کند و در صورت خطا ValidationException می‌دهد.

Optional و nullable fieldها

برای fieldهای optional و nullable، SDK تفاوت بین «ارسال نشدن field»، «ارسال null» و «ارسال مقدار واقعی» را حفظ می‌کند. این تفاوت در PATCH و update APIها مهم است.

منابع داخل SDK

• پوشه documentation/ برای مستندات serviceها و modelها.
• پوشه examples/ برای نمونه اجرایی.
• وابستگی‌ها معمولا شامل OkHttp، Jackson و Kotlin runtime هستند.

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