양호한 API 설계에 대한 실용적인 제안

보기 드문 유튜브 회의에서 나는 조슈아 블로흐(Joshua Bloch, 고효율 자바라는 책의 저자)가 어떻게 잘 구축된 API와 그 중요성에 대한 강연을 만났다.보고 나서 나는 내가 반드시 필기를 해야 한다는 것을 알았다. 왜냐하면 강연이 너무 좋아서 나는 잊을 수 없기 때문이다.사실은 좋아요. 여러분과 나누고 싶어요.
Joshua는 많은 주제를 한 시간 안에 압축하여 API의 더욱 높은 차원 특징과 하나의 API를 구축하는 과정과 일부 구축 API의 실용적인 기교에 부합하도록 한다.우리 바로 시작합시다.
우선 API가 무엇인지 빠르게 살펴보겠습니다.영상에는 이 점이 소개되지 않았기 때문에 이미 알고 있다면 이 부분을 넘어가세요.
API(어플리케이션 프로그래밍 인터페이스)는 API의 배후 소프트웨어와 통신하는 방법을 계약으로 간주할 수 있습니다.그것은 얻을 수 있는 데이터, 데이터의 형식, 그리고 이 데이터에 대해 실행할 수 있는 조작을 정의했다.이것은 하나의 API가 성숙한 REST API일 수도 있고, 목록을 조작할 수 있는 일련의 방법이 될 수도 있다는 것을 의미한다.
브로흐의 견해에 따르면, 좋은 API를 설계하려면, 당신은 특정한 특성을 겨냥할 수 있다.

양호한 API의 특징

역학

문서가 없는 경우에도 사용하기 쉽습니다

.

오용 불가

코드를 쉽게 읽고 유지할 수 있음

요구 사항을 충족하는 강력한 성능

진화 용이

관객 맞춤

이러한 특징은 매우 추상적이고 실현하기 어렵지만 지도 방침으로 삼을 수 있다.이러한 특성을 어떻게 실현하는가가 본문의 나머지 부분의 중점이다.

API 구축 프로세스

API를 구축하는 첫 번째 단계는 수요에서 시작됩니다.그러나 섭외자가 제시한 해결 방안을 조심하고 용례를 추출해 보아야 한다.사용자가 원하는 것이 아니라 당신이 해결하려고 시도하고 있는 문제를 찾아라.
일단 네가 적당한 수요가 생기면 작은 일부터 시작해라.최대 한 페이지의 설명서를 쓰다.
이보다 더 큰 일이라면, 너의 자아는 몰입될 것이다.침몰 원가 오류론이 나타나기 시작하면 포기하는 것이 불편하다고 느낄 것이다.
변경을 진행하는 작업량은 매우 적기 때문에 피드백을 받기 시작하면 다시 쓰기 쉽다.당신이 해결하고자 하는 문제를 더 잘 이해하기 시작할 때만, 규범을 더욱 충실하게 해야 한다.
비록 상식에 어긋나게 들리지만, 즉시 API에 대한 인코딩을 시작해야 합니다.인터페이스를 만들어라. 모든 것을 지정하기 전에, 실현을 위해 고민하지 마라.그래도 API를 기반으로 코드를 작성하여 해당 동작이 예상대로 작동하는지 확인해야 합니다.이것은 너로 하여금 의외의 사고를 규명하고 방지하게 할 수 있다.
이러한 코드 세그먼트는 API를 위해 작성할 가장 중요한 코드일 수 있습니다.그것들은 예로 계속 존재할 수 있으니, 너는 그 위에 많은 시간을 들여야 한다.일단 API가 사용되면 복사된 예시 코드입니다.좋은 예는 당신이 API를 잘 사용할 수 있다는 것을 의미하기 때문에 그것들은 전형적이어야 한다.
그러나 API를 구축할 때 가장 중요한 것은

When in doubt, leave it out.

특히 공공 API를 구축할 때 사용자가 사용하기 시작하면 기능을 삭제할 수 없다.

실용적인 기교

간단하게 말하자면, 이 예들 중 많은 것들이 자바와 OOP (대상 프로그래밍) 을 기반으로 한 것이다.그러나 대부분의 컨텐트는 Java와 OOP 이외에도 여전히 적용됩니다.
API 하나면 뭐 하나 잘하고 있어야 돼.
기능은 해석하기 쉬워야 한다.만약 그것의 이름을 말하기가 매우 어렵다면, 그것은 통상적으로 나쁜 징조이다.좋은 API는 산문처럼 읽어야 한다.
한 곳에서 너무 많은 일을 하려고 하거나 비슷한 일을 할 때 그것을 함께 놓을 때 마음을 열어라.
API는 가능한 한 작아야 하지만 더 작아서는 안 된다
요구를 만족시키고 기타 요소를 고려하지 않다.언제든지 추가할 수 있지만 삭제할 수 없습니다.
API의 개념을 이해할 수 있는 수량을 고려하다.너는 API의 개념적 중요성을 고려하고 가능한 한 낮은 수준으로 유지해야 한다.
한 가지 방법은 가능한 한 인터페이스를 다시 사용하는 것이다.인터페이스를 다시 사용함으로써 사용자는 이 인터페이스를 한 번만 배울 수 있다.
API에 구현 세부 사항을 추가하지 마십시오.
클라이언트에게 세부 사항을 공개해서는 안 됩니다.구현을 변경하려면 API를 변경하기가 더 어렵습니다.
예를 들어 이상을 던지다.SQL 예외가 발생할 수 있지만, 더 높은 버전에서는 다른 형식의 데이터 저장을 원할 수도 있습니다.이제 파일을 쓰려고 해도 사용자가 SQL 이상을 기대하고 처리하기 때문에 SQL 이상을 버려야 합니다.
액세스 가능성 최소화
가능한 한 비밀을 지키다.이것은 클라이언트의 실현에 영향을 주지 않고 명칭을 유연하게 변경하고 실현할 수 있도록 합니다.
이름이 중요해요.
이 명칭들은 어느 정도는 자명해야 하며, 소형 언어와 같은 API를 고려해야 한다.이것은 그것의 명칭이 일치해야 한다는 것을 의미한다.같은 단어는 같은 일을 의미하고, 같은 뜻은 같은 일을 묘사하는 데 써야 한다.

// Does the same thing, but different names are used
fun remove()
fun delete()

문서 사항
잘 기록된 API 구성 요소가 재사용될 가능성이 더 큽니다.특히 상태나 부작용을 처리할 때 진지하게 기록한다.문서가 좋을수록 사용자가 겪는 오류는 줄어든다.
성능을 위해 API를 왜곡하지 마십시오.
양호한 API 설계는 일반적으로 양호한 성능과 일치한다.인터페이스를 사용하지 않고 유형을 변형시키거나 사용하면 성능을 제한할 수 있습니다.
API를 벤드업하여 성능을 향상시키면 API를 손상시킬 위험이 있습니다.예를 들어, 변할 수 없는 클래스를 만들면 더 적은 메모리를 사용할 수 있다.잠재적인 성능 문제는 해결될 것이지만 골치 아픈 문제는 영원히 존재한다.
가변성 최소화
좋은 이유가 없으면 종류는 변할 수 없을 것이다.가변이 필요하면 상태 공간을 최대한 작게 유지하세요.
의미가 있는 곳에서만 하위 클래스를 사용합니다
자류의 모든 실례가 초류의 실례라고 단도직입적으로 말할 수 있을 때만 자류를 사용할 수 있다.만약 답이 우렁찬 '예' 가 아니라면, 작문으로 대체해라.공개된 클래스는 단순히 코드를 다시 사용하기 위해 하위 클래스화되어서는 안 된다.
상속을 위한 설계와 문서입니다. 그렇지 않으면 상속을 금지합니다.
이것은 OOP에 적용됩니다.Avoid the fragile base class problem 기본 클래스에 대한 변경이 하위 클래스의 실현을 파괴할 수 있을 때 발생한다.
만약 피할 수 없다면, 방법을 어떻게 서로 사용하는지 상세하게 기록해 주십시오.가능한 한 실례 변수에 대한 접근을 제한하고 Getter와setter를 사용하여 기본 클래스의 실현을 제어합니다.
고객이 모듈에서 할 수 있는 어떤 일도 하지 못하게 하다
API로 하여금 항상 해야 할 일을 하게 하다.고객에게 템플릿 파일을 제공하지 마십시오.

// DON'T
val circle = CircleFactory.newInstance().newCircle()
circle.radius(1)
circle.draw()
// DO
val circle = CircleFactory.newCircle(radius = 0.5)
circle.draw()

최소 놀라움의 원칙을 운용하다
API 사용자는 행동에 놀라서는 안 됩니다.부작용을 피하거나 묘사적인 명칭으로 부작용을 묘사한다.
빠른 실패
오류가 발생한 후에는 가능한 한 빨리 보고해야 한다.컴파일할 때 가장 좋기 때문에 범형/정적 유형을 사용합니다.
모든 사용 가능한 데이터에 대한 프로그래밍 접근을 문자열로 제공합니다
문자열만 사용하면 형식과 컨텐트가 API의 일부가 되므로 변경할 수 없습니다.따라서 대상을 통해 문자열 내용에 대한 접근을 제공합니다.이렇게 하면 문자열의 형식과 내용에 대해 어떠한 약속도 할 필요가 없다.
지나치게 조심하다
행동이 같은 방법만이 다시 싣는다.자바 트리 집합 구조 함수의 경우 트리 집합 (Collection) 은 순서를 무시하고, 트리 집합 (SortedSet) 은 순서를 존중합니다.
적당한 매개 변수와 되돌아오는 형식을 사용합니다
입력에 대해서는 클래스가 아닌 인터페이스를 지원하지만 가장 구체적인 입력 매개 변수 형식을 사용합니다.더 좋은 유형이 존재하면string을 사용하지 마십시오.예를 들어 화폐 값도 이중 정밀도나 변동을 사용해서는 안 된다.
모든 방법에서 일치하는 매개 변수 순서를 사용하다
특히 매개변수 유형이 동일할 경우 실수로 매개변수를 교환할 수 있습니다.

fun copy(source: String, destination: String)
fun partialCopy(destination: String, source: String, numberToCopy: Int)

긴 매개변수 목록 피하기
세 개 이상의 매개 변수는 이상적이다.긴 직렬 유형이 같은 매개 변수는 유해할 수 있고 오류가 발생하기 쉽다.필요하면 함수를 분해하거나 도움말 클래스를 사용하여 파라미터를 저장합니다.
특별 취급이 필요한 반품 유형 방지
사용자가 특수 상황 코드를 작성하는 것을 잊어버리면 오류가 발생할 수 있습니다.비이상 유량도 충분한 상황에서 이런 상황을 피해야 한다.예를 들어, null 대신 길이가 0인 그룹이나 집합을 되돌려줍니다.
마지막으로, 실수를 기대해야 한다. 이것이 바로 처음부터 완벽한 API를 구축하는 것이 아니라, 일을 쉽게 바꿀 수 있는 요점에 대한 것이다.
이 강연도 보세요. 그는 나보다 훨씬 상세하게 말합니다.
나는 네가 이런 것들이 유용하다고 생각하고 평론에서 너의 생각이나 경험을 자유롭게 공유하기를 바란다.
읽어주셔서 감사합니다.❤️
리소스:
- 조슈아 브로흐Slides