[python] API 디자인을 위한 코드 리팩토링 가이드

15 Dec 2023

python

API 디자인은 소프트웨어 개발에서 매우 중요한 부분입니다. 잘 설계된 API는 사용자들이 쉽게 이해하고 사용할 수 있도록 도와주며, 시스템의 유지보수성과 확장성을 향상시킵니다. 따라서 코드의 리팩토링은 API 디자인을 개선하는 데 매우 중요한 단계입니다.

이번 블로그에서는 API 디자인을 개선하기 위한 코드 리팩토링의 가이드에 대해 살펴보겠습니다.

1. 코드의 일관성 유지

API를 사용하는 개발자들이 예측 가능하고 일관된 경험을 할 수 있도록, API의 메서드, 클래스, 변수명 등을 일관성 있게 유지해야 합니다. 모든 API 요소들은 일관된 스타일과 패턴을 따라야 합니다.

예시:

# Bad example
def get_userInfo(): 
    pass

def FetchAllData():
    pass

# Good example
def get_user_info(): 
    pass

def fetch_all_data():
    pass

2. 의미 있는 네이밍 사용

의미 있는 이름을 사용하여 API의 기능과 동작을 명확하게 설명해야 합니다. 간결하면서도 명확한 네이밍은 API를 사용하는 사람들이 코드를 이해하고 사용하기 쉽게 도와줍니다.

예시:

# Bad example
def func(a, b):
    pass

# Good example
def calculate_total_price(quantity, unit_price):
    pass

3. 파라미터와 리턴 값 정의

API 메서드의 파라미터와 리턴 값은 명확하게 정의되어야 합니다. 이를 통해 사용자가 메서드를 호출할 때 필요한 입력값과 리턴되는 결과를 명확히 알 수 있습니다.

예시:

# Bad example
def get_data():
    pass

# Good example
def get_data(user_id: int) -> dict:
    pass

4. 에러 처리 및 예외 디자인

API 메서드는 예외 상황에 대한 적절한 처리 방법을 제공해야 합니다. 사용자가 잘못된 입력값을 전달했을 때나 시스템에 문제가 발생했을 때, 명확한 에러 메시지와 상황에 맞는 예외를 발생시켜야 합니다.

예시:

# Bad example
def divide(a, b):
    pass

# Good example
def divide(dividend: int, divisor: int) -> float:
    if divisor == 0:
        raise ValueError("Cannot divide by zero")
    return dividend / divisor

5. RESTful 디자인 원칙 준수

RESTful API를 디자인할 때 HTTP Method와 URL 구조를 일관성 있게 정의해야 합니다. 이를 통해 사용자들이 API의 동작을 쉽게 예측하고 이해할 수 있습니다.

예시:

# Bad example
GET /getAllUsers
POST /createNewUser

# Good example
GET /users
POST /users

API 디자인과 코드의 리팩토링은 서로 밀접하게 연관되어 있습니다. 좋은 API 디자인을 위해서 코드를 꾸준히 리팩토링하고 개선하는 것이 중요합니다. API를 사용하는 개발자들의 편리성과 시스템의 유지보수성을 고려하여 코드를 리팩토링하는 것이 좋은 API를 만드는 첫걸음입니다.

이상으로 API 디자인을 위한 코드 리팩토링 가이드에 대해 알아보았습니다.

목차

1. 코드의 일관성 유지

2. 의미 있는 네이밍 사용

3. 파라미터와 리턴 값 정의

4. 에러 처리 및 예외 디자인

5. RESTful 디자인 원칙 준수