أغلفة أخطاء JSON موحّدة
وحّد بنية الأخطاء لعملاء API.
أغلفة أخطاء JSON موحّدة درس مجاني في Flask Academy على CoddyKit. هذا هو الدرس 4 من أصل 4. يمكنك قراءة الدرس كاملاً أدناه مجاناً — ثم تمرن عليه مباشرة في المتصفح باستخدام محرر أكواد مدمج ومدرس ذكاء اصطناعي متاح 24/7. هذا الدرس جزء من مسار التعلم في Flask Academy، وتقدمك يتزامن عبر الويب وتطبيق CoddyKit. تتضمن دورة Flask Academy 4 دروس في المجموع.
بعض أجزاء هذا الدرس لم تُترجم بعد وتظهر باللغة الإنجليزية.
One Shape for Every Error
Mixed error formats confuse clients. A uniform envelope means every failure looks the same, so apps parse it once and trust it.
What an Envelope Holds
A good envelope carries a stable error message and a code. Clients read these fields instead of guessing from raw text.
{
"error": "Not found",
"code": 404
}Add a Machine Code
Beyond the message, include a short code string. Clients branch on it safely even if you reword the human text later.
{
"error": "Not found",
"code": "post_missing"
}Build It in a Helper
Wrap envelope creation in a small helper function. Every handler calls it, so the shape never drifts apart.
def envelope(msg, code):
return jsonify(error=msg, code=code)Use It in Handlers
Each errorhandler returns the helper plus a status. The status code and body now always agree across your API.
return envelope("Not found", 404), 404Catch HTTPException Centrally
Register one handler for HTTPException to wrap every built-in error. That single spot formats 404, 400, and more.
@app.errorhandler(HTTPException)
def wrap(e):
return envelope(e.description, e.code), e.codeInclude Field Details
For validation, add a details field listing which inputs failed. Clients can then highlight the exact bad fields.
{
"error": "Invalid",
"details": {"email": "required"}
}Keep Status and Body in Sync
The number in the body should match the real HTTP status. Mismatches break clients that trust one over the other.
Do Not Leak Internals
Never put stack traces in the envelope. Log them privately and show clients only a safe, generic message.
Document the Format
Write down your envelope shape so every endpoint follows it. A documented contract keeps your whole API predictable.
Why It Pays Off
One stable error shape makes client code simpler and bugs rarer. Teams build on a predictable API with far less friction.
Quick Check
Why give clients a stable error code string?
Recap
You designed a uniform JSON envelope with message, code, and details, wrapped errors centrally, and kept status and body in sync. You did it!
تعلم Python مع معلم ذكاء اصطناعي — مجانًا
اكتب وقم بتشغيل أكوادك الفعلية في المتصفح، واحصل على مساعدة فورية من معلم ذكاء اصطناعي متاح 24/7، واستمر من حيث توقفت على الويب أو في التطبيق.
- الدورات
- 30
- الدروس
- 120
الأسئلة الشائعة
هل درس «أغلفة أخطاء JSON موحّدة» مجاني؟
نعم — نص درس «أغلفة أخطاء JSON موحّدة» كامل متاح مجاناً هنا على الويب. لتمرينه بشكل تفاعلي (محرر أكواد مدمج ومدرس ذكاء اصطناعي متاح 24/7) وفتح باقي دورة Flask Academy، انتقل إلى CoddyKit PRO. تتضمن دورة Flask Academy 4 دروس في المجموع.
ماذا ستتعلم في «أغلفة أخطاء JSON موحّدة»؟
وحّد بنية الأخطاء لعملاء API. تتمرن على Flask Academy مع أكواد عملية تشغلها مباشرة في المتصفح، ومدرس ذكاء اصطناعي متاح 24/7 يجيب على أسئلتك أثناء عملك.
هل أحتاج إلى خبرة سابقة لأبدأ Flask Academy؟
لا تُشترط خبرة سابقة. Flask Academy على CoddyKit منظم للمبتدئين حتى المتقدمين، لذا يمكنك البدء من هنا أو من البداية والتقدم بسرعتك الخاصة. هذا هو الدرس 4 من أصل 4.
كم من الوقت يستغرق درس «أغلفة أخطاء JSON موحّدة»؟
معظم دروس CoddyKit تستغرق حوالي 5–10 دقائق. كل منها موجز وتفاعلي، لذا تحرز تقدماً مستمراً وتستأنف من حيث توقفت عبر الويب والتطبيق.
هل يمكنني كتابة وتشغيل أكواد في درس Flask Academy هذا؟
نعم. كل درس في Flask Academy يتضمن محرر أكواد مدمج، لذا تكتب وتشغل أكواداً حقيقية مباشرة في متصفحك وتحصل على تعليقات فورية من الذكاء الاصطناعي — بدون إعداد محلي.
جميع الدروس في هذه الدورة
- abort ورموز أخطاء HTTP
- تسجيل دوال errorhandler
- إطلاق فئات استثناء مخصصة
- أغلفة أخطاء JSON موحّدة