فهرست مستندات

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

به‌روزرسانی ۱۵ تیر ۱۴۰۵ ۵ دقیقه مطالعه Postman

فهرست مطالب

این راهنما روش استفاده از SDKهای Java تولیدشده با Postman SDK Generator را توضیح می‌دهد: ساختار SDK، اجرای example، import با Maven یا Gradle، انتشار در Maven Central، authentication، فراخوانی sync/async، تنظیمات چندسطحی، error handling، validation و optional/nullable fieldها.

ساختار SDK Java

[SdkName].java: client اصلی SDK که با [SdkName]Config ساخته می‌شود.
services/: کلاس‌های service با methodهای synchronous و asynchronous.
models/: modelهای داده، POJOها با Lombok builder، enumها و exceptionهای typed.
config/: کلاس‌های تنظیمات authentication، retry و client.
pom.xml: وابستگی‌هایی مثل OkHttp، Jackson و Lombok.

اجرای نمونه Java

هر SDK تولیدشده یک پوشه examples/ دارد که initialization، config builder، فراخوانی sync، model builder و exception handling را نشان می‌دهد.

cd examples
./run.sh

یا به صورت دستی:

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

import com.example.sdk.Sdk;
import com.example.sdk.config.SdkConfig;
import com.example.sdk.config.ApiKeyAuthConfig;
import com.example.sdk.models.User;

public class Main {
    public static void main(String[] args) {
        SdkConfig config = SdkConfig.builder()
            .apiKeyAuthConfig(
                ApiKeyAuthConfig.builder()
                    .apiKey("your-api-key")
                    .build()
            )
            .build();

        Sdk sdk = new Sdk(config);

        try {
            User user = sdk.usersService.getUser("123");
            System.out.println("User: " + user);
        } catch (Exception e) {
            System.err.println("Error: " + e.getMessage());
        }
    }
}

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

روش Maven local repository

cd path/to/your-sdk
mvn clean install

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

import com.example.sdk.Sdk;
import com.example.sdk.config.SdkConfig;

SdkConfig config = SdkConfig.builder().build();
Sdk sdk = new Sdk(config);

روش project file path

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

<dependency>
    <groupId>com.example</groupId>
    <artifactId>your-sdk</artifactId>
    <version>${project.version}</version>
</dependency>

روش Gradle

cd path/to/your-sdk
mvn clean install

dependencies {
    implementation group: 'com.example', name: 'your-sdk', version: '1.0.0'
}

اگر می‌خواهید SDK را به صورت JAR به Gradle بدهید، ابتدا fat JAR بسازید:

cd path/to/your-sdk
mvn compile assembly:single

dependencies {
    implementation files('../path/to/your-sdk/target/your-sdk-1.0.0-jar-with-dependencies.jar')
}

انتشار SDK در Maven Central

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

راه‌اندازی اولیه

در central.sonatype.com حساب بسازید و namespace یا group ID خود، مثلا com.example، را تایید کنید.
GPG key بسازید و public key را به keyserver بفرستید.

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

سپس در ~/.m2/settings.xml tokenهای Central Portal و passphrase کلید GPG را تنظیم کنید.

<settings>
  <servers>
    <server>
      <id>central</id>
      <username>your-central-portal-token-username</username>
      <password>your-central-portal-token-password</password>
    </server>
  </servers>
</settings>

تنظیم pom.xml

در pom.xml اطلاعات اصلی package، license، developer، SCM و pluginهای لازم را قرار دهید. حداقل موارد مهم عبارت‌اند از:

<groupId>com.example</groupId>
<artifactId>your-sdk</artifactId>
<version>1.0.0</version>
<packaging>jar</packaging>
<name>Your SDK</name>
<description>SDK for Your API</description>

برای انتشار استاندارد، source JAR، Javadoc JAR، امضای GPG و Central Publishing Maven Plugin را هم در build اضافه کنید.

Deploy و verify

mvn clean deploy

اگر autoPublish فعال باشد، artifactها بعد از validation منتشر می‌شوند. بعد از deploy مسیر Maven را بررسی کنید؛ مثلا:

https://repo1.maven.org/maven2/com/example/your-sdk/

معمولا بعد از تایید، انتشار تا حدود ۳۰ دقیقه طول می‌کشد.

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

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

بهترین کارها برای Maven Central

از semantic versioning استفاده کنید.
همه artifactها را با GPG امضا کنید.
source و Javadoc JAR را منتشر کنید.
مستندات کامل ارائه دهید.
releaseها را در Git tag کنید.
برای انتشار خودکار از Maven Release Plugin یا CI/CD استفاده کنید.

Authentication

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

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

Sdk sdk = new Sdk(config);

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

SdkConfig config = SdkConfig.builder()
    .basicAuthConfig(
        BasicAuthConfig.builder()
            .username("your-username")
            .password("your-password")
            .build()
    )
    .build();

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

فراخوانی synchronous و asynchronous

هر service method یک نسخه sync و یک نسخه async دارد. نسخه sync مستقیما type خروجی را برمی‌گرداند و نسخه async، CompletableFuture<T> می‌دهد.

Pet pet = sdk.petService.getPetById(123);
System.out.println("Pet: " + pet.getName());

CompletableFuture<Pet> futurePet = sdk.petService.getPetByIdAsync(123);

futurePet
    .thenAccept(p -> System.out.println("Pet: " + p.getName()))
    .exceptionally(e -> {
        System.err.println("Error: " + e.getMessage());
        return null;
    });

Pet petFromFuture = futurePet.get();

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

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

Java از چهار سطح configuration پشتیبانی می‌کند: SDK، service، method و request. سطح request خاص‌ترین سطح است و تنظیمات قبلی را override می‌کند.

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

Sdk sdk = new Sdk(config);

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

sdk.usersService.setGetUserConfig(
    RequestConfig.builder()
        .baseUrl("https://legacy-api.example.com")
        .build()
);

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

Error handling

برای خطاهای API، SDK exceptionهای سفارشی ایجاد می‌کند که message، status code و response body را دارند.

import com.example.sdk.exceptions.APIError;

try {
    User user = sdk.usersService.getUser("123");
    System.out.println(user);
} catch (APIError e) {
    System.err.println("API error: " + e.getMessage());
    System.err.println("Status code: " + e.getStatus());
    System.err.println("Response: " + e.getResponse());
} catch (Exception e) {
    System.err.println("Unexpected error: " + e.getMessage());
}

try {
    sdk.usersService.deleteUser("123");
} catch (APIError e) {
    switch (e.getStatus()) {
        case 404:
            System.out.println("User not found");
            break;
        case 403:
            System.out.println("Permission denied");
            break;
        default:
            System.out.println("API error: " + e.getMessage());
    }
}

اگر specification برای error responseها model تعریف کرده باشد، SDK exceptionهای typed مثل NotFoundErrorException می‌سازد. برای دسترسی به fieldهای مدل خطا از getError() استفاده کنید.

Timeout و retry

SdkConfig config = SdkConfig.builder()
    .timeout(10000)
    .build();

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

Validation

SDK validatorهایی تولید می‌کند که constraintهای OpenAPI مثل minLength، maxLength، pattern، min، max و uniqueItems را در runtime بررسی می‌کنند. اگر validation شکست بخورد، ValidationException با لیست Violationها پرتاب می‌شود.

try {
    sdk.usersService.createUser(user);
} catch (ValidationException e) {
    System.err.println(e.getMessage());
    for (Violation violation : e.getViolations()) {
        System.err.println(violation.getPath() + ": " + violation.getMessage());
    }
} catch (APIError e) {
    System.err.println("API error: " + e.getMessage());
}

String: minLength، maxLength، pattern.
Numeric: min و max.
List/array: minItems، maxItems، uniqueItems.
Required fields: بر اساس specification خودکار validation می‌شوند.

Optional و nullable fieldها

SDK برای fieldهای optional از wrapperهایی مثل JsonNullable<T> استفاده می‌کند تا تفاوت بین undefined، null و مقدار واقعی روشن باشد. حذف یک field با ارسال explicit null یکی نیست.

ModelWithOptionalNullableDefaultValues model =
    ModelWithOptionalNullableDefaultValues.builder()
        .requiredString("requiredString")
        .requiredInteger(8L)
        .requiredNullableString("not null")
        .requiredNullableInteger(null)
        .optionalString("optionalString")
        .optionalNullableInteger(null)
        .build();

اگر fieldهای optional را اصلا set نکنید، هنگام serialization از JSON حذف می‌شوند. اگر field optional nullable را روی null بگذارید، مقدار null به API ارسال می‌شود.

منابع داخل SDK

پوشه documentation/ برای مستندات SDK.
Javadoc با فرمان mvn javadoc:javadoc.
پوشه examples/ برای نمونه اجرایی.
وابستگی‌ها: OkHttp برای HTTP، Jackson برای JSON و jackson-databind-nullable برای optional nullable، و Lombok برای کم کردن boilerplate.

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