دسته‌ها را مشاهده کنید

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

مدت زمان مطالعه: : 7 دقیقه

این راهنما روش استفاده از 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 تاییدشده نیاز دارید.

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

  1. در central.sonatype.com حساب بسازید و namespace یا group ID خود، مثلا com.example، را تایید کنید.
  2. 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، بازنویسی و ساده‌سازی‌شده برای کاربران فارسی‌زبان.

به‌روزرسانی شده در 1405-04-15

احساسات شما چیست؟

  • خوشحال
  • عادی
  • ناراحت

دیدگاهتان را بنویسید