FastAPI 기본

1. Fast API

Fast API는 파이썬으로 웹서버 프로그램을 쉽게 만들 수 있도록 도와주는 프레임워크로 개발자가 요청을 어떻게 처리할지에 대해서만 지정해 둔다면 FastAPI가 그걸 웹 서버 형태로 실행되도록 만들어준다.

여기서 웹 서버는 Uvicorn, Hypercorn과 같은 ASGI 서버가 띄워주고 FastAPI와 소통하면서 웹 서버 프로그램을 구동시킨다

조금 더 정리하면 사용자가 어떤 요청을 전달하면 이를 Uvicorn, Hypercorn과 같은 ASGI 서버가 받아서 FastAPI에게 전달하고 FastAPI는 이를 정리하여 필요한 곳에 전달하고 로직을 수행한 후에 결과 응답을 다시 ASGI서버로 전달하는 역할을 한다.

 

ASGI서버

기존에는 WSGI라고 Web Server Gateway Interface라는 표준이 있었으나 해당 방식은 동기적인 방식만을 지원했고 이를 Flask, Django(구버전)과 같은 프레임워크에서 사용했었다

그런데 최근에는 동시에 여러가지 요청을 처리하고 WebSocket을 지원하는 등의 비동기 프로그래밍의 중요성이 대두되면서 이를 위한 새로운 프로토콜이 필요했는데 이때 나온게 ASGI이다

ASGI란  Asynchronous Server Gateway Interface로 파이썬 웹 프레임워크(FastAPI, Django, Starlette등)와 네트워크 서버(Uvicorn, Hypercorn)이 서로 소통할 수 있도록 만든 공식 표준 규칙이다.

쉽게 말하자면 프레임워크와 서버가 서로 소통할 수 있도록 만들어둔 프로토콜(대화법)이라고 보면된다.

 

대표적인 ASGI 서버는 Uvicorn, Hypercorn, Daphne이 있는데 이들은 네트워크 포트를 열고 HTTP 요청을 받으며 해당 요청을 ASGI 규칙에 맞춰서 FastAPI 같은 프레임워크에 전달해주고 이에 대한 응답을 받아 다시 클라이언트에게 돌려주는 역할을 한다.

 

정확한건 실제로 서버를 만들어보면서 파악하는 것이 좀 더 이해하기가 쉬울듯 하다.

확인해보면서 이해하도록 하자.

 

2. 설치

우선 FastAPI를 설치할때 위에서 말했다 싶이 사용자의 요청을 받아줄 ASGI서버가 필요하다 

그렇기에 FastAPI와 Uvicorn을 같이 설치하고자 하는데 설치하기 위해서는 pip를 사용해 라이브러리를 설치해줘야하만 한다.

>> pip install fastapi uvicorn

 

3. FastAPI 기본 - 서버 실행, URL 맵핑

먼저 FastAPI를 Import 해주고 

FastAPI의 생성자를 호출해 객체로 만들어 변수에 담아준다.

그리고 이제 단순하게 함수를 하나 만들어주는데 

이 위에 데코레이터로 @를 붙인 후  app.get("URL")을 넣어주면 

get요청으로 /라는 URL로 접근하면 해당 함수에서 받아준다

 

이제 이렇게 만든 서버를 실행해주기 위해서는 ASGI서버를 켜줘야 하는데 우리는 uvicorn을 사용하기에 uvicorn을 실행하는 명령어를 실행해주자.

uvicorn으로 서버를 실행하는 명령어는 uvicorn 파일명:app --reload로 각각의 파트를 설명해보면 

uvicorn 파일명:app --reload

• uvicorn → 실행할 ASGI 서버 프로그램 이름
• 파일명:app → 실행할 FastAPI 앱을 지정하는 부분으로 해당 파일 내부에 있는 FastAPI 인스턴스(객체)를 담은 변수 이름을 쓰면 된다.
  또한 파일 명은 확장자 .py를 제외한 이름을 넣어주면 된다.
• --reload → 코드가 바뀌면 서버를 자동으로 재시작하는 옵션

으로 구성되어 있다.

한번 실행해보면 

이렇게 서버가 켜지는 것을 볼 수 있다.

 

브라우저를 통해서 해당 경로로 접근하면

이렇게 우리가 만든 응답이 반환되는 것을 볼 수 있다.

 

만약 인스턴스를 받는 객체의 이름을 apptest로 변경한다면

이 명령어로 실행을 하면

이렇게 ASGI app을 로드할 수 없다고 알린다 

명령어도 인스턴스에 맞게 변경을 해줘야만 한다 

 

여기서 추가로 간단하게 python명령만으로 서버를 여는 방법이 있는데 아래와 같이 해당 파이썬 파일을 바로 실행할 때 실행될 코드를 uvicorn을 사용해서 실행하도록 하는 방법이다.

이때 설정은 파일명:FastAPI인스턴스명 을 첫번째로 host에는 문자열로 host를 넣어주고, port를 숫자로 넣어주고 재시작을 자동으로 해주는 reload 설정을 True로 넣어주면 된다

이렇게 하면 python 파일명.py로 실행이 가능해진다.

4. FastAPI 기본 - get요청에서 파라미터 받기

get요청을 보낼때 문자열을 같이 전달하면 파라미터로 받아 변수에 담아 사용이 가능하다.

간단한 내용이라 예시를 확인해서 방법을 알아보도록하자 

먼저 단순한 함수를 하나 만들고 

이제 위에 데코레이터로 get 요청에 대한 맵핑을 해주고 

그뒤에 중괄호로 변수명을 넣어준다.

이렇게 한 후에 해당 변수에 대한 타입을 함수의 매개변수쪽에 함수명과 함께 넣어준다.

타입이 없어도 상관은 없다. 그치만 지정이 가능하다는 점

이제 이 변수는 함수 내부에서 사용이 가능하고 해당 변수를 응답에 담아 보내보면 

요청을 보낼 때 /param 뒤에 /값을 넣어주면

이렇게 해당 값이 함수 내부에서 사용된다.

 

5. Swagger UI

Swagger UI는 API를 문서화하고 테스트할 수 있게 해주는 웹 인터페이스로 서버가 제공해주는 API 설명서를 자동으로 만들어주고 그 안에서 직접 버튼을 눌러가면서 API를 테스트할 수 있게 만들어진 인터페이스이다.

 

기본적으로 FastAPI는 자동 문서화 기능이 내장되어 있고 서버를 띄우고 나서 URL 뒤에 docs를 붙여주면 Swagger UI 화면이 나온다.

한번 확인해보면 내 로컬에서 띄운 서버는 127.0.0.1:8000으로 되어 있기에 127.0.0.1/docs로 요청을 보내면 

이렇게 Swagger UI가 나온다.

 

비슷한 것으로 docs대신에 redoc을 붙여서 요청을 보내면 

이렇게 다른 스타일의 명세 화면이 출력된다.

 

이전에 만든 param 에 대한것을 눌러보면

이렇게 어떤 파라미터를 받고 어떤 형태로 성공적인 응답이 반환되는지를 볼 수 도 있고 우측 위쪽에 Try it out을 누르면 

이렇게 직접 파라미터를 입력해서 요청을 보낼 수 도 있다

요청을 한번 보내보면 

이렇게 어떤 식으로 요청을 보내면 어떤 응답을 받을 수 있는 지에 대해서 확인할 수 있다.

 

6. 동일한 중간 경로의 처리

기존에 우리는 아래와 같이 param이라는 경로 뒤에 오는 문자열을 값으로 받아들이기로 했었다.

근데 만약에 /param/id라는 값과 맵핑되어 있는 함수가 있다면 어떻게 될까 ?
위 함수의 바로 아래에 해당 함수를 만들었고 

해당 경로로 요청을 보내보자.

그 위에 변수를 받는 경로로 들어가버리는 것을 볼 수 있다.

이렇게 만약 응답을 값으로 인식하는 함수가 존재한다면 이들 순서를 지정해서 파라미터를 받는 함수는 동일 중간 경로에 해당하는 함수들의 가장 마지막에 존재해야한다.

이래야 해당 요청을 먼저 낚아 채서 가지고 들어갈 수 있기 때문이다.

이렇게 하고 다시 요청을 보내보면

우리가 바라던 대로 요청이 들어가는 것을 볼 수 있다.

 

7. 요청에서 받을 파라미터를 미리 지정하기

기존에 param으로 요청을 할때는 어떤 파라미터든 문자열이라면 받아서 전달을 했었는데 이 변수를 서버 측에서 미리 지정해둘 수 도 있다.

이때는 Enum을 활용해서 지정을 한다.

먼저 Enum을 import 하고 

 

str과 Enum을 상속하는 서브 클래스를 하나 임의로 생성해주자.

이를 선언함으로써 API문서에서는 값이 String형임을 인식하고 문서에 표기하게 된다.

이제 내부에다 받고 싶은 파라미터에 해당하는 내용을 넣어주고

받는 파라미터의 타입을 해당 클래스의 타입으로 설정한다

이렇게만 해도 Swagger UI에서 요청에 대해서 

설정한 값으로만 요청을 보낼 수 있게 제한한다.

만약 이때 해당 클래스의 값 리스트에 없는 값을 담아 요청을 보낸다면 

이렇게 에러에 대한 내용을 반환한다.

해당 내용을 천천히 보면 

• "type":"enum" → 열거형(enum)의 검증에서 발생한 오류로
• "loc":["path", "param"] → 에러가 발생한 위치는 path(URL 경로)에서 발생한 에러로 그 변수의 이름이 "param"이고
• "msg": "Input should be 'param1', 'param2', 'param3' → 해당 변수에 허용되는 값은 param1, param2, param3 인데
• "input":'test' → 그런데 너가 보낸 값은 test임
• "ctx" : {"expected": " 'prarm1', 'param2', 'param3' "} → 내가 원하는 값은 param1, param2, param3 니까 그안에서 보내라

라는 의미이다.

 

그리고 이 값은 나중에 열거형의 값으로 비교하여 분기 처리의 도구로써도 사용이 가능하다.

 

8. 파라미터로 경로를 받는 요청에 대한 처리

만약 파라미터를 파일의 경로인 /home/text/test.txt를 받고 싶다면 그냥 단순하게 담아서 보내면 어떻게 될까

먼저 이를 받기 위한 함수를 하나 선언해주고 

요청을 보내보자.

이렇게 요청을 담당할 함수 자체를 찾지를 못하는 것을 볼 수 있다

 

이렇게 경로를 받고 싶을때는 Starlette의 옵션을 직접 사용해서 URL 맵핑 부에서 path를 포함하는 경로 매개변수를 선언하는 것이 가능하다.

방법은 아래와 같이 맵핑부의 변수이름 뒤에 : 콜론을 붙인 후에 path라는 문자열을 같이 넣어주면 된다.

 

한번 요청을 보내보면 

이렇게 값을 받아오는 것을 볼 수 있다.

만약 경로의 맨 앞에도 /가 필요하다면 같이 전달하면 된다.