TypeScript Academy · درس

استراتيجية حزمة الأنواع المشتركة

أنشئوا حزمة أنواع مخصّصة تُستخدم في أنحاء المستودع متعدد الحزم

استراتيجية حزمة الأنواع المشتركة درس مجاني في TypeScript Academy على CoddyKit. هذا هو الدرس 3 من أصل 4. يمكنك قراءة الدرس كاملاً أدناه مجاناً — ثم تمرن عليه مباشرة في المتصفح باستخدام محرر أكواد مدمج ومدرس ذكاء اصطناعي متاح 24/7. هذا الدرس جزء من مسار التعلم في TypeScript Academy، وتقدمك يتزامن عبر الويب وتطبيق CoddyKit. تتضمن دورة TypeScript Academy 4 دروس في المجموع.

لماذا نستخدم حزمة أنواع مشتركة؟

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

// packages/types/src/index.ts
export interface User { id: string; name: string; email: string; }
export interface ApiResponse<T> { data: T; error?: string; }

بنية الحزمة

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

packages/types/
├── src/
│   ├── index.ts      # re-exports all
│   ├── user.ts
│   ├── product.ts
│   └── api.ts
├── tsconfig.json
└── package.json

tsconfig لحزمة الأنواع

فعّل emitDeclarationOnly حتى لا يتم إخراج JavaScript — بل ملفات .d.ts فقط التي تشير إليها الحزم المستهلكة.

{
  "compilerOptions": {
    "composite": true,
    "declaration": true,
    "emitDeclarationOnly": true,
    "outDir": "./dist",
    "rootDir": "./src"
  }
}

استهلاك حزمة الأنواع

أشر إلى حزمة الأنواع في كل من API وتطبيق الويب، واستورد الأنواع باستخدام import type لتجنب الحمل الزائد وقت التشغيل.

import type { User, ApiResponse } from "@myapp/types";

async function getUser(id: string): Promise<ApiResponse<User>> {
  // ...
}

الحفاظ على قابلية تسلسل الأنواع

ينبغي أن تتضمن الأنواع المشتركة بين العميل والخادم قيمًا قابلة للتسلسل باستخدام JSON فقط. تجنب كائنات Date — واستخدم string (بصيغة ISO) بدلًا منها.

// Good: serialization-safe
interface Event { id: string; createdAt: string; /* ISO date */ }
// Bad: Date is not JSON-serializable
interface Event { id: string; createdAt: Date; }

إدارة إصدار حزمة الأنواع

أصدر حزمة الأنواع وفق semver. ويُعد التغيير الكاسر للتوافق، مثل إزالة حقل أو إعادة تسميته، رفعًا للإصدار الرئيسي.

# Breaking change: major bump
npm version major
# Adding optional fields: minor bump
npm version minor

إنشاء الأنواع من OpenAPI

أتمت حزمة الأنواع بإنشائها من مواصفة OpenAPI باستخدام openapi-typescript. يضمن ذلك تطابق الأنواع دائمًا مع الواجهة الخلفية.

npx openapi-typescript ./api/openapi.yaml -o ./packages/types/src/api.ts

استخدام Zod للأنواع وقت التشغيل ووقت الترجمة

عرّف الأنواع باستخدام مخططات Zod واستنتج منها أنواع TypeScript. يأتي كل من التحقق وقت التشغيل والأنواع الساكنة من المصدر نفسه.

import { z } from "zod";
export const UserSchema = z.object({ id: z.string(), name: z.string() });
export type User = z.infer<typeof UserSchema>;

تجنب التبعيات الدائرية

ينبغي ألا تستورد حزمة الأنواع من حزم مساحة العمل الأخرى لمنع سلاسل التبعيات الدائرية. اجعلها عقدة طرفية في مخطط التبعيات.

// types/ should not import from ui/ or api/
// ui/ and api/ both import from types/

اختبار صحة الأنواع

استخدم tsd لكتابة تأكيدات على مستوى الأنواع تتحقق من توافق الأنواع المشتركة مع التوقعات.

import { expectType } from "tsd";
import type { User } from "@myapp/types";
expectType<User>({ id: "1", name: "Alice", email: "a@b.com" });

مراجعة: استراتيجية الأنواع المشتركة

تزيل حزمة الأنواع المشتركة الاختلافات في API: أخرج الإعلانات فقط، وحافظ على قابلية تسلسل الأنواع باستخدام JSON، وأدر الإصدارات وفق semver، وأنشئها اختياريًا تلقائيًا من OpenAPI، واختبرها باستخدام tsd.

تحقق سريع

لماذا ينبغي أن تستخدم أنواع API المشتركة string بدلًا من Date؟

ما تعلمته

تمثل حزمة الأنواع المشتركة مصدرًا واحدًا للحقيقة لعقود API. اجعلها مقتصرة على الإعلانات، وآمنة مع JSON، ومدارة الإصدارات وفق semver، وأنشئها اختياريًا من OpenAPI للقضاء على الاختلافات بين الواجهة الأمامية والخلفية.

الأسئلة الشائعة

هل درس «استراتيجية حزمة الأنواع المشتركة» مجاني؟

نعم — نص درس «استراتيجية حزمة الأنواع المشتركة» كامل متاح مجاناً هنا على الويب. لتمرينه بشكل تفاعلي (محرر أكواد مدمج ومدرس ذكاء اصطناعي متاح 24/7) وفتح باقي دورة TypeScript Academy، انتقل إلى CoddyKit PRO. تتضمن دورة TypeScript Academy 4 دروس في المجموع.

ماذا ستتعلم في «استراتيجية حزمة الأنواع المشتركة»؟

أنشئوا حزمة أنواع مخصّصة تُستخدم في أنحاء المستودع متعدد الحزم تتمرن على TypeScript Academy مع أكواد عملية تشغلها مباشرة في المتصفح، ومدرس ذكاء اصطناعي متاح 24/7 يجيب على أسئلتك أثناء عملك.

هل أحتاج إلى خبرة سابقة لأبدأ TypeScript Academy؟

لا تُشترط خبرة سابقة. TypeScript Academy على CoddyKit منظم للمبتدئين حتى المتقدمين، لذا يمكنك البدء من هنا أو من البداية والتقدم بسرعتك الخاصة. هذا هو الدرس 3 من أصل 4.

كم من الوقت يستغرق درس «استراتيجية حزمة الأنواع المشتركة»؟

معظم دروس CoddyKit تستغرق حوالي 5–10 دقائق. كل منها موجز وتفاعلي، لذا تحرز تقدماً مستمراً وتستأنف من حيث توقفت عبر الويب والتطبيق.

هل يمكنني كتابة وتشغيل أكواد في درس TypeScript Academy هذا؟

نعم. كل درس في TypeScript Academy يتضمن محرر أكواد مدمج، لذا تكتب وتشغل أكواداً حقيقية مباشرة في متصفحك وتحصل على تعليقات فورية من الذكاء الاصطناعي — بدون إعداد محلي.

جميع الدروس في هذه الدورة

شرح مراجع مشاريع TypeScript
مساحات عمل pnpm مع TypeScript
استراتيجية حزمة الأنواع المشتركة
البنيات التزايدية والتخزين المؤقت في المستودعات متعددة الحزم

← العودة إلى TypeScript Academy