[ FastAPI ] 쿼리 매개변수와 문자열 유효성 검사

FastAPI는 추가적인 정보와 유효성 검사를 매개변수에 선언할 수 있게 해줍니다.

 

아래 애플리케이션 예시를 한 번 같이 살펴봅시다:

 

 

쿼리 매개변수 q 는 Optional[str] 자료형이고, 이는 곧 str 이면서 동시에 None 이 될 수 있다는 걸 의미하며, 실제로, 기본 값이 None 이게 됩니다, 따라서 FastAPI는 이것이 필수로 요구되지 않는다는 걸 알게 됩니다.

 

참고
FastAPI는 기본 값이 = None 이기 때문에 q 의 값이 필수로 요구되지 않는다는 걸 알 수 있습니다.

Optional[str] 속 Optional 은 FasAPI에 의해 사용되지는 않지만, 편집기가 더 잘 지원하며 오류를 찾아낼 수 있게 해줍니다.

 

추가적인 유효성 검사

q 가 선택 사항이지만, 값이 주어졌을 때, 그 길이가 50자를 초과하지 않도록 강제할 것입니다.

 

임포트 Query

이를 구현하기 위해서는, 우선 fastapi 로 부터 Query 를 임포트 하시기 바랍니다:

 

 

기본 값으로 사용되는 Query

그리고 이제 매개변수의 기본값으로 사용하여, 다음과 같이 매개변수 max_length 를 50으로 설정합니다:

 

 

기본 값 None 을 Query(None) 으로 대체했기 때문에, Query 의 첫 번째 매개변수는 기본 값을 정의한 것과 동일한 목적으로 사용됩니다.

 

따라서 다음과 같은 코드는:

 

 

... 다음과 동일하게, 매개변수를 선택 사항으로 만듭니다:

 

 

그러나 쿼리 매개변수로 명시적이게 선언됩니다.

 

정보
FastAPI는 다음과 같은 부분만을 신경씁니다:

= None

또는 다음과 같은 부분도 신경씁니다:

= Query(None)

그리고 쿼리 매개변수가 필수적으로 요구되지 않는다는 걸 감지하기 위해 None 을 사용할 것입니다.

Optional 은 단지 편집기가 더 효율적인 지원을 제공하는데 사용됩니다.

 

결국, 더 많은 매개변수를 Query 로 보낼 수 있습니다. 이 경우, max_length 매개변수는 문자열에 적용됩니다:

 

 

이것은 데이터의 유효성 검사를 진행하고, 만약 유효하지 않을 경우 명확한 오류와, OpenAPI 스키마 경로 동작 속 매개변수를 문서에서 보여줄 것입니다.

 

더 많은 검증 추가

물론 min_length 매개변수도 추가할 수 있습니다:

 

 

정규 표현식 추가

매개변수가 반드시 일치해야 할 정규 표현식을 정의할 수도 있습니다:

 

 

이러한 구체적인 정규 표현식은 전달 받은 매개변수의 값을 확인합니다:

 

• ^ : 다음에 오는 문자로 시작하는지 확인하며, 따라서 그 전에는 어떤 문자도 없어야 합니다.
• fixedquery : fixedquery 라는 정확한 값을 가져야 합니다.
• $ : 여기서 끝나야 하며, fixedquery 다음에 어떤 문자도 더 있어서는 안 됩니다.

 

만약 이 모든 "정규 표현식" 개념이 헷갈린다면, 걱정마시기 바랍니다. 이건 많은 사람에게 어려운 주제입니다. 정규 표현식 없이도 여전히 많은 작업을 할 수 있습니다.

 

그러나 만약 그것이 필요하고 사용하고 배워야 한다면, FastAPI에서 바로 사용할 수 있다는 걸 알고 계시기 바랍니다.

 

기본 값

None 을 기본 값으로 사용되는 첫 번째 인자로써 전달한 것과 동일한 방식으로, 다른 값을 전달 할 수 있습니다.

 

min_length 가 3 이고, 기본 값으로 "fixedquery" 를 갖는 q 쿼리 매개변수를 선언하길 원한다고 가정해봅시다:

 

 

참고
기본 값을 갖는 건 매개변수를 선택 사항으로 만들어줍니다.

 

요구되게 만들기

추가적인 유효성 검사나 메타 데이터를 선언 할 필요가 없다면, q 쿼리 매개변수를 다음과 같이 기본 값 없이 필수적으로 요구되게 만들 수 있습니다:

 

 

아래와 같은 방법 대신입니다:

 

 

그러나 이제 Query 를 사용하여, 다음과 같이 선언합니다:

 

 

따라서, Query 를 사용하여 값을 필수적으로 요구되게 선언하고 싶은 경우, ... 를 첫 번째 인자로 사용할 수 있습니다:

 

 

정보
... 를 한 번도 본 적이 없다면: 이것은 특별한 단일 값이므로, 파이썬 문법 중 하나인 "Ellipsis"를 참고하시기 바랍니다.

 

이것은 FastAPI에게 매개변수가 필수적으로 요구된다는 걸 알려줍니다.

 

쿼리 매개변수 리스트 / 다중 값

Query 를 사용하여 쿼리 매개변수를 명시적으로 정의할 때 리스트의 값을 전달 받거나, 다른 방식으로, 다중 값을 전달 받게 선언할 수 있습니다.

 

예를 들어, URL에 여러 번 등장하는 쿼리 매개변수 q 를 선언할 경우, 다음과 같이 작성할 수 있습니다:

 

 

 

그렇다면, URL은 다음과 같을 것입니다:

 

 

다중 q 쿼리 매개변수의 값 ( foo 와 bar ) 을 경로 동작 함수 내부의 파이썬 list 에서 함수의 매개변수 q 로 전달 받을 것입니다.

 

따라서, URL의 응답은 아래와 같습니다:

 

 

팁
위 예시와 같이, list 자료형으로 쿼리 매개변수를 선언하기 위해서는, 명시적으로 Query 를 사용해야 하며, 그렇지 않을 경우 요청 바디로 해석됩니다.

 

대화형 API 문서 또한 함께 수정되어, 다중 값이 반영되어 있을 것입니다:

 

 

기본 값을 사용한 쿼리 매개변수 리스트 /  다중 값

그리고 아무런 값도 주어지지 않았을 때의 list 기본 값을 정의할 수 있습니다:

 

 

만약 아래 주소에 접속해본다면:

 

 

q 의 기본 값은: ["foo", "bar"] 이고 응답은 아래와 같을 것입니다.

 

 

list 사용

List[str] 대신 list 를 직접 사용할 수도 있습니다:

 

 

참고
이 경우, FastAPI가 리스트의 콘텐츠를 확인하지 않는다는 걸 명심하시기 바랍니다.

예를 들어, List[int] 의 경우 리스트의 값이 정수형인지 확인 (그리고 문서화) 합니다. 그러나 list 만 쓸 경우 그렇지 않습니다.

 

더 많은 메타 데이터 선언

매개변수에 관한 더 많은 정보를 추가할 수 있습니다.

 

해당 정보는 생성된 OpenAPI에 포함되며 사용자 인터페이스 문서와 외부 도구에 사용됩니다.

 

참고
다른 도구는 다른 수준의 OpenAPI 지원을 받을 수 있다는 걸 명심하시기 바랍니다.

대부분의 경우, 누락된 기능이 이미 개발을 위해 계획되어 있지만, 그 중 일부는 아직 선언된 추가 정보를 표시하지 않을 수 있습니다.

 

다음과 같이 title 을 추가할 수 있습니다:

 

 

description 도 추가할 수 있습니다:

 

 

매개변수 벼링

item-query 라는 매개변수를 원한다고 상상해보시기 바랍니다.

 

아래와 같을 것입니다:

 

 

그러나 item-query 는 유효한 파이썬 변수명이 아닙니다.

 

가장 가까운 형태는 item_query 일 것 입니다.

 

그러나 정확히 item-query 를 원할 수 있습니다...

 

이럴 때 alias 를 선언하면, 이 별칭은 매개변수 값을 찾는 데 사용됩니다.

 

 

권장되지 않는 매개변수

더 이상 이러한 매개변수를 좋아하지 않는다고 가정해봅시다.

 

이것을 사용 중인 클라이언트 때문에 놔둬야 하지만, 문서에는 명확하게 사용이 권장되지 않는다고 표시하길 원합니다.

 

이럴 때 Query 에 deprecated=True 로 매개변수를 전달하시기 바랍니다:

 

 

그러면 문서는 아래와 같이 보여질 것입니다:

 

 

요약

추가적인 유효성 검사와 메타 데이터를 매개변수에 선언할 수 있습니다.

 

일반적인 유효성 검사와 메타 데이터는 다음과 같습니다:

 

• alias
• title
• description
• deprecated

 

문자열에 관한 세부적인 유효성 검사는 다음과 같습니다:

 

• min_length
• max_length
• regex

 

이러한 예시를 통해 str 값을 위해 어떻게 유효성 검사를 선언해야 하는지 알 수 있었습니다.

 

다음 챕터에서는 숫자형과 같은, 다른 자료형은 어떻게 유효성 검사를 선언하는지 알아보도록 합시다.