حوّل نماذج SQLAlchemy إلى JSON!

أدخل نماذج SQLAlchemy لإنشاء JSON تجريبي! يدعم SQLAlchemy ORM. مفيد لتوثيق واجهات API وأجسام الطلبات التجريبية (mock request body).
SQLAlchemy
النتيجة
 

حوّل نماذج SQLAlchemy إلى JSON!

الصق أصناف نماذج SQLAlchemy لتحصل على JSON نموذجي مفاتيحه أسماء سمات الأعمدة. يقرأ أسلوب 2.0 Mapped[...] مع mapped_column()، وأسلوب 1.x Column()، وdb.Column() في Flask-SQLAlchemy، ويدمج الأعمدة القادمة من الـ mixins والأصناف الأب.

لا يمكن تمرير نماذج SQLAlchemy إلى json.dumps مباشرة، لذا تضيف تطبيقات FastAPI وFlask مخططات Pydantic أو Marshmallow. استخدم هذا لترتيب الحقول التي سيعرضها النموذج قبل كتابة ذلك المخطط، أو لبناء أجسام الطلبات للاختبارات.

طريقة الاستخدام

  1. الصق ملف النموذج في خانة SQLAlchemy. أبقِ Base والـ mixins وأصناف enum.Enum في الإدخال نفسه حتى تُحلّ الأعمدة الموروثة وقيم الـ enum.
  2. لا تُعدّ نماذج إلا الأصناف التي فيها __tablename__. وتُخرج النماذج المتعددة باسم الصنف، مثل { "User": {...}, "Team": {...} }.
  3. انسخ النتيجة.

مثال

المدخلات (Python · Flask-SQLAlchemy)
class TimestampMixin:
    created_at = db.Column(db.DateTime, default=datetime.utcnow)


class Plan(enum.Enum):
    FREE = "free"
    PRO = "pro"


class Subscription(TimestampMixin, db.Model):
    __tablename__ = "subscriptions"

    id = db.Column(db.Integer, primary_key=True)
    plan = db.Column(db.Enum(Plan), nullable=False)
    seats = db.Column(db.SmallInteger, default=1)
    trial_ends = db.Column(db.Date)
    user_id = db.Column(db.Integer, db.ForeignKey("users.id"))
    user = db.relationship("User", backref="subscriptions")
المخرجات (JSON)
{
  "created_at": "1970-01-01T00:00:00",
  "id": 0,
  "plan": "free",
  "seats": 1,
  "trial_ends": "1970-01-01",
  "user_id": 0
}

يأتي created_at من TimestampMixin أولًا، وفق ترتيب الوراثة، ويُحذف user لأن relationship() ليس عمودًا. يأخذ db.Enum(Plan) القيمة الأولى في الـ enum، "free"، ويصبح db.Date على شكل 1970-01-01. ويُظهر seats القيمة 1 من default=1، بينما يُبقي created_at القيمة البديلة لأن datetime.utcnow دالة.

الميزات المدعومة

  • تلميحات الأنواع في Python مثل Mapped[int] وMapped[Optional[str]] وMapped[str | None] تحدد القيمة.
  • دون تلميح نوع، يحدد معامل نوع SQL القيمة، كما في Column(String(50)) أو db.Column(db.Numeric).
  • DateTime → 1970-01-01T00:00:00، وDate → 1970-01-01، وTime → 00:00:00، وJSON/JSONB → {}، وUuid → UUID كله أصفار.
  • يصبح ARRAY(String) وMapped[list[str]] مصفوفات من عنصر واحد.
  • الصنف الذي يرث enum.Enum، والمستخدم عبر Enum(Plan) أو Mapped[Plan]، يساهم بقيمة عضوه الأول.
  • تُستبعد relationship() وcolumn_property() ومتغيرات الصنف العادية والسمات ذات الشرطتين مثل __table_args__.
  • تُوضع الأعمدة القادمة من الـ mixins والنماذج الأب قبل أعمدة الصنف الابن.

حالات الاستخدام

مسودة نموذج استجابة Pydantic

قبل كتابة صنف Pydantic لـ response_model في FastAPI، تحقق من الحقول والأنواع التي يعرضها النموذج كـ JSON. وأدخل ذلك الـ JSON في صفحة JSON إلى Python لتحصل على مسودة Pydantic أيضًا.

payloads اختبار لـ API في Flask

ابنِ جسم client.post("/subscriptions", json=...) بمفاتيح تطابق سمات النموذج. واحذف أولًا id ذا الزيادة التلقائية ووقت الإنشاء.

ملاحظات وقيود

  • يُستخدم default= الحرفي ("new"، 1، True، None) قيمةً نموذجية؛ ولا تُشغَّل الدوال القابلة للاستدعاء مثل datetime.utcnow أو dict. ولا يُقرأ server_default= ولا nullable=.
  • إذا أُعطي عمود اسمًا منفصلًا في قاعدة البيانات، كما في Column("user_name", String)، يبقى مفتاح JSON اسم السمة في Python.
  • لا تُضمَّن الكائنات المرتبطة المحمَّلة عبر relationship. أضف الكائنات المتداخلة بنفسك إن كانت استجابتك تضمّنها.
  • السمات المحسوبة مثل hybrid_property أو @property ليست جزءًا من الناتج.

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

لماذا يكون Mapped[Optional[str]] سلسلة فارغة بدلًا من null؟

Optional يعني أن None مسموح؛ والمثال يُظهر الحالة التي توجد فيها قيمة، فيستخدم str الداخلي. غيّره إلى null في الناتج إن احتجت إلى تلك الحالة.

لماذا لا يوجد Z أو إزاحة في التواريخ والأوقات؟

أعمدة DateTime بلا منطقة زمنية (naive) افتراضيًا، وisoformat() يطبعها دون إزاحة. إن كنت تستخدم DateTime(timezone=True)، فالمثال الذي فيه +00:00 أقرب إلى ما ستراه فعلًا.

هل يمكنه تحويل نماذج Django؟

لا. هذه الصفحة لا تفهم إلا صيغة Column وmapped_column وMapped في SQLAlchemy؛ ولا يُتعرَّف على حقول Django مثل models.CharField.