상태 코드 및 오류 처리
gRPC 상태 코드를 효과적으로 사용하고 서비스에서 적절한 오류 전파와 처리를 구현하는 방법을 배웁니다.
상태 코드 및 오류 처리은(는) CoddyKit의 무료 gRPC & High Performance APIs 강의입니다. 이것은 4개 중 1번째 강의입니다. 아래에서 전체 강의를 무료로 읽을 수 있으며, 내장 코드 에디터와 24/7 AI 튜터와 함께 브라우저에서 직접 실습할 수 있습니다. 이 강의는 gRPC & High Performance APIs 학습 경로의 일부이며, 진행 상황이 웹과 CoddyKit 앱에 동기화됩니다. gRPC & High Performance APIs 강의에는 총 4개의 강의가 포함되어 있습니다.
이 강의의 일부는 아직 번역되지 않았으며 영어로 표시됩니다.
Why Handle gRPC Errors?
In any robust application, errors are inevitable. How we handle them can make or break a system's reliability and user experience.
For distributed systems using gRPC, consistent error handling is crucial. It ensures that services can communicate problems clearly and clients can react appropriately.
Meet gRPC Status Codes
gRPC uses a standardized set of Status Codes to indicate the outcome of an RPC (Remote Procedure Call). These codes provide a universal way to understand why a call succeeded or failed.
Think of them like HTTP status codes, but specifically for gRPC. Some common ones include:
OK: The RPC completed successfully.NOT_FOUND: Resource not found (e.g., a user ID doesn't exist).INTERNAL: An unexpected error occurred on the server.UNAUTHENTICATED: The request lacks valid authentication credentials.
Protobuf Service Definition
Before we look at error handling, let's define a simple service in a .proto file. This defines the structure of our messages and the RPC methods.
We'll create a UserService with a GetUser method that takes a UserRequest and returns a User.
syntax = "proto3";
option java_multiple_files = true;
option java_package = "com.coddykit.grpc.error";
option java_outer_classname = "ErrorProto";
package errorhandling;
message UserRequest {
int32 id = 1;
}
message User {
int32 id = 1;
string name = 2;
string email = 3;
}
service UserService {
rpc GetUser (UserRequest) returns (User);
}Server-Side Error Signaling
On the server, when an operation fails, you don't throw a regular exception. Instead, you create a gRPC Status object with an appropriate code and description, then convert it to a StatusRuntimeException.
This exception is then sent back to the client via the responseObserver.onError() method, ensuring the client receives the standardized gRPC error.
Server Error Implementation
Try running this example. The server will respond with a NOT_FOUND error if you request any user ID other than 1.
import io.grpc.Server;
import io.grpc.ServerBuilder;
import io.grpc.Status;
import io.grpc.stub.StreamObserver;
import com.coddykit.grpc.error.ErrorProto.User;
import com.coddykit.grpc.error.ErrorProto.UserRequest;
import com.coddykit.grpc.error.UserServiceGrpc;
public class ErrorServer {
private static final int PORT = 50051;
public static void main(String[] args) throws Exception {
Server server = ServerBuilder.forPort(PORT)
.addService(new UserServiceImpl())
.build();
server.start();
System.out.println("Server started on port " + PORT);
server.awaitTermination();
}
static class UserServiceImpl extends UserServiceGrpc.UserServiceImplBase {
@Override
public void getUser(UserRequest request, StreamObserver<User> responseObserver) {
System.out.println("Received GetUser request for ID: " + request.getId());
if (request.getId() == 1) {
User user = User.newBuilder()
.setId(1)
.setName("Alice")
.setEmail("alice@example.com")
.build();
responseObserver.onNext(user);
responseObserver.onCompleted();
} else {
Status status = Status.NOT_FOUND.withDescription("User with ID " + request.getId() + " not found.");
responseObserver.onError(status.asRuntimeException());
}
}
}
}Client-Side Error Handling
On the client side, gRPC errors are typically received as StatusRuntimeException. You should wrap your gRPC calls in try-catch blocks to gracefully handle these exceptions.
Inside the catch block, you can inspect the Status object from the exception to determine the error code and description, allowing your client to respond intelligently.
Client Error Handling Demo
Run this client code after starting the server from the previous scene. Observe how it handles both a successful user lookup and a 'not found' error.
import io.grpc.ManagedChannel;
import io.grpc.ManagedChannelBuilder;
import io.grpc.StatusRuntimeException;
import com.coddykit.grpc.error.ErrorProto.User;
import com.coddykit.grpc.error.ErrorProto.UserRequest;
import com.coddykit.grpc.error.UserServiceGrpc;
public class ErrorClient {
private static final int PORT = 50051;
private static final String HOST = "localhost";
public static void main(String[] args) {
ManagedChannel channel = ManagedChannelBuilder.forAddress(HOST, PORT)
.usePlaintext() // For local testing without TLS
.build();
UserServiceGrpc.UserServiceBlockingStub blockingStub = UserServiceGrpc.newBlockingStub(channel);
// Scenario 1: User found
try {
UserRequest foundRequest = UserRequest.newBuilder().setId(1).build();
User user = blockingStub.getUser(foundRequest);
System.out.println("User found: " + user.getName());
} catch (StatusRuntimeException e) {
System.err.println("Error calling GetUser (found scenario): " + e.getStatus().getCode() + " - " + e.getStatus().getDescription());
}
System.out.println("\n--- Trying to get a non-existent user ---");
// Scenario 2: User not found (expected error)
try {
UserRequest notFoundRequest = UserRequest.newBuilder().setId(99).build();
User user = blockingStub.getUser(notFoundRequest);
System.out.println("User found (unexpected): " + user.getName()); // This line should not be reached
} catch (StatusRuntimeException e) {
System.err.println("Error calling GetUser (not found scenario):");
System.err.println(" Status Code: " + e.getStatus().getCode());
System.err.println(" Description: " + e.getStatus().getDescription());
} finally {
channel.shutdown();
}
}
}Effective Error Propagation
Proper error propagation is vital. When a gRPC service calls another internal service and encounters an error, it's often best to:
- Log the error with sufficient detail for debugging.
- Translate the error into an appropriate gRPC
Statuscode for the calling client. Don't expose internal system errors directly. - Avoid swallowing errors. Always handle them or re-throw them so they don't disappear silently.
Test Your Knowledge
You are building a gRPC service that performs a complex calculation. If the input data is invalid (e.g., negative numbers where only positive are allowed), which gRPC Status code is most appropriate to return?
Key Takeaways
You've learned the basics of gRPC error handling!
- gRPC uses standardized Status Codes to communicate RPC outcomes.
- Servers signal errors by creating a
Statusobject and callingresponseObserver.onError(). - Clients handle errors by catching
StatusRuntimeExceptionand inspecting itsStatusobject. - Always propagate errors clearly and translate them appropriately for clients.
This structured approach ensures reliable communication in your distributed systems.
자주 묻는 질문
“상태 코드 및 오류 처리” 강의는 무료인가요?
네 — “상태 코드 및 오류 처리” 전체 내용을 이 웹사이트에서 무료로 읽을 수 있습니다. 인터랙티브하게 실습하려면(내장 코드 에디터와 24/7 AI 튜터), CoddyKit PRO로 업그레이드하면 gRPC & High Performance APIs 강의 전체를 잠금 해제할 수 있습니다. gRPC & High Performance APIs 강의에는 총 4개의 강의가 포함되어 있습니다.
“상태 코드 및 오류 처리”에서 뭘 배우나요?
gRPC 상태 코드를 효과적으로 사용하고 서비스에서 적절한 오류 전파와 처리를 구현하는 방법을 배웁니다. 브라우저에서 직접 실행하는 실습 코드로 gRPC & High Performance APIs을(를) 배우며, 24/7 AI 튜터가 강의를 진행하면서 질문에 답변해줍니다.
gRPC & High Performance APIs을(를) 시작하는 데 경험이 필요한가요?
사전 경험은 필요하지 않습니다. CoddyKit의 gRPC & High Performance APIs은(는) 초급자부터 고급 학습자까지를 위해 구성되어 있으므로, 여기서 시작하거나 처음부터 시작할 수 있으며 자신의 속도대로 진행할 수 있습니다. 이것은 4개 중 1번째 강의입니다.
“상태 코드 및 오류 처리” 강의는 얼마나 걸리나요?
대부분의 CoddyKit 강의는 약 5~10분이 소요됩니다. 각 강의는 간결하고 인터랙티브하여 꾸준한 진행이 가능하며, 웹과 앱에서 중단한 부분부터 바로 시작할 수 있습니다.
이 gRPC & High Performance APIs 강의에서 코드를 작성하고 실행할 수 있나요?
네. 모든 gRPC & High Performance APIs 강의에는 내장 코드 에디터가 포함되어 있으므로, 브라우저에서 바로 실제 코드를 작성하고 실행한 후 즉시 AI 피드백을 받을 수 있습니다 — 로컬 설정이 필요 없습니다.