Blog

بدء استخدام Bun API

Mark Ponomarev

Mark Ponomarev

4 مايو 2025

بدء استخدام Bun API

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

💡
هل تريد أداة اختبار واجهات برمجة تطبيقات (API) رائعة تولّد توثيق API جميل؟

هل تريد منصة متكاملة وشاملة لفريق المطورين لديك للعمل معًا بأقصى إنتاجية؟

Apidog يلبي جميع متطلباتك، ويستبدل Postman بسعر أقل بكثير!
button

ما هو Bun؟

في جوهره، تم بناء Bun حول محرك تشغيل JavaScript عالي الأداء. على عكس Node.js، الذي يستخدم محرك V8 من Google، يستخدم Bun محرك JavaScriptCore (JSC) من Apple، وهو المحرك الذي يدعم Safari. هذا الاختيار، جنبًا إلى جنب مع تنفيذ Bun بلغة البرمجة Zig منخفضة المستوى، يساهم بشكل كبير في سرعته الملحوظة. غالبًا ما تُقاس أوقات بدء تشغيل تطبيقات Bun لتكون أسرع بكثير من تطبيقات Node.js المكافئة، أحيانًا بعامل أربعة أو أكثر. تمتد ميزة السرعة هذه إلى ما هو أبعد من مجرد البدء؛ فقد تم تحسين تطبيقات Bun الداخلية لواجهات برمجة التطبيقات المختلفة لتحقيق أقصى إنتاجية وأقل استخدام للذاكرة.

لكن طموح Bun يمتد إلى ما هو أبعد من مجرد كونه بيئة تشغيل أسرع. يهدف إلى أن يكون مجموعة أدوات شاملة، تعالج احتياجات المطورين الشائعة مباشرة:

  1. الأدوات المدمجة: يعمل أمر bun نفسه كنقطة دخول للعديد من الوظائف. يقوم bun run بتنفيذ السكريبتات المحددة في package.json، ويدير bun install التبعيات (غالبًا أسرع بكثير من npm أو yarn)، ويقوم bun test بتشغيل الاختبارات باستخدام واجهة برمجة تطبيقات متوافقة مع Jest، ويقوم bun build بتجميع الكود للإنتاج، ويقوم bunx بتنفيذ الحزم دون تثبيتها صراحةً. هذا التكامل يبسط سير العمل عن طريق تقليل عدد أدوات التطوير المميزة المطلوبة.
  2. دعم TypeScript وJSX الأصلي: إحدى الميزات البارزة في Bun هي دعمه الجاهز لملفات TypeScript (.ts، .tsx) وJSX (.jsx). يتضمن Bun مُحَوِّلًا مدمجًا عالي التحسين يتعامل مع أنواع الملفات هذه بسلاسة أثناء التنفيذ أو التجميع. هذا يلغي الحاجة إلى خطوات تجميع منفصلة تتضمن tsc أو Babel للعديد من سيناريوهات التطوير الشائعة، مما يبسط عملية الإعداد.
  3. توافق نظام الوحدات: يحتضن Bun JavaScript الحديث مع دعم من الدرجة الأولى لوحدات ES (ESM). ومع ذلك، فإنه يدرك النظام البيئي الواسع الحالي المبني على CommonJS (CJS). يوفر Bun توافقًا قويًا لكلا نظامي الوحدات، مما يسمح للمطورين باستخدام import وrequire بشكل متبادل إلى حد كبير والاستفادة من ملايين حزم CJS الموجودة والمتاحة على npm.
  4. الالتزام بواجهات برمجة تطبيقات الويب القياسية: مبدأ تصميم رئيسي هو تنفيذ واجهات برمجة تطبيقات الويب القياسية. وظائف وكائنات مثل fetch، Request، Response، Headers، WebSocket، وواجهة برمجة تطبيقات Streams (ReadableStream، WritableStream) مدمجة في النطاق العام لـ Bun. هذا يعزز قابلية نقل الكود بين بيئات Bun من جانب الخادم، والواجهات الأمامية للمتصفح، ومنصات الحوسبة الطرفية (edge computing)، مما يسمح للمطورين بإعادة استخدام واجهات برمجة التطبيقات المألوفة عبر سياقات مختلفة.
  5. توافق Node.js: بينما يشق Bun طريقه الخاص بواجهات برمجة تطبيقات محسّنة ومعايير الويب، فإنه يهدف إلى درجة عالية من التوافق مع سطح واجهة برمجة تطبيقات Node.js. يتم تنفيذ العديد من وحدات Node.js المدمجة (node:fs، node:path، node:os، node:events، إلخ) والكائنات العامة (process، Buffer، __filename، __dirname) جزئيًا أو كليًا. الهدف هو السماح للعديد من مشاريع Node.js وحزم npm الموجودة بالعمل على Bun بأقل تعديل أو بدون تعديل، مما يضع Bun كـ "بديل مباشر" محتمل في العديد من الحالات.

من خلال الجمع بين هذه العناصر، يقدم Bun بديلاً مقنعًا لمطوري JavaScript وTypeScript الذين يبحثون عن الأداء والبساطة وتجربة تطوير حديثة.

كيفية تثبيت Bun

تم تصميم البدء باستخدام Bun ليكون سريعًا ومباشرًا عبر مختلف المنصات. الطريقة الأكثر شيوعًا لنظام macOS وLinux وWindows Subsystem for Linux (WSL) تستخدم أمر curl بسيط يتم تنفيذه في الطرفية الخاصة بك:

curl -fsSL https://bun.sh/install | bash

يقوم هذا الأمر بتنزيل سكريبت التثبيت وتمريره مباشرةً إلى bash. يتعامل السكريبت مع اكتشاف نظام التشغيل والبنية الخاصة بك، ويقوم بتنزيل الملف التنفيذي المناسب لـ Bun، وعادةً ما يقوم بتثبيته في ~/.bun/bin. كما يحاول تحديث ملف تكوين shell الخاص بك (مثل .zshrc أو .bashrc أو .bash_profile) لإضافة ~/.bun/bin إلى PATH النظام الخاص بك، مما يجعل أمر bun متاحًا عالميًا. قد تحتاج إلى إعادة تشغيل جلسة الطرفية الخاصة بك أو تشغيل ملف تكوين shell يدويًا (مثل source ~/.zshrc) لتصبح التغييرات سارية المفعول على الفور.

إذا واجهت مشاكل في الأذونات أو فضلت عدم التمرير مباشرةً إلى bash، يمكنك تنزيل السكريبت أولاً وفحصه قبل التشغيل:

curl -fsSL https://bun.sh/install -o install.sh
# Inspect install.sh if desired
bash install.sh

طرق تثبيت أخرى:

npm install -g bun

docker run --rm --init --ulimit memlock=-1:-1 oven/bun:latest bun --version

brew tap oven-sh/bun
brew install bun

التحقق:

بمجرد التثبيت، افتح نافذة طرفية جديدة وتحقق من التثبيت عن طريق التحقق من الإصدار:

bun --version

يجب أن يُظهر هذا رقم الإصدار المثبت، مؤكدًا أن Bun جاهز للاستخدام. يمكنك أيضًا تشغيل bun --help لرؤية قائمة بالأوامر والخيارات المتاحة.

تشغيل Bun لأول مرة

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

قم بإنشاء ملف جديد باسم server.js (أو server.ts، حيث يتعامل Bun مع كليهما):

// server.ts

// Bun.serve starts the HTTP server
const server = Bun.serve({
  // Specify the port to listen on.
  // Defaults to process.env.PORT || 3000
  port: 3000,

  // The 'fetch' function is the core request handler.
  // It receives a standard Request object and must return a Response object (or a Promise resolving to one).
  fetch(request: Request): Response {
    // Create a standard Web API Response object
    return new Response("Welcome to Bun!");
  },
});

// Log a message indicating the server is running
console.log(`Listening on http://localhost:${server.port}`);

يقوم هذا المقتطف البرمجي بما يلي:

  1. يستدعي الدالة Bun.serve، وهي الدالة الأساسية لإنشاء خوادم HTTP في Bun.
  2. يمرر كائن تكوين، يحدد المنفذ (port) (3000 في هذه الحالة).
  3. الجزء الحاسم هو دالة fetch. يتم استدعاء هذه الدالة لكل طلب HTTP وارد. تتوافق مع نمط معالج حدث fetch في Service Worker، وتقبل كائن Request قياسيًا.
  4. داخل fetch، نقوم بإنشاء وإرجاع كائن Response قياسي. هنا، نرجع ببساطة نصًا عاديًا "Welcome to Bun!".
  5. أخيرًا، نسجل رسالة تأكيد في الطرفية، بما في ذلك المنفذ الفعلي الذي يستمع عليه الخادم (يمكن الوصول إليه عبر server.port).

لتشغيل هذا الخادم، افتح الطرفية في الدليل الذي حفظت فيه الملف ونفذ:

bun run server.ts

أو، إذا حفظته كـ server.js:

bun run server.js

سيقوم Bun بتنفيذ السكريبت. إذا استخدمت TypeScript (server.ts)، سيتعامل المُحَوِّل الداخلي لـ Bun مع التحويل إلى JavaScript أثناء التنفيذ. سترى رسالة "Listening on http://localhost:3000".

الآن، افتح متصفح الويب الخاص بك وانتقل إلى http://localhost:3000. يجب أن ترى النص "Welcome to Bun!" معروضًا.

لإيقاف الخادم، ارجع إلى الطرفية واضغط على Ctrl + C.

يوضح هذا المثال البسيط سهولة إعداد خادم أساسي وتشغيل الكود (بما في ذلك TypeScript) مباشرةً باستخدام Bun، مما يعرض طبيعته المتكاملة واعتماده على واجهات برمجة تطبيقات الويب القياسية مثل Request وResponse.

ما هو دعم TypeScript الأصلي في Bun؟

إحدى أهم مزايا Bun، خاصةً للمطورين الذين يستخدمون بالفعل أو يرغبون في اعتماد TypeScript، هي دعمه المباشر والجاهز من الدرجة الأولى. على عكس Node.js، حيث يتطلب تشغيل TypeScript عادةً التجميع المسبق باستخدام مُجمّع TypeScript (tsc) أو استخدام مُحمّلات/مسجلات مثل ts-node أو tsx، يتعامل Bun مع ذلك بشكل أصلي وشفاف.

كيف يعمل:

عندما تطلب من Bun تشغيل ملف .ts أو .tsx (مثل bun run myscript.ts)، فإنه يستدعي تلقائيًا مُحَوِّله الداخلي. هذا المُحَوِّل مكتوب بلغة برمجية أصلية (Zig) وهو سريع للغاية. وظيفته هي:

  1. تجريد الأنواع: إزالة تعليقات نوع TypeScript، الواجهات، التعدادات، إلخ، حيث أنها ليست جزءًا من تنفيذ JavaScript القياسي.
  2. تحويل الصيغة: تحويل الصيغة الخاصة بـ TypeScript (مثل بعض استخدامات enum أو صيغة المزيّنات القديمة إذا تم تكوينها) إلى ما يعادلها في JavaScript.
  3. التعامل مع JSX: تحويل صيغة JSX (المستخدمة في ملفات .tsx و.jsx) إلى استدعاءات دوال JavaScript قياسية (عادةً React.createElement أو ما يعادله في وقت تشغيل JSX المكوّن).

الفائدة الرئيسية هي أن هذا يحدث أثناء التنفيذ مباشرةً أثناء عملية التنفيذ (bun run) أو التجميع (bun build). لا توجد خطوة بناء منفصلة وصريحة مطلوبة فقط لتشغيل كود TypeScript الخاص بك أثناء التطوير.

مثال:

ضع في اعتبارك ملف TypeScript هذا (greet.ts):

// greet.ts
interface User {
  name: string;
  id: number;
}

function greetUser(user: User): void {
  console.log(`Hello, ${user.name} (ID: ${user.id})!`);
}

const myUser: User = { name: "Bun Developer", id: 123 };

greetUser(myUser);

// You can even use modern features Bun supports
const message = `Bun version: ${Bun.version}`;
console.log(message);

يمكنك تشغيل هذا مباشرةً:

bun run greet.ts

سيقوم Bun بتحويله داخليًا وتنفيذ JavaScript الناتج، مما ينتج عنه إخراج مثل:

Hello, Bun Developer (ID: 123)!
Bun version: 1.x.y

دعم JSX:

بالمثل، إذا كان لديك ملف .tsx يحتوي على JSX:

// component.tsx

// Assuming you have JSX configured (Bun defaults often work with React)
function MyComponent({ name }: { name: string }) {
  return <div className="greeting">Hello, {name}!</div>;
}

// NOTE: Running this directly won't render HTML,
// it just shows the transpiled JS structure.
// You'd typically use this within a larger app or framework.
console.log("Simulating component creation (transpiled output structure):");
// The actual output depends on JSX transform settings,
// but it would be JavaScript objects/function calls.

تشغيل bun run component.tsx سيقوم بتنفيذ الملف، محولًا JSX إلى JavaScript.

التكوين (tsconfig.json):

يحترم Bun ملفات tsconfig.json لخيارات التكوين التي تؤثر على التحويل. بينما لا يقوم بإجراء فحص كامل للأنواع مثل tsc (يركز Bun على سرعة التنفيذ والتحويل)، فإنه يقرأ tsconfig.json لفهم الإعدادات مثل:

إذا لم يتم العثور على ملف tsconfig.json، يستخدم Bun إعدادات افتراضية معقولة.

هذا التكامل السلس يجعل بدء مشاريع TypeScript باستخدام Bun بسيطًا وسريعًا بشكل لا يصدق، مما يقلل من حاجز الدخول ويسرع دورات التطوير.

لنتحدث عن واجهات برمجة التطبيقات الخاصة بـ Bun

بينما يركز Bun بشكل كبير على التوافق مع واجهات برمجة تطبيقات الويب القياسية وNode.js، فإنه يقدم أيضًا مجموعته الخاصة من واجهات برمجة التطبيقات المدمجة والمحسّنة تحت الكائن العام Bun. غالبًا ما توفر واجهات برمجة التطبيقات هذه بدائل عالية الأداء أو أغلفة (wrappers) مريحة للمهام الشائعة التي تستفيد من قدرات Bun البرمجية الأصلية.

إليك لمحة عن بعض واجهات برمجة التطبيقات الرئيسية Bun.*:

تمثل واجهات برمجة التطبيقات هذه جهد Bun لتوفير حلول مدمجة ومحسّنة للمهام الشائعة في التطوير، مما يقلل الاعتماد على التبعيات الخارجية ويستفيد من سرعة نواته الأصلية.

واجهات برمجة تطبيقات الويب في Bun

اختيار تصميم أساسي في Bun هو التزامه القوي بتنفيذ واجهات برمجة تطبيقات الويب القياسية. حيثما توجد واجهة برمجة تطبيقات قياسية لمهمة معينة (خاصة للشبكات ومعالجة البيانات)، يفضل Bun تنفيذ هذا المعيار بدلاً من ابتكار واجهة برمجة تطبيقات خاصة أو الاعتماد فقط على اصطلاحات Node.js.

يقدم هذا النهج العديد من المزايا الهامة:

  1. قابلية نقل الكود: يمكن غالبًا إعادة استخدام الكود المكتوب باستخدام واجهات برمجة تطبيقات الويب القياسية عبر بيئات JavaScript مختلفة – المتصفح، Node.js (الذي يعتمد أيضًا بشكل متزايد معايير الويب)، Deno، Cloudflare Workers، وBun – مع تعديلات أقل.
  2. الألفة: يمكن للمطورين المألوفين بالفعل بواجهات برمجة تطبيقات المتصفح الاستفادة من تلك المعرفة عند العمل مع Bun، مما يقلل من منحنى التعلم.
  3. مقاومة المستقبل: التوافق مع المعايير التي وضعتها هيئات مثل WHATWG وW3C يؤدي عمومًا إلى واجهات برمجة تطبيقات أكثر استقرارًا ودعمًا على نطاق واسع على المدى الطويل.
  4. الأداء: تطبيقات Bun الأصلية لواجهات برمجة تطبيقات الويب هذه محسّنة للغاية لبيئة التشغيل الخاصة بها.

تشمل واجهات برمجة تطبيقات الويب القياسية الرئيسية التي تم تنفيذها في Bun ما يلي:

Fetch API:

URL API:

Streams API:

Encoding API:

Blob API:

FormData API:

WebSocket API:

المؤقتات (Timers):

Console API:

Crypto API:

Performance API:

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

خادم HTTP في Bun، شرح مفصل

الطريقة الأساسية لإنشاء خوادم الويب في Bun هي عبر واجهة برمجة تطبيقات Bun.serve. تم تصميمها لتحقيق أداء استثنائي وسهولة الاستخدام، مع التكامل السلس مع واجهات برمجة تطبيقات الويب القياسية مثل Request وResponse وfetch.

المفاهيم الأساسية:

تأخذ دالة Bun.serve كائن تكوين وتعيد كائن Server. الجزء الأكثر أهمية في التكوين هو دالة fetch.

import { type Server } from "bun";

const server: Server = Bun.serve({
  port: 8080, // The port to listen on
  hostname: "0.0.0.0", // The network interface to bind to (0.0.0.0 for all)

  // fetch: The heart of the server - handles incoming requests
  async fetch(req: Request, server: Server): Promise<Response> {
    // req is a standard Web API Request object
    // server is a reference to the Server instance itself

    const url = new URL(req.url);

    // Basic Routing Example
    if (url.pathname === "/") {
      return new Response("Homepage");
    }
    if (url.pathname === "/about") {
      return new Response("About Us page");
    }
    if (url.pathname === "/greet" && req.method === "GET") {
        const name = url.searchParams.get("name") || "World";
        return new Response(`Hello, ${name}!`);
    }
     if (url.pathname === "/data" && req.method === "POST") {
        try {
            const data = await req.json(); // Read request body as JSON
            console.log("Received data:", data);
            return new Response(JSON.stringify({ received: data }), {
               headers: { 'Content-Type': 'application/json' }
            });
        } catch (e) {

ممارسة تصميم API في Apidog

اكتشف طريقة أسهل لبناء واستخدام واجهات برمجة التطبيقات

التسجيل مجانًاتحميل