gRPC & High Performance APIs · درس

نماذج الأخطاء الغنية باستخدام google.rpc.Status

تجاوزوا رموز الحالة العادية بإرفاق تفاصيل أخطاء منظّمة وقابلة للقراءة آليًا باستخدام نموذج google.rpc.Status وأنواع تفاصيل الأخطاء القياسية.

نماذج الأخطاء الغنية باستخدام google.rpc.Status درس مجاني في gRPC & High Performance APIs على CoddyKit. هذا هو الدرس 4 من أصل 4. يمكنك قراءة الدرس كاملاً أدناه مجاناً — ثم تمرن عليه مباشرة في المتصفح باستخدام محرر أكواد مدمج ومدرس ذكاء اصطناعي متاح 24/7. هذا الدرس جزء من مسار التعلم في gRPC & High Performance APIs، وتقدمك يتزامن عبر الويب وتطبيق CoddyKit. تتضمن دورة gRPC & High Performance APIs 4 دروس في المجموع.

بعض أجزاء هذا الدرس لم تُترجم بعد وتظهر باللغة الإنجليزية.

Limits of Plain Status Codes

A bare status code plus a message tells the client that something failed, but not the structured why. Clients often need field-level validation errors, retry hints, or quota info.

The rich error model attaches structured details to a status.

The google.rpc.Status Message

The core type is google.rpc.Status with three fields:

code: a numeric status code
message: developer-facing text
details: a repeated list of Any payloads

Standard Detail Types

Google defines reusable detail messages in google/rpc/error_details.proto:

BadRequest — field violations
RetryInfo — when to retry
QuotaFailure — limit exceeded
ErrorInfo — machine-readable reason

BadRequest for Validation

BadRequest carries a list of FieldViolation entries, each naming a bad field and describing the problem. Perfect for form validation responses.

Building a Rich Error in Go

The status package lets you create a status and append typed details with WithDetails.

st := status.New(codes.InvalidArgument, 'invalid request')
v := &errdetails.BadRequest_FieldViolation{
  Field: 'email', Description: 'must be a valid address',
}
br := &errdetails.BadRequest{FieldViolations: []*errdetails.BadRequest_FieldViolation{v}}
st, _ = st.WithDetails(br)
return st.Err()

RetryInfo for Backoff Hints

For temporary failures, attach RetryInfo with a retry_delay. A well-behaved client reads this and waits before retrying.

ri := &errdetails.RetryInfo{RetryDelay: durationpb.New(2 * time.Second)}
st, _ = status.New(codes.Unavailable, 'busy').WithDetails(ri)

ErrorInfo for Stable Reasons

ErrorInfo gives a stable reason string and a domain plus metadata. Unlike free-text messages, clients can branch on these reliably.

ei := &errdetails.ErrorInfo{
  Reason: 'EMAIL_TAKEN', Domain: 'auth.example.com',
}

Reading Details on the Client

The client converts the returned error back to a status and inspects each detail with a type switch.

st := status.Convert(err)
for _, d := range st.Details() {
  switch t := d.(type) {
  case *errdetails.BadRequest:
    handleFieldErrors(t)
  case *errdetails.RetryInfo:
    waitThenRetry(t.RetryDelay)
  }
}

How Details Travel

Details are serialized into the grpc-status-details-bin trailer as a binary Status proto. Languages with the rich-error libraries decode it automatically.

Best Practices

Use the rich model wisely:

Prefer standard detail types for interoperability
Never leak secrets in messages or details
Keep ErrorInfo.reason values stable and documented
Pair RetryInfo with truly retryable codes

Cross-Language Interop

Because the model is defined in protobuf, a Go server can emit a BadRequest that a Java or Python client decodes identically. This consistency is the whole point of the standard types.

Quick Check

Test your rich error knowledge.

Recap

You learned the rich error model:

google.rpc.Status carries code, message, and repeated detail Any payloads
Standard types: BadRequest, RetryInfo, QuotaFailure, ErrorInfo
Build with WithDetails, read with a type switch over Details()
Details travel in the grpc-status-details-bin trailer
Standard types give cross-language consistency

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

هل درس «نماذج الأخطاء الغنية باستخدام google.rpc.Status» مجاني؟

نعم — نص درس «نماذج الأخطاء الغنية باستخدام google.rpc.Status» كامل متاح مجاناً هنا على الويب. لتمرينه بشكل تفاعلي (محرر أكواد مدمج ومدرس ذكاء اصطناعي متاح 24/7) وفتح باقي دورة gRPC & High Performance APIs، انتقل إلى CoddyKit PRO. تتضمن دورة gRPC & High Performance APIs 4 دروس في المجموع.

ماذا ستتعلم في «نماذج الأخطاء الغنية باستخدام google.rpc.Status»؟

تجاوزوا رموز الحالة العادية بإرفاق تفاصيل أخطاء منظّمة وقابلة للقراءة آليًا باستخدام نموذج google.rpc.Status وأنواع تفاصيل الأخطاء القياسية. تتمرن على gRPC & High Performance APIs مع أكواد عملية تشغلها مباشرة في المتصفح، ومدرس ذكاء اصطناعي متاح 24/7 يجيب على أسئلتك أثناء عملك.

هل أحتاج إلى خبرة سابقة لأبدأ gRPC & High Performance APIs؟

لا تُشترط خبرة سابقة. gRPC & High Performance APIs على CoddyKit منظم للمبتدئين حتى المتقدمين، لذا يمكنك البدء من هنا أو من البداية والتقدم بسرعتك الخاصة. هذا هو الدرس 4 من أصل 4.

كم من الوقت يستغرق درس «نماذج الأخطاء الغنية باستخدام google.rpc.Status»؟

معظم دروس CoddyKit تستغرق حوالي 5–10 دقائق. كل منها موجز وتفاعلي، لذا تحرز تقدماً مستمراً وتستأنف من حيث توقفت عبر الويب والتطبيق.

هل يمكنني كتابة وتشغيل أكواد في درس gRPC & High Performance APIs هذا؟

نعم. كل درس في gRPC & High Performance APIs يتضمن محرر أكواد مدمج، لذا تكتب وتشغل أكواداً حقيقية مباشرة في متصفحك وتحصل على تعليقات فورية من الذكاء الاصطناعي — بدون إعداد محلي.

جميع الدروس في هذه الدورة

رموز الحالة ومعالجة الأخطاء
نقل البيانات الوصفية المخصصة
السياق والمهلات الزمنية
نماذج الأخطاء الغنية باستخدام google.rpc.Status

← العودة إلى gRPC & High Performance APIs