أنواع استجابات API

API Response Types

مفهوم ~19 دقيقة

أنواع استجابات API — API Response Types

استجابة API قد تنجح أو تفشل. لا تجعل النوع يقول User فقط إذا كانت الدالة قد تفشل. يمكنك تمثيل ذلك بـ union: { ok: true; data: User } | { ok: false; error: string }. هذا يجعل التعامل مع الفشل إلزامياً في الكود.

هذا النمط مفيد لأنه لا يعتمد على exceptions في كل مكان. القارئ يرى من النوع أن النتيجة لها حالتان. ثم يستخدم if (response.ok) لتضييق النوع.

مثال عملي

index.ts

type ApiResult<T> =
  | { ok: true; data: T }
  | { ok: false; error: string };

type User = { name: string };

function handleUser(result: ApiResult<User>): string {
  if (result.ok) {
    return result.data.name;
  }

  return `error: ${result.error}`;
}

console.log(handleUser({ ok: true, data: { name: "Sara" } }));

Output:

داخل فرع result.ok, يعرف TypeScript أن data موجودة.

لا تكذب على API

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

تحدي — Challenge

type Result = { ok: true; value: string } | { ok: false; error: string };

const result: Result = { ok: false, error: "failed" };

if (result.ok) {
  console.log(result.value);
} else {
  // اطبع error: <الرسالة> — Print error: <message>
}