الصق نماذج Python المكتوبة بـ BaseModel من Pydantic أو @dataclass أو TypedDict، لتحصل على مستند JSON نموذجي يتبع بنيتها. يُقرأ Field(alias=...) وإعداد alias_generator=to_camel، فترى المفاتيح التي تُسلسَل إليها حقولك المكتوبة بـ snake_case فعلًا.
يناسب بناء أمثلة الطلبات لنقاط نهاية FastAPI، أو مشاركة مخطط payload لـ webhook أو طابور رسائل مع فريق آخر، أو تجهيز بيانات JSON ثابتة لـ pytest.
.py الذي يحوي نماذجك. تُتخطى أسطر import والدوال والـ decorators مثل @field_validator.Enum حتى تُملأ تلك الأجزاء. والإشارات الأمامية النصية ("Order") مفهومة.تلقائي، يختار النوع الجذري الصنف الذي لا يستخدمه نموذج آخر نوعًا لحقل؛ ويمكنك أيضًا اختيار صنف من القائمة.examples في json_schema_extra أو إلى ملف بيانات اختبار أو إلى وثائق الـ API.class Payer(BaseModel):
model_config = ConfigDict(alias_generator=to_camel)
customer_id: str
email_address: str
class PaymentEvent(BaseModel):
model_config = ConfigDict(alias_generator=to_camel)
event_type: Literal["payment.succeeded", "payment.failed"]
amount: Decimal
currency: str = "KRW"
payer: Payer
receipt_url: Optional[str] = None
retry_count: int = Field(default=0, alias="retries")
raw_payload: dict = Field(exclude=True){
"eventType": "payment.succeeded",
"amount": "0",
"currency": "KRW",
"payer": {
"customerId": "",
"emailAddress": ""
},
"receiptUrl": "",
"retries": 0
}بسبب to_camel في model_config، تتحول event_type وreceipt_url وcustomer_id إلى مفاتيح camelCase، بينما يفوز alias="retries" الصريح في retry_count. ويُحذف raw_payload لأن عليه Field(exclude=True). ويأخذ الـ Literal قيمته الأولى، payment.succeeded، وتُحفظ القيمة الافتراضية الحرفية "KRW" كما هي.
BaseModel من Pydantic (v1 وv2)، و@dataclass، وTypedDict، وEnum/StrEnum/IntEnum بما فيها auto().Field(alias=...) وserialization_alias وalias_generator (to_camel، to_pascal) المضبوطة في model_config = ConfigDict(...) أو في class Config: داخلي._، وClassVar، وmodel_config، وحقول Field(exclude=True).Optional[X] / X | None → عيّنة من X، وLiteral[...] → القيمة الأولى، وAnnotated/Required/NotRequired → النوع الداخلي، وlist/set/tuple → مصفوفة من عنصر واحد، وdict[str, V] → {"key": V}.EmailStr وHttpUrl وSecretStr وconstr → سلسلة نصية؛ وconint وPositiveInt → 0؛ وDecimal وcondecimal → السلسلة "0"، كما يكتبها JSON في Pydantic v2.datetime → 1970-01-01T00:00:00، وdate → 1970-01-01، وtime → 00:00:00، وtimedelta → PT0S؛ ويحصل UUID على قيمة سليمة الصيغة.True/False عيّناتٍ؛ والقيمة الافتراضية من enum مثل Status.PAID تصبح قيمة ذلك العضو.ولّد JSON من نموذج طلب وضعه في model_config = {"json_schema_extra": {"examples": [...]}}؛ فيستخدم المثال في /docs عندها مفاتيح الأسماء البديلة نفسها التي تتوقعها نقطة النهاية.
إن كانت payloads مهام Celery أو رسائل Kafka معرَّفة بـ Pydantic، فأعطِ فرق المستهلكين على Node أو Go ملف JSON الناتج بدلًا من كود Python للاتفاق على البنية.
أنشئ هيكل ملف JSON لاختبارات model_validate_json() أو عميل الـ API، ثم غيّر قيمًا بعينها لإضافة الحالات الحدّية.
Optional والحقول ذات القيمة الافتراضية None تحصل مع ذلك على عيّنة من نوعها بدلًا من null.Decimal بالسلسلة "0"، بما يطابق تسلسل JSON في Pydantic v2 (model_dump_json). إن كان مشروعك يُخرج أرقامًا بدلًا من ذلك (Pydantic v1، أو json.dumps(default=float))، فغيّره إلى رقم.@computed_field أو @field_serializer أو @model_serializer، لا يُنفَّذ.Union[A, B] أول عضو ليس None؛ ولا تُنمذَج الاتحادات المميَّزة التي يُختار عضوها بحقل discriminator.default_factory ولا القيم الافتراضية الناتجة عن استدعاءات دوال؛ بل تأتي القيمة من النوع.model_dump_json() عندي يطبع أسماء الحقول.يُسلسِل Pydantic بأسماء الحقول ما لم تمرّر by_alias=True. ويستخدم response_model في FastAPI by_alias=True افتراضيًا، وهذا يطابق ناتج هذه الأداة. وعند التفريغ بنفسك، استدعِ model_dump_json(by_alias=True).
لا توجد إعادة تسمية في dataclass القياسي، فاسم الحقل هو المفتاح. لكن إن حمل حقلٌ تعليقًا لاحقًا # JSON: "orderId"، كما في الـ dataclasses التي تنتجها صفحة JSON → Python في هذا الموقع، يُستخدم ذلك الاسم.
NotRequired في TypedDict؟نعم. العيّنة مقصود بها إظهار كل المفاتيح الممكنة، لذا تُضمَّن حقول NotRequired وtotal=False. حدّد في وثائقك تلك التي قد تُحذف.
هذه الصفحة للنماذج المبنية على تلميحات الأنواع. لنماذج SQLAlchemy المعرَّفة بـ Column(...) أو Mapped[...]، استخدم صفحة SQLAlchemy → JSON.