بناء تكامل عميل API

اختر عميلاً

يحتوي المستودع على ثلاثة أسطح عملاء ذات صلة. وهي تتشارك في إعلانات نقطة النهاية، لكن بنائها وأشكال الإدخال وتبعيات وقت التشغيل وقنوات الخطأ تختلف. اختر واحدًا عمدًا واحتفظ بالأمثلة من هذا السطح معًا.

حزمة API عبارة عن مساحة عمل خاصة مع تصدير المصدر. الواردات أدناه مخصصة لهذا monorepo أو التوزيع الذي يوفر تلك الصادرات فعليًا؛ لا تطالب هذه الصفحة بحزمة npm عامة متاحة بشكل منفصل. يمكن للعملاء المستقلين استخدام مستند OpenAPI أو HTTP عادي.

بالنسبة للطلب الأول دون إعداد مكتبة العميل، ابدأ بـ تم التقاط إرشادات HTTP. ويحدد كيف تختلف هيئات النجاح والفشل بين العمليات.

حل الاتصال

استخدم عنوان URL والرمز المميز لحامل التطبيق الذي ينتمي إلى الإطلاق السايدكار الحالي. Tauri يحصل عليهم من خلال get_sidecar_endpoint. تقوم عملية التطوير اليدوي بطباعة المنفذ المخصص لها في حدث جاهز. يجب أن يشير الأصل إلى بوابة السايدكار أو البوابة المصاحبة المقبولة، بدلاً من موقع التوثيق أو أصول Vite.

بعد إعادة تشغيل السايدكار، قم بحل الاتصال مرة أخرى. يمكن أن تؤدي إعادة استخدام المنفذ السابق إلى رفض الاتصال أو معالجة عملية أخرى عن طريق الخطأ. تؤدي إعادة استخدام رمز الإطلاق القديم إلى فشل التفويض. لا تثبت استجابة الصحة العامة الناجحة أنه سيتم قبول الطلب المحمي.

يتم التمييز بين اختيار الحساب وقبول التطبيق وقبول الجهاز والوصول إلى الوكيل الخارجي. الاختياري x-session-token يختار حسابا بعد قبول التطبيق. يقتصر رمز الجسر على نطاق المشروع على نقاط نهاية جسر العمل الخاص به. يعمل رمز الهاتف من خلال قائمة السماح الخاصة بالبوابة. اتبع مرجع المصادقة قبل اختيار الاتصال للتكامل.

وعد SDK

مساحة الاسم المصدرة هي CadCam، ومنشئه هو make. قم بتوفير عنوان URL الأساسي والرؤوس الافتراضية. تستخدم أساليب الإنشاء والحصول أدناه الحقول المسطحة بدلاً من الحقول المتداخلة payload أو params هدف.

import { CadCam } from "@cadcamfun/api/sdk"

const client = CadCam.make({
  baseUrl,
  headers: { Authorization: "Bearer " + token },
})

const projects = await client.projects.list()
const created = await client.projects.create({
  name: "Fixture plate",
  description: "An integration-created project",
})
const detail = await client.projects.get({ id: created.id })
console.log(projects.length, detail.name, detail._count.drawings)

تحل كل مكالمة مع حمولة النجاح الخاصة بنقطة النهاية هذه مباشرةً. projects.list() إرجاع مصفوفة؛ projects.create() إرجاع صف المشروع. لا يوجد عالمي { data, error } المجمع ولا throwOnError خيار المنشئ في SDK هذا. تحتوي بعض حمولات نقاط النهاية نفسها على data أو success لأن هذا هو عقد HTTP الخاص بهم.

يقوم SDK بإعداد عنوان URL من مسار نقطة النهاية وعنوان URL الأساسي الذي تم تكوينه، وترميز معرفات المسار، وإجراء تسلسل لإدخال JSON المعلن، والتحقق من حالة النجاح المعلنة الدقيقة للعملية. ثم يقوم بتوزيع JSON وإرجاع قيمته المكتوبة. لا يطبق وقت تشغيل Promise وحدة فك ترميز مخطط التأثير على كل حمولة يتم إرجاعها؛ لا تتحقق أنواع مخرجات TypeScript من صحة التنفيذ العشوائي للخادم.

أعلن وأخطاء النقل

يتم رفض حالات فشل HTTP المعلنة باستخدام نص الاستجابة الذي تم فك ترميزه. يمكن أن تكون هذه القيمة كائنًا عاديًا مُعلَّمًا بدلاً من مثيل لخطأ JavaScript. تستخدم حالات فشل النقل والبروتوكول أدوات تطوير البرامج (SDK). ClientError.

import { ClientError } from "@cadcamfun/api/sdk"

try {
  await client.projects.create({})
} catch (error) {
  if (error instanceof ClientError) {
    console.error(error.reason, error.message)
  } else if (error && typeof error === "object" && "message" in error) {
    console.error(String(error.message))
  } else {
    console.error("Unrecognized API failure", error)
  }
}

على سبيل المثال، اسم المشروع المفقود هو فشل أعمال HTTP 400 على الرغم من أن نوع إدخال الإنشاء يسمح بالحذف. تختلف إعادة تعيين الاتصال أثناء إنشاء مشروع: فهي تترك العميل غير متأكد مما إذا كانت الكتابة قد اكتملت أم لا. اقرأ حالة المورد قبل تكرار الطفرة. لا يقوم SDK بإضافة بروتوكول عدم القدرة على مستوى التطبيق أو إعادة محاولة كل مكالمة مرفوضة تلقائيًا.

الإلغاء والعناوين

ClientOptions يقبل baseUrlوتنفيذ جلب اختياري والرؤوس الافتراضية. لكل مكالمة RequestOptions يقبل إشارة ورؤوس إضافية. بالنسبة للأساليب التي لا تحتوي على إدخال نقطة النهاية، تكون خيارات الطلب هي الوسيطة الأولى؛ الأساليب مع الإدخال تأخذ خيارات الطلب بعد ذلك.

const controller = new AbortController()
const pending = client.projects.get(
  { id: projectId },
  {
    signal: controller.signal,
    headers: { "x-session-token": accountSessionToken },
  },
)
// Call controller.abort() when the operation is no longer needed.
const project = await pending

يطبق منشئ الطلب الرؤوس الافتراضية، والرؤوس المعلنة لنقطة النهاية، ثم الرؤوس لكل مكالمة. يمكن لقيمة المكالمة الواحدة أن تتجاوز القيمة الافتراضية؛ تجنب استبدال التفويض عن طريق الخطأ عند إضافة حساب أو تتبع الرؤوس. لا تضع بيانات الاعتماد في عناوين URL لنقطة النهاية المنسوخة في السجلات.

الحقن fetch يدعم نقل اختبار قيد التشغيل أو محول يتم التحكم فيه. يجب أن يستمر المحول في احترام رؤوس الطلب، والنص، والإلغاء، وأنواع المحتوى، ودلالات حالة الاستجابة. يقوم تكامل التأثير الخاص بسطح المكتب والنقل الأصلي المثبت بالهاتف بعمل إضافي؛ استبدال جلب تعسفي لا يعيد إنتاج تلك الحدود الأصلية.

عميل التأثير الكامل

ApiClient.layer إنشاء عميل HttpApi الكامل، وجلب النقل، والبرمجيات الوسيطة للحامل. يعرض أساليب نقطة النهاية مع شكل طلب HttpApi الأساسي. تنخفض حمولة الطفرة payload، وتنخفض قيم المسار params.

import { ApiClient } from "@cadcamfun/api"
import { Effect } from "effect"

const createProject = Effect.gen(function* () {
  const api = yield* ApiClient
  return yield* api.projects.create({
    payload: { name: "Fixture plate" },
  })
}).pipe(Effect.provide(ApiClient.layer({ baseUrl, token })))

const project = await Effect.runPromise(createProject)

يشتق هذا العميل من إعلان واجهة برمجة التطبيقات بالكامل وهو خيار لنقاط النهاية المحذوفة من الأهداف التي تم إنشاؤها. فهو يحافظ على قناة الخطأ المكتوبة الخاصة بالتأثير والنقل المدرك للمخطط. ينتمي عمر المورد وانقطاع الدفق وتوفير الطبقة إلى برنامج تأثير الاستدعاء؛ إنشاء تأثير لا ينفذه.

توفر الطبقة القابلة لإعادة الاستخدام رمز التطبيق. يقوم سطح المكتب ببناء طبقته الخاصة apps/desktop/src/app/client.ts لإرفاق حالة جلسة الحساب الاختيارية والنقل المحقون. أعد استخدام هذا التكامل عند العمل داخل سطح المكتب بدلاً من إنشاء اتصال/وقت تشغيل ثانٍ لكل مكون.

محولات التأثير التي تم إنشاؤها

يقوم عميل Effect الذي تم إنشاؤه باستيراد المخططات الحقيقية وتكييف الأساليب في الحقول المسطحة. إنه CadCam.make تقوم بإرجاع التأثير الذي ينشئ العميل المُكيَّف. لا يوفر نقل الجلب الخاص به أو طبقة ترخيص التطبيق، لذلك يجب على المتصل توفير الخدمات والبرامج الوسيطة المقابلة.

يقوم محول الخطأ الذي تم إنشاؤه بتعيين فشل النقل/المخطط/SSE في علامة ClientError مع الاحتفاظ بفشل المجال المعلن. فئة الخطأ هذه منفصلة عن فئة خطأ JavaScript الخاصة بـ Promise SDK والتي تحتوي على reason خيط. تشابه الأسماء لا يجعل التعامل معها قابلاً للتبديل.

اجعل أمثلة الإدخال واضحة. يتم استخدام نماذج الوعد والتأثير المولد projects.get({ id }); يستخدم نموذج العقد الخام projects.get({ params: { id } }). تجنب تمرير كائن إدخال من سطح إلى آخر من خلال تأكيد النوع غير المحدد.

جاري

تقوم عمليات وعد SSE بإرجاع العناصر التكرارية غير المتزامنة. يحدث إعداد الشبكة عند بدء التكرار. يتحقق وقت التشغيل من حالة النجاح ونوع محتوى دفق الحدث، ويقرأ بيانات UTF-8 المتزايدة، ويضبط حدود الإطارات، ويفك تشفير إطارات البيانات بواسطة JSON. يفشل الإطار المشوه في التكرار؛ يتم تشغيل تنظيف القارئ عند انتهاء التكرار أو الخروج منه.

حارس وقت التشغيل هو 16 * 1024 * 1024 وحدات سلسلة جافا سكريبت المخزنة مؤقتًا. فهو يحد من التراكم قبل حدود الإطار؛ ولا يعد هذا وعدًا بأن كل حمولة عشوائية تبلغ 16 ميغابايت مفيدة أو صالحة لمخططات أحداث التطبيق.

استهلك أحداث الذكاء الاصطناعي وفقًا لتمييزاتها واحتفظ بمعرف الجلسة. النقل المنتهي ليس دليلاً على حدث محادثة طرفية. يستخدم تدفق الذكاء الاصطناعي والانتعاش لقائمة الانتظار، والإجهاض، والإذن، والسؤال، وسلوك استرداد الحالة. EventSource ليس بديلاً مباشرًا لطلب POST برؤوس التفويض ونص JSON.

التغطية والتجديد

يحتوي المولد على قوائم حذف واضحة للأشكال التي لا يمكنه تمثيلها. تتضمن عمليات الإغفال المشتركة تحميلات الملفات الشخصية/المكونات الإضافية متعددة الأجزاء، وإنشاء MCP بمخططات نجاح متعددة، وأسماء الإدخال المتضاربة، وخدمة المكونات الإضافية مع رؤوس الاستجابة في التدفق الخاص بها. تتضمن عمليات حذف الوعد الإضافية خطافات الويب الموقعة الأولية، وأداة تمهيد JavaScript الإضافية، والتنزيل الثنائي، وطلبات المولدات ذات النموذج الحر.

اقرأ القوائم الحالية بالضبط في packages/api/scripts/generate-clients.ts و نظرة عامة على واجهة برمجة التطبيقات. لا تثبت الطريقة التي تم إنشاؤها غائبة أن نقطة نهاية الخادم غير متوفرة. استخدم عميل العقد الكامل أو النقل الخام المناسب لهذه العملية.

bun run generate
bun run generate:check
bun run --filter @cadcamfun/web generate:api-reference
bun run --filter @cadcamfun/web check:api-reference

يعد تجديد العميل وتجديد الوثائق مخرجات منفصلة من نفس العقد. احتفظ بكلاهما محدثًا بعد تغييرات نقطة النهاية. لا تقم بتحرير نصوص الطريقة التي تم إنشاؤها لتغيير متطلبات إدخال الخادم.

تتم كتابة التعليمات البرمجية التي تم إنشاؤها إلى packages/api/src/client/generated و packages/api/src/sdk/generated. لا تقم بتحرير هذه الملفات يدوياً؛ تغيير العقد والتجديد.

التحقق من التكامل

تم ممارسة سلوك الإنشاء/القراءة/النتيجة الواضحة لـ Promise والفشل المُعلن الموضح هنا مقابل مكدس معالج الجانب الحقيقي باستخدام قاعدة بيانات مُرحَّلة يمكن التخلص منها. تحتوي إرشادات HTTP على الاستجابات المرصودة المقابلة. كرر عمليات الفحص المركزة عند تغيير المولد أو المصادقة أو مخططات نقطة النهاية.

For an integration acceptance check, verify public health; a protected request without a token; the same request with the current token; a valid create/read cycle; a declared validation failure; a cancelled request; and a stream whose terminal state is checked. Use a disposable project and never infer successful persistence from a frontend fixture alone.

مصادر التنفيذ هي packages/api/src/sdk/generated/client.ts، إنه client-error.ts, packages/api/src/client.ts, packages/api/src/client/generated، و packages/httpapi-codegen/src/index.ts. يقوم المولد والمخرجات الملتزمة معًا بتحديد سلوك العميل الفعلي.

مرجع خيارات SDK الوعد

عندما يكون الجسم موجودا ولا content-type تم تعيين الرأس، ومجموعات SDK application/json ويتسلسل مع JSON.stringify. يتم دائمًا تمرير معلمات المسار encodeURIComponent، لذلك مفتاح مثل docs.walkthrough.units أو واحدة تحتوي على / يبقى قطعة واحدة.

أسباب خطأ العميل

رسالة أ ClientError هو السبب متبوعًا برسالة السبب (على سبيل المثال Transport: fetch failed) ، لذلك التسجيل error.message وحده هو التشخيص بالفعل.

import { CadCam, ClientError } from "@cadcamfun/api/sdk"

async function withRetry<T>(read: () => Promise<T>, attempts = 3): Promise<T> {
  for (let attempt = 1; ; attempt++) {
    try {
      return await read()
    } catch (error) {
      const transient = error instanceof ClientError && error.reason === "Transport"
      if (!transient || attempt >= attempts) throw error
      await new Promise((resolve) => setTimeout(resolve, 250 * 2 ** attempt))
    }
  }
}

const projects = await withRetry(() => client.projects.list())

استهلاك دفق مع SDK

const controller = new AbortController()
const events = client.ai.chatStream(
  { message: "Pocket the 40 x 30 rectangle, 3 mm deep", projectId },
  { signal: controller.signal },
)

for await (const event of events) {
  switch (event.type) {
    case "delta": render(event); break
    case "permission_request": askUser(event); break
    case "done": finish(event); break
    case "error": showError(event); break
  }
}

يقوم المكرّر بتوزيع كل كتلة SSE: فهو ينضم إلى data: خطوط الكتلة، وتوزع JSON وتنتج عنه. التعليقات والكتل بدون data: يتم تخطيها. ترك الحلقة مبكرا (breakأو استثناء أو إحباط) يلغي القارئ ويحرر الاتصال. الحدث type القيم هي تلك المدرجة في دليل البث المساعد؛ تحقق من الناتج AiChatStreamOutput اكتب للاتحاد الدقيق.

مثال: التفضيلات من خلال SDK

const key = "docs.walkthrough.units"

try {
  await client.kv.get({ key })
} catch (error) {
  if ((error as { _tag?: string })._tag !== "NotFound") throw error   // first run: 404
}

const saved = await client.kv.set({ key, value: { units: "mm" } })
// saved: { key, value: { units: "mm" }, updatedAt: "2026-…" }

const { entries } = await client.kv.list({ prefix: "docs." })
await client.kv.remove({ key })   // { message: "…" }

تقتصر المفاتيح على 512 من الأحرف ويجب أن تحتوي على نص بدون مسافة بيضاء؛ يجب أن تكون القيم متوافقة مع JSON (بدون دورات أو وظائف أو أرقام غير محدودة).

في 3د