diff --git a/docs/ko/docs/tutorial/handling-errors.md b/docs/ko/docs/tutorial/handling-errors.md index 0b2f14f8f..349aac852 100644 --- a/docs/ko/docs/tutorial/handling-errors.md +++ b/docs/ko/docs/tutorial/handling-errors.md @@ -1,10 +1,10 @@ # 에러 처리 { #handling-errors } -API를 사용하는 클라이언트에게 에러를 알려야 하는 상황이 많습니다. +API를 사용하는 클라이언트에게 에러를 알려야하는 상황은 꽤나 많이 발생합니다. -클라이언트는 프론트엔드가 있는 브라우저일 수도 있고, 다른 사람의 코드일 수도 있고, IoT 장치일 수도 있습니다. +클라이언트는 프론트엔드가 있는 브라우저일 수도 있고, 다른 사람의 코드,혹은 IoT 장치일 수도 있습니다. -다음과 같은 상황을 클라이언트에게 알려야 할 수 있습니다: +클라이언트에게 에러를 알려야 할때: * 해당 작업에 대한 권한이 없음 * 해당 리소스에 접근할 수 없음 @@ -17,7 +17,7 @@ API를 사용하는 클라이언트에게 에러를 알려야 하는 상황이 400번대 상태 코드는 클라이언트에서 에러가 발생했다는 의미입니다. -**"404 Not Found"** 에러(그리고 농담들)를 기억하시나요? +**"404 Not Found"** 에러는 농담이나 드립으로 활용되아 아마 모두가 기억하고 있을겁니다. ## `HTTPException` 사용하기 { #use-httpexception } @@ -33,11 +33,11 @@ API를 사용하는 클라이언트에게 에러를 알려야 하는 상황이 파이썬 예외이므로 `return`이 아닌 `raise`를 사용합니다. -*경로 작동 함수* 내에서 호출하는 유틸리티 함수가 있다면, 그 함수 안에서 `HTTPException`을 발생시켰을 때 *경로 작동 함수*의 나머지 코드는 실행되지 않고, 요청이 즉시 종료되며 `HTTPException`의 HTTP 에러가 클라이언트로 전송됩니다. +*경로 동작 함수* 내에서 호출하는 유틸리티 함수가 있다면, 그 함수 안에서 `HTTPException`을 발생시켰을 때 *경로 동작 함수*의 나머지 코드는 실행되지 않고, 요청이 즉시 종료되며 `HTTPException`의 HTTP 에러가 클라이언트로 전송됩니다. -값을 반환하는 것보다 예외를 발생시키는 것의 이점은 의존성과 보안 섹션에서 더 명확해질 것입니다. +값을 반환하는 것보다 예외를 발생시키는 것이 왜 더 좋은 방식인지에 대해서는 의존성과 보안 섹션에서 더 명확히 알 수 있을것 입니다. -이 예제에서는 클라이언트가 존재하지 않는 ID로 항목을 요청하면 상태 코드 `404`의 예외를 발생시킵니다: +이 예제에서는 클라이언트가 존재하지 않는 ID로 요청을 보내면 상태 코드 `404`의 예외를 발생시킵니다: {* ../../docs_src/handling_errors/tutorial001.py hl[11] *} @@ -51,7 +51,7 @@ API를 사용하는 클라이언트에게 에러를 알려야 하는 상황이 } ``` -하지만 클라이언트가 `http://example.com/items/bar`(존재하지 않는 `item_id` `"bar"`)를 요청하면, HTTP 상태 코드 404("not found" 에러)와 다음 JSON 응답을 받습니다: +하지만 클라이언트가 `http://example.com/items/bar`(존재하지 않는 `item_id` `"bar"`)를 요청하면, HTTP 상태 코드 404("not found" 에러)와 다음과 같이 JSON 응답을 받게 됩니다: ```JSON { @@ -61,21 +61,17 @@ API를 사용하는 클라이언트에게 에러를 알려야 하는 상황이 /// tip | 팁 -`HTTPException`을 발생시킬 때 `detail` 매개변수에 `str`뿐만 아니라 JSON으로 변환 가능한 모든 값을 전달할 수 있습니다. +`HTTPException`을 발생시킬 때 `detail` 매개변수에 `str`뿐만 아니라 JSON으로 변환 가능한 모든 값(`dict`, `list` 등)을 전달할 수 있습니다. -`dict`, `list` 등을 전달할 수 있습니다. - -이들은 **FastAPI**가 자동으로 처리하여 JSON으로 변환합니다. +이를 통해 **FastAPI**가 자동으로 처리하여 JSON으로 변환하게 됩니다ㅡ /// ## 커스텀 헤더 추가하기 { #add-custom-headers } -HTTP 에러에 커스텀 헤더를 추가하는 것이 유용할 때가 있습니다. 예를 들어, 일부 보안 시나리오에서 말이죠. - -직접 사용할 필요는 거의 없습니다. +HTTP 에러에 커스텀 헤더를 추가하는 것이 유용할 때가 있습니다. 예를 들어, 보안과 관련된 부분이 있죠. -하지만 필요한 고급 시나리오를 위해 커스텀 헤더를 추가할 수 있습니다: +직접 사용할 필요는 거의 없습니다만, 필요한 상황에서는 커스텀 헤더를 추가할 수 있습니다: {* ../../docs_src/handling_errors/tutorial002.py hl[14] *} @@ -85,17 +81,13 @@ HTTP 에러에 커스텀 헤더를 추가하는 것이 유용할 때가 있습 여러분(또는 사용하는 라이브러리)이 `raise`할 수 있는 커스텀 예외 `UnicornException`이 있다고 가정해봅시다. -이 예외를 FastAPI에서 전역으로 처리하고 싶습니다. - -`@app.exception_handler()`로 커스텀 예외 핸들러를 추가할 수 있습니다: +이 예외를 FastAPI에서 전역으로 처리하고 싶은 경우에는 `@app.exception_handler()`로 커스텀 예외 핸들러를 추가할 수 있습니다: {* ../../docs_src/handling_errors/tutorial003.py hl[5:7,13:18,24] *} -여기서 `/unicorns/yolo`를 요청하면 *경로 작동*이 `UnicornException`을 `raise`합니다. - -하지만 `unicorn_exception_handler`가 이를 처리합니다. +여기서 `/unicorns/yolo`를 요청하면 *경로 동작*이 `UnicornException`을 `raise`하고, `unicorn_exception_handler`가 이를 처리합니다. -따라서 HTTP 상태 코드 `418`과 다음 JSON 내용의 깔끔한 에러를 받습니다: +결과적으로 HTTP 상태 코드 `418`과 다음 JSON 내용의 깔끔한 에러를 받습니다: ```JSON {"message": "Oops! yolo did something. There goes a rainbow..."} @@ -105,7 +97,7 @@ HTTP 에러에 커스텀 헤더를 추가하는 것이 유용할 때가 있습 `from starlette.requests import Request`와 `from starlette.responses import JSONResponse`를 사용할 수도 있습니다. -**FastAPI**는 개발자 편의를 위해 `starlette.responses`를 `fastapi.responses`로도 제공합니다. 하지만 사용 가능한 대부분의 응답은 Starlette에서 직접 가져옵니다. `Request`도 마찬가지입니다. +**FastAPI**는 개발자 편의를 위해 `starlette.responses`를 `fastapi.responses`로도 제공합니다. 하지만 사용 가능한 대부분의 응답은 Starlette에서 직접 가져오게 되며,`Request`도 마찬가지입니다. /// @@ -115,21 +107,17 @@ HTTP 에러에 커스텀 헤더를 추가하는 것이 유용할 때가 있습 이 핸들러들은 `HTTPException`을 `raise`하거나 요청에 유효하지 않은 데이터가 있을 때 기본 JSON 응답을 반환합니다. -이러한 예외 핸들러를 여러분만의 것으로 오버라이드할 수 있습니다. +이러한 예외 핸들러를 여러분들의 코드로 오버라이드할 수 있습니다. ### 요청 검증 예외 오버라이드하기 { #override-request-validation-exceptions } -요청에 유효하지 않은 데이터가 포함되면 **FastAPI**는 내부적으로 `RequestValidationError`를 발생시킵니다. +요청에 유효하지 않은 데이터가 포함되면 **FastAPI**는 내부적으로 `RequestValidationError`를 발생시키게 됩니다. -그리고 기본 예외 핸들러도 포함하고 있습니다. - -이를 오버라이드하려면 `RequestValidationError`를 임포트하고 `@app.exception_handler(RequestValidationError)`로 예외 핸들러를 데코레이트합니다. - -예외 핸들러는 `Request`와 예외를 받습니다. +또한,기본 예외 핸들러도 포함하고 있으며 오버라이드하려면 `RequestValidationError`를 임포트하고 `@app.exception_handler(RequestValidationError)`로 예외 핸들러를 데코레이터로 붙이면 예외 핸들러는 `Request`와 예외를 받습니다. {* ../../docs_src/handling_errors/tutorial004.py hl[2,14:16] *} -이제 `/items/foo`로 가면 다음과 같은 기본 JSON 에러 대신: +이제 `/items/foo`로 가면 다음과 같은 기본 JSON 에러가 아닌: ```JSON { @@ -146,7 +134,7 @@ HTTP 에러에 커스텀 헤더를 추가하는 것이 유용할 때가 있습 } ``` -다음과 같은 텍스트 버전을 받습니다: +다음과 같은 텍스트 에러메시지를 받습니다: ``` 1 validation error @@ -164,19 +152,17 @@ path -> item_id `RequestValidationError`는 Pydantic의 `ValidationError`의 서브클래스입니다. -**FastAPI**는 이를 사용하여 `response_model`에서 Pydantic 모델을 사용하고 데이터에 에러가 있는 경우 로그에서 에러를 볼 수 있게 합니다. +**FastAPI**는 이를 활용하여 `response_model`에서 Pydantic 모델을 사용하고 데이터에 에러가 있는 경우 로그에서 에러를 볼 수 있게 합니다. -하지만 클라이언트/사용자는 이를 보지 못합니다. 대신 HTTP 상태 코드 `500`과 함께 "Internal Server Error"를 받습니다. +하지만 클라이언트/사용자는 이를 보지 못합니다. 대신 HTTP 상태 코드 `500`과 함께 "Internal Server Error"를 받게 됩니다. -*응답*이나 코드 어딘가에(클라이언트 *요청*이 아닌) Pydantic `ValidationError`가 있다면 실제로는 코드의 버그이므로 이렇게 되어야 합니다. - -그리고 이를 수정하는 동안 클라이언트/사용자는 에러에 대한 내부 정보에 접근할 수 없어야 합니다. 보안 취약점을 노출할 수 있기 때문입니다. +*응답*이나 코드 어딘가에(클라이언트 *요청*이 아닌) Pydantic `ValidationError`가 있다면 실제로는 코드의 버그이므로 이를 수정하는 동안 클라이언트/사용자는 에러에 대한 내부 정보에 접근할 수 없어야 합니다. 보안 취약점을 노출할 수 있기 때문입니다. ### `HTTPException` 에러 핸들러 오버라이드하기 { #override-the-httpexception-error-handler } 같은 방식으로 `HTTPException` 핸들러를 오버라이드할 수 있습니다. -예를 들어 이런 에러들에 대해 JSON 대신 일반 텍스트 응답을 반환하고 싶을 수 있습니다: +예를 들어 이런 에러들에 대해 JSON 대신 일반 텍스트 응답을 반환하고 싶은 경우: {* ../../docs_src/handling_errors/tutorial004.py hl[3:4,9:11,22] *} @@ -192,7 +178,7 @@ path -> item_id `RequestValidationError`는 유효하지 않은 데이터와 함께 받은 `body`를 포함합니다. -앱 개발 중 이를 사용하여 본문을 로깅하고 디버그하거나 사용자에게 반환할 수 있습니다. +앱 개발 중에는 이를 활용하여 body를 로깅하고 디버그하거나 사용자에게 반환할 수 있습니다. {* ../../docs_src/handling_errors/tutorial005.py hl[14] *} @@ -205,7 +191,7 @@ path -> item_id } ``` -데이터가 유효하지 않다는 내용과 받은 본문을 포함한 응답을 받습니다: +데이터가 유효하지 않다는 내용과 받은 본문을 포함한 응답을 받게 될겁니다: ```JSON hl_lines="12-15" { @@ -228,17 +214,15 @@ path -> item_id #### FastAPI의 `HTTPException` vs Starlette의 `HTTPException` { #fastapis-httpexception-vs-starlettes-httpexception } -**FastAPI**는 자체 `HTTPException`을 가지고 있습니다. - -**FastAPI**의 `HTTPException` 에러 클래스는 Starlette의 `HTTPException` 에러 클래스를 상속받습니다. +**FastAPI**는 자체 `HTTPException`을 가지고 있으며, Starlette의 `HTTPException` 에러 클래스를 상속받습니다. -유일한 차이점은 **FastAPI**의 `HTTPException`은 `detail` 필드에 JSON으로 변환 가능한 모든 데이터를 허용하는 반면, Starlette의 `HTTPException`은 문자열만 허용한다는 것입니다. +유일한 차이점이라면 **FastAPI**의 `HTTPException`은 `detail` 필드에 JSON으로 변환 가능한 모든 데이터를 허용하는 반면, Starlette의 `HTTPException`은 문자열만 허용한다는 것입니다. -따라서 여러분의 코드에서 평소처럼 **FastAPI**의 `HTTPException`을 계속 발생시킬 수 있습니다. +이로 인해 코드에서 평소처럼 **FastAPI**의 `HTTPException`을 계속 발생시킬 수 있습니다. -하지만 예외 핸들러를 등록할 때는 Starlette의 `HTTPException`에 대해 등록해야 합니다. +하지만 예외 핸들러를 등록할 때는 Starlette의 `HTTPException`로 등록해야 합니다. -이렇게 하면 Starlette 내부 코드나 Starlette 확장/플러그인에서 Starlette `HTTPException`을 발생시켰을 때 여러분의 핸들러가 이를 잡아서 처리할 수 있습니다. +그렇게 해야만 Starlette 내부 코드나 Starlette 확장/플러그인에서 Starlette `HTTPException`을 발생시켰을 때 핸들러가 이를 잡아서 처리할 수 있습니다. 이 예제에서는 같은 코드에서 두 `HTTPException`을 모두 사용하기 위해 Starlette의 예외를 `StarletteHTTPException`으로 이름을 바꿨습니다: @@ -252,4 +236,4 @@ from starlette.exceptions import HTTPException as StarletteHTTPException {* ../../docs_src/handling_errors/tutorial006.py hl[2:5,15,21] *} -이 예제에서는 아주 설명적인 메시지로 에러를 출력하지만, 핵심은 이해할 수 있을 것입니다. 예외를 사용한 다음 기본 예외 핸들러를 재사용하면 됩니다. +이 예제에서는 아주 기본적인 메시지로 에러를 출력하지만, 핵심은 이해할 수 있을 것입니다. 예외를 사용한 다음 기본 예외 핸들러를 재사용하면 됩니다.