تولید SDK با کد سفارشی در Postman CLI

تولید SDK و حفظ کدهای سفارشی

با Postman CLI می‌توانید از روی Collection یا API specification یک SDK بسازید، بعد روی فایل‌های تولیدشده تغییرات خودتان را اضافه کنید و در تولیدهای بعدی آن تغییرات را حفظ کنید.

این قابلیت برای زمانی مفید است که می‌خواهید متد کمکی، logging، validation، README اختصاصی یا منطق مخصوص برنامه خودتان را به SDK اضافه کنید، اما همچنان SDK با تغییرات API به‌روز بماند.

SDK Generator از زبان‌های TypeScript، Python، Java، Kotlin، C#، Go، PHP، Ruby و Rust پشتیبانی می‌کند. نمونه‌های این راهنما عمومی هستند و باید با قواعد زبان انتخابی شما تطبیق داده شوند.

مرحله ۱: تولید SDK اولیه

برای ساخت SDK، دستور postman sdk generate را با شناسه Collection یا specification اجرا کنید. مقدار <language> را با زبان مورد نظر جایگزین کنید؛ مثل typescript، python، java، kotlin، csharp، go، php، ruby یا rust.

postman sdk generate 12345678-abcd-1234-1234-123456789abc -l <language>

مثال برای TypeScript:

postman sdk generate 12345678-abcd-1234-1234-123456789abc -l typescript

CLI مراحل build را نشان می‌دهد: تشخیص نوع شناسه، ساخت build، وضعیت پردازش، موفقیت یا خطا، و در پایان دانلود SDK.

Identifying ID type (collection or specification)...
Identified as: collection
Starting SDK generation...
Build ID: 7836
Status: SUCCESS

Downloading SDKs...
✓ typescript: sdks/typescript
✓ All SDKs downloaded successfully!

اگر در Collection، request بدون URL داشته باشید، آن endpoint وارد SDK نمی‌شود. برای اضافه‌شدن آن، ابتدا URL را در Collection کامل کنید و سپس SDK را دوباره تولید کنید.

ساختار خروجی SDK

SDK تولیدشده معمولا در مسیر ./sdks/<language>/ ذخیره می‌شود و شامل بخش‌هایی مثل این‌هاست:

• .sdk-gen/: metadata داخلی تولید SDK.
• documentation/: مستندات API تولیدشده.
• examples/: نمونه‌های استفاده.
• فایل‌های dependency، مثل requirements.txt یا فایل‌های package.
• فایل‌های build و scriptها.
• کدهای اصلی SDK، معمولا در service moduleها.
• فایل‌های configuration، مثل .env.example.

مرحله ۲: افزودن کد سفارشی

بعد از تولید اولیه، می‌توانید فایل‌های SDK را ویرایش کنید. وقتی بعدا همان SDK را دوباره تولید کنید، CLI تغییرات محلی شما را تشخیص می‌دهد و تلاش می‌کند آن‌ها را با خروجی جدید ادغام کند.

افزودن متد logging

مثلا می‌توانید در یک service مثل PaymentService متد کمکی اضافه کنید:

// Add a custom logging method to the class
_customLog(input) {
  console.log(input);
}

بعد آن را داخل متدهای همان کلاس استفاده کنید:

setAddCreditCardForUserConfig(config) {
  this._customLog('hello world');
  this.addCreditCardForUserConfig = config;
  return this;
}

سفارشی‌سازی README

می‌توانید فایل README.md را ویرایش کنید و مواردی مثل لوگوی شرکت، دستور نصب داخلی، توضیح احراز هویت، لینک‌های پشتیبانی یا مثال‌های اختصاصی را اضافه کنید. این تغییرات در تولیدهای بعدی حفظ می‌شوند.

تبدیل داده و متدهای کمکی

می‌توانید utility methodهایی اضافه کنید که پاسخ API را به ساختار ساده‌تر و مناسب‌تر برای برنامه شما تبدیل کنند. نمونه TypeScript:

interface PaymentSummary {
  id: string;
  amount: string;
  status: string;
  createdAt: Date;
  isCompleted: boolean;
  displayName: string;
}

class PaymentService {
  transformPaymentData(rawPayment: any): PaymentSummary {
    return {
      id: rawPayment.payment_id,
      amount: this.formatCurrency(rawPayment.amount_units),
      status: rawPayment.status.toUpperCase(),
      createdAt: new Date(rawPayment.created_timestamp),
      isCompleted: rawPayment.status === 'completed',
      displayName: `Payment ${rawPayment.payment_id.slice(-8)}`
    };
  }

  formatCurrency(units: number): string {
    return new Intl.NumberFormat('en-US', {
      style: 'currency',
      currency: 'USD'
    }).format(units / 100);
  }
}

این نوع کد باعث می‌شود خروجی خام API به شکل قابل استفاده‌تری در برنامه مصرف شود.

افزودن validation و منطق کسب‌وکار

می‌توانید قبل از اجرای متدهای SDK، قوانین داخلی برنامه را بررسی کنید. نمونه ساده:

validatePaymentAmount(amount: number, currency: string = 'USD') {
  const errors: string[] = [];

  if (amount <= 0) {
    errors.push('Payment amount must be greater than zero');
  }

  if (currency === 'USD' && amount >= 1000000) {
    errors.push('USD payments cannot exceed $10,000.00');
  }

  return {
    isValid: errors.length === 0,
    errors
  };
}

اگر audit logging اضافه می‌کنید، اطلاعات حساس مثل API key، payment token، شناسه کامل مشتری یا داده شخصی را log نکنید. در محیط production بهتر است این داده‌ها حذف یا mask شوند.

مرحله ۳: تولید دوباره SDK با حفظ تغییرات

وقتی دوباره postman sdk generate را اجرا کنید، CLI فایل‌های تغییرکرده را تشخیص می‌دهد و برای merge استفاده می‌کند.

User edits detected for: typescript
Uploading modified files for 3-way merge...
  typescript: 1 modified file(s)
    + src/services/payment/payment-service.ts
Creating SDK build...
✓ Build created successfully
Status: SUCCESS

اگر پوشه خروجی از قبل وجود داشته باشد، CLI قبل از overwrite سوال می‌پرسد. بعد از تایید، SDK جدید دانلود می‌شود و تغییرات سفارشی شما داخل آن ادغام می‌شود.

مرحله ۴: حل conflictها

اگر هم شما و هم generator یک بخش مشترک از فایل را تغییر داده باشید، conflict ایجاد می‌شود. با strategy پیش‌فرض mark، CLI علامت‌های conflict را داخل فایل می‌گذارد:

<<<<<<< user
// Your version of the code
export function getPet(id: string): Pet {
    return this.cache.get(id) ?? this.fetchPet(id);
}
=======
// Generator's version of the code
export function getPet(id: string): Promise<Pet> {
    return this.httpClient.get(`/pets/${id}`);
}
>>>>>>> generated

در این حالت فایل را باز کنید، نسخه درست را بسازید، markerها را حذف کنید و فایل را ذخیره کنید.

تغییرات چطور تشخیص داده می‌شوند؟

در ریشه هر SDK یک فایل .manifest.json وجود دارد. وقتی change tracking فعال باشد، این فایل hash هر فایل تولیدشده را نگه می‌دارد.

{
  "sdkVersion": "1.0.4",
  "files": ["src/index.ts", "package.json"],
  "fileHashes": {
    "src/index.ts": "a1b2c3d4...",
    "package.json": "c9d0e1f2..."
  }
}

در تولید بعدی، CLI hash فعلی فایل‌ها را با manifest مقایسه می‌کند. اگر hash تغییر کرده باشد، فایل به عنوان ویرایش‌شده در نظر گرفته می‌شود. فایل‌های جدید، فایل‌های حذف‌شده و metadata لازم هم برای merge ارسال می‌شوند.

پوشه‌هایی مثل node_modules، vendor، .venv، dist، build، target، __pycache__، .gradle، .sdk-gen و .git در change detection نادیده گرفته می‌شوند.

تنظیمات change tracking

بخش customCode در فایل تنظیمات SDK رفتار change tracking و merge را کنترل می‌کند:

{
  "sdk": {
    "customCode": {
      "trackChanges": true,
      "conflictStrategy": "mark",
      "noMerge": false
    }
  }
}

اولویت تنظیمات از بالا به پایین این است:

• فلگ‌های CLI، مثل --no-track-changes یا --conflict-strategy ours.
• مقادیر customCode در فایل پیکربندی.

اگر --no-track-changes را اجرا کنید، generator تولید تمیز انجام می‌دهد و برای حفظ تغییرات شما merge انجام نمی‌شود. اگر --no-merge یا noMerge: true را استفاده کنید، فرایند merge رد می‌شود.

محدودیت‌ها

• change tracking به پشتیبانی generator از نوشتن fileHashes در .manifest.json نیاز دارد.
• merge سه‌طرفه به build artifact قبلی در cloud نیاز دارد. اگر artifact قبلی پاک شده باشد، تغییرات سفارشی فقط روی خروجی جدید overlay می‌شوند.
• فایل‌های binary هنگام بررسی conflict اسکن نمی‌شوند.

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