Convert JSON to CSV: Complete Guide With Examples

عندما تحتاج إلى تحويل JSON إلى CSV

يعد JSON هو التنسيق الافتراضي لواجهات برمجة التطبيقات (APIs) وتطبيقات الويب، ولكن في اللحظة التي يحتاج فيها البيانات إلى مغادرة نظام المطورين — إلى جدول بيانات، أو أداة ذكاء الأعمال، أو استيراد قاعدة بيانات، أو تقرير يتم إرساله عبر البريد الإلكتروني إلى أحد المعنيين — يكون CSV هو التنسيق المتوقع عادةً.

السيناريوهات الشائعة حيث يظهر تحويل JSON إلى CSV:

• تصدير بيانات API — سحب السجلات من واجهة برمجة تطبيقات REST وتحميلها في Excel أو Google Sheets للتحليل.
• استيرادات قواعد البيانات — تدعم العديد من قواعد البيانات (PostgreSQL، MySQL، SQLite) استيرادات CSV بشكل افتراضي، ولكن ليس JSON.
• التقارير — يحتاج المعنيون غير التقنيين إلى البيانات بتنسيق يمكنهم فتحه في جدول بيانات، وليس في عارض JSON.
• خطوط البيانات — غالبًا ما تتوقع أنظمة ETL القديمة CSV كتنسيق تبادل بين المراحل.

جرب بنفسك: ألصق مصفوفة JSON في محول JSON إلى CSV الخاص بنا للحصول على ملف CSV جاهز للتنزيل على الفور.

walkthrough تحويل بسيط

الحالة المباشرة: لديك مصفوفة JSON من كائنات مسطحة حيث يحتوي كل كائن على نفس المفاتيح. هذا يتطابق مباشرة مع جدول CSV.

JSON المدخل:

[
  { "name": "Alice", "age": 30, "city": "Portland" },
  { "name": "Bob", "age": 25, "city": "Seattle" },
  { "name": "Carol", "age": 35, "city": "Denver" }
]

CSV المخرج:

name,age,city
Alice,30,Portland
Bob,25,Seattle
Carol,35,Denver

تتحول مفاتيح الكائنات إلى رؤوس أعمدة، ويصبح كل كائن صفًا. هذه هي المسار السعيد — ويعمل بشكل مثالي لمعظم استجابات API التي تعيد مصفوفات من السجلات.

تظهر التعقيدات عندما لا يكون JSON مسطحًا. تتطلب الكائنات المتداخلة، والمصفوفات داخل الكائنات، والمفاتيح المفقودة، والأنواع المختلطة قرارات حول كيفية تمثيل البيانات الهيكلية في جدول مسطح.

التعامل مع JSON المتداخل

نادراً ما يكون JSON في العالم الحقيقي مسطحًا. قد تتضمن استجابة API لمستخدم ما كائن عنوان متداخل، ومصفوفة من الأدوار، وحقول اختيارية لا تظهر في كل سجل. لا يحتوي CSV على مفهوم التداخل، لذا تحتاج إلى استراتيجية تسطيح.

الاستراتيجية 1: تدوين النقاط

أكثر الأساليب شيوعًا. يتم دمج المفاتيح المتداخلة مع النقاط لتشكيل اسم عمود واحد.

المدخل:

[
  {
    "name": "Alice",
    "address": {
      "city": "Portland",
      "state": "OR"
    }
  }
]

المخرج:

name,address.city,address.state
Alice,Portland,OR

يحافظ تدوين النقاط على العلاقة الهيكلية في اسم العمود. يعمل بشكل جيد لمستوى أو مستويين من التداخل، ولكنه يصبح غير عملي للبيانات المتداخلة بعمق (user.profile.settings.notifications.email).

الاستراتيجية 2: أعمدة منفصلة لكل قيمة ورقة

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

الاستراتيجية 3: تحويل الكائنات المتداخلة إلى سلسلة نصية

للهياكل المتداخلة المعقدة التي لا تتطابق بشكل جيد مع الأعمدة المسطحة، قم بتسلسل القيمة المتداخلة كسلسلة JSON داخل خلية CSV.

المخرج:

name,address
Alice,"{""city"":""Portland"",""state"":""OR""}"
Bob,"{""city"":""Seattle"",""state"":""WA""}"

هذا يحافظ على جميع البيانات، ولكن تحتوي خلايا CSV على JSON خام — وهو ليس مثاليًا لمستخدمي جداول البيانات. يعمل عندما يكون CSV تنسيقًا وسيطًا سيتم تحليله مرة أخرى بواسطة الشيفرة.

مقارنة أساليب التسطيح

الأسلوب	قابلية القراءة	فقدان البيانات	التداخل العميق	الأفضل لـ
تدوين النقاط	جيد	لا شيء	يصبح مطولاً	1-2 مستويات من التداخل
أسماء الأعمدة المخصصة	الأفضل	تصادم محتمل	جهد يدوي	مخططات معروفة ومستقرة
تحويل إلى سلسلة نصية	سيء للبشر	لا شيء	يتعامل مع أي عمق	خطوط البيانات بين الآلات

التعامل مع المصفوفات داخل الكائنات

تقدم المصفوفات تحديًا مختلفًا. اعتبر مستخدمًا لديه أدوار متعددة:

{
  "name": "Alice",
  "roles": ["admin", "editor", "viewer"]
}

لديك عدة خيارات لتمثيل ذلك في CSV:

• الانضمام كسلسلة مفصولة: admin;editor;viewer في خلية واحدة. بسيطة ولكن تتطلب التحليل لاحقًا.
• أعمدة منفصلة: roles.0, roles.1, roles.2. تعمل عندما يكون طول المصفوفة الأقصى معروفًا وصغيرًا.
• صفوف منفصلة: صف واحد لكل دور، مع تكرار بيانات المستخدم الأخرى. هذا ينزع البيانات ولكنه يتجنب خلايا متعددة القيم.
• تحويل إلى سلسلة نصية: ["admin","editor","viewer"] كـ JSON خام في الخلية. يحافظ على الهيكل للمعالجة لاحقًا.

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

الحالات الخاصة

كل تحويل من JSON إلى CSV في النهاية يواجه هذه الحالات. معرفة عنها مسبقًا يوفر وقت تصحيح الأخطاء.

القيم الفارغة

يمكن أن يتم تعيين JSON null إلى خلية فارغة، أو السلسلة النصية الحرفية null، أو عنصر نائب مخصص. تستخدم معظم الأدوات خلية فارغة، وهو أمر صحيح لجداول البيانات ولكنه يفقد التمييز بين "null" (لا قيمة صريحة) و"المفتاح المفقود" (الحقل غير موجود). إذا كانت تلك التمييز مهمة، استخدم null كسلسلة حرفية.

الأنواع المختلطة

قد يكون حقل JSON سلسلة في سجل واحد ورقمًا في آخر. لا تحتوي أعمدة CSV على أنواع — كل شيء هو سلسلة — لذا عادةً ما يعمل هذا بشكل جيد على مستوى CSV. تظهر المشكلة عند الاستيراد إلى الأنظمة المخصصة (قواعد البيانات، إطارات البيانات المخصصة). تحقق من الأنواع بعد التحويل.

المفاتيح المفقودة

عندما لا تحتوي الكائنات في مصفوفة JSON على نفس المفاتيح، يحتاج المحول إلى بناء اتحاد لجميع المفاتيح عبر جميع الكائنات. ينتج عن ذلك صف رأس مع كل عمود ممكن، وتصبح الكائنات التي تفتقر إلى مفتاح ما خلية فارغة لذلك العمود.

[
  { "name": "Alice", "age": 30 },
  { "name": "Bob", "city": "Seattle" }
]

المخرج:

name,age,city
Alice,30,
Bob,,Seattle

الأحرف الخاصة في القيم

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

name,bio
Alice,"تحب ""JSON"" والترميز"
Bob,"Portland, OR"

التحويل البرمجي

JavaScript / Node.js

لبيانات بسيطة مسطحة، يمكنك تحويل JSON إلى CSV في بضع أسطر دون أي تبعيات:

const jsonToCsv = (data: Record<string, unknown>[]) => {
  if (data.length === 0) return "";

  const headers = Object.keys(data[0]);
  const rows = data.map((row) =>
    headers
      .map((header) => {
        const value = row[header] ?? "";
        const str = String(value);
        return str.includes(",") || str.includes('"') || str.includes("\\n")
          ? `"\${str.replace(/"/g, '""')}"` 
          : str;
      })
      .join(",")
  );

  return [headers.join(","), ...rows].join("\\n");
};

للاستخدام في الإنتاج مع البيانات المتداخلة، تتعامل مكتبات مثل json2csv (من حزمة @json2csv/plainjs) مع التسطيح، والتحولات المخصصة، والحالات الخاصة:

import { Parser } from "@json2csv/plainjs";
import { flatten } from "@json2csv/transforms";

const parser = new Parser({
  transforms: [flatten({ separator: "." })],
});

const csv = parser.parse(data);

بايثون

تحتوي مكتبة بايثون القياسية على كل ما تحتاجه للتحويلات الأساسية:

import csv
import json
import io

def json_to_csv(data: list[dict]) -> str:
    if not data:
        return ""

    output = io.StringIO()
    writer = csv.DictWriter(output, fieldnames=data[0].keys())
    writer.writeheader()
    writer.writerows(data)
    return output.getvalue()

لـ JSON المتداخل، تقوم مكتبة pandas بتسطيح وتحويل في استدعاء واحد:

import pandas as pd

df = pd.json_normalize(data, sep=".")
df.to_csv("output.csv", index=False)

تتعامل json_normalize مع الكائنات المتداخلة تلقائيًا باستخدام تدوين النقاط لأسماء الأعمدة. إنها أسرع طريقة للانتقال من استجابة API متداخلة إلى ملف CSV نظيف.

اعتبارات الملفات الكبيرة

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

المحللات المتدفقة هي الحل. بدلاً من تحميل الملف بالكامل، تقوم بمعالجته بشكل تدريجي:

• Node.js: استخدم JSONStream أو stream-json لتحليل مصفوفة JSON كائنًا واحدًا في كل مرة، وتحويل كل منها إلى صف CSV، وكتابته إلى دفق الإخراج. تبقى الذاكرة ثابتة بغض النظر عن حجم الملف.
• بايثون: توفر مكتبة ijson تحليل JSON تكراري. اجمعها مع csv.writer الكتابة إلى مقبض ملف لتحويل ثابت الذاكرة.
• CLI: يقوم jq بمعالجة JSON بطريقة متدفقة بشكل أصلي. لأغراض تحويل JSON إلى CSV بشكل محدد، تم تصميم أدوات مثل miller (mlr) و csvkit لتحويل التنسيقات على نطاق واسع.

قاعدة عملية: إذا كان ملف JSON الخاص بك أقل من 50 ميجابايت، فإن التحويل في الذاكرة جيد. فوق ذلك، انتقل إلى نهج متدفق. فوق 1 جيجابايت، استخدم أداة CLI مثل miller أو إطار معالجة بيانات مخصص.

اختيار النهج الصحيح

السيناريو	النهج الموصى به
تحويل سريع لمرة واحدة	أداة عبر الإنترنت أو محول متصفح
JSON مسطح، ملفات صغيرة	مكتبة اللغة المدمجة (وحدة csv، دالة JS بسيطة)
JSON متداخل، مخطط معقد	pandas.json_normalize أو @json2csv مع تحويل التسطيح
ملفات كبيرة (>50 ميجابايت)	محلل متدفق (ijson، stream-json) أو CLI (miller)
خط أنابيب متكرر	نص برمجي مع مكتبة، مدمج في CI/ETL

بالنسبة لمعظم المطورين، فإن مسار التحويل السريع هو كل ما يحتاجونه. ألصق JSON، احصل على CSV، انتقل. تصبح التعقيدات مهمة فقط عندما تكون البيانات متداخلة، أو الملفات كبيرة، أو يتم تشغيل التحويل بدون مراقبة في خط أنابيب.

جرب بنفسك: ألصق بيانات JSON الخاصة بك في محول JSON إلى CSV الخاص بنا للحصول على ملف CSV نظيف في ثوانٍ. هل تحتاج إلى الذهاب في الاتجاه الآخر؟ استخدم أداة CSV إلى JSON الخاصة بنا.