使用 google.rpc.Status 构建丰富的错误模型
不再局限于简单状态码，学习如何使用 google.rpc.Status 模型和标准错误详情类型附加结构化、机器可读的错误详情。
使用 google.rpc.Status 构建丰富的错误模型 是 CoddyKit 上的免费 gRPC & High Performance APIs 课时。 这是第 4 节课，共 4 节。 你可以在下方免费阅读本课时的完整内容 — 然后在浏览器中使用内置代码编辑器和全天候 AI 导师进行实践。 这是 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
Anypayloads
Standard Detail Types
Google defines reusable detail messages in google/rpc/error_details.proto:
BadRequest— field violationsRetryInfo— when to retryQuotaFailure— limit exceededErrorInfo— 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.reasonvalues stable and documented - Pair
RetryInfowith 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.Statuscarries code, message, and repeated detailAnypayloads- Standard types:
BadRequest,RetryInfo,QuotaFailure,ErrorInfo - Build with
WithDetails, read with a type switch overDetails() - Details travel in the
grpc-status-details-bintrailer - Standard types give cross-language consistency
用 AI 导师学习 gRPC & High Performance APIs — 免费
在浏览器中编写并运行真实代码，获得全天候 AI 导师的即时帮助，并在网页或应用中继续学习。
- 课程
- 12
- 课程
- 48
常见问题解答
「使用 google.rpc.Status 构建丰富的错误模型」课时是免费的吗？
是的 — 「使用 google.rpc.Status 构建丰富的错误模型」的完整文本可在网页上免费阅读。要进行交互式练习（内置代码编辑器和全天候 AI 导师）并解锁 gRPC & High Performance APIs 课程的其余内容，请升级到 CoddyKit PRO。 gRPC & High Performance APIs 课程共包含 4 节课。
「使用 google.rpc.Status 构建丰富的错误模型」这节课中我会学到什么？
不再局限于简单状态码，学习如何使用 google.rpc.Status 模型和标准错误详情类型附加结构化、机器可读的错误详情。 你通过在浏览器中直接运行的动手代码来练习 gRPC & High Performance APIs，全天候 AI 导师会在你学习这节课的过程中回答你的问题。
学习 gRPC & High Performance APIs 需要有经验吗？
无需任何先前经验。CoddyKit 上的 gRPC & High Performance APIs 课程适合初学者到高级学习者，你可以从这里开始或从头开始，按照自己的节奏学习。 这是第 4 节课，共 4 节。
「使用 google.rpc.Status 构建丰富的错误模型」课时需要多长时间？
大多数 CoddyKit 课程大约需要 5–10 分钟。每节课都很精短且互动，所以你能稳步进步，并在网页和应用中从离开的地方继续。
我能在这节 gRPC & High Performance APIs 课中编写并运行代码吗？
能。每节 gRPC & High Performance APIs 课都包含内置代码编辑器，你可以在浏览器中直接编写并运行真实代码，并获得即时 AI 反馈 — 无需本地设置。