자바 API 디자인:

자바 프레임워크 아키텍트가 알려주는

API 설계 이론과 실제

책2.indb 1 2015-04-28 오후 2:34:04

목차4

01이론과 정당성

PART

저자 소개 10

감사의 글 11

들어가며 12

1장: 현대 소프트웨어 구축의 예술 33

합리주의, 경험주의, 무지 34

지금까지의 소프트웨어의 진화 37

거대한 기반 요소 39

아름다움, 진리, 우아함 40

더 무지해져라! 43

2장: API를 만드는 이유 46

분산 개발 47

애플리케이션 모듈화 50

비선형적인 버전 관리 54

중요한 것은 의사소통이다 56

경험적 프로그래밍 58

첫 번째 버전은 늘 쉽다 60

3장: 훌륭한 API를 결정하는 요소 62

메서드와 필드 시그너처 63

파일과 파일의 내용 64

환경변수와 명령줄 옵션 66

API로서의 텍스트 메시지 67

프로토콜 69

책2.indb 4 2015-04-28 오후 2:34:10

목차 5

동작 방식 72

I18N 지원과 L10N 메시지 73

넓은 의미의 API 75

API의 품질을 검사하는 법 75

4장: 시시각각 변하는 표적 82

첫 번째 버전은 결코 완벽하지 않다 83

하위 호환성 84

유스 케이스 지향의 중요성 96

API 검토 100

API의 생명주기 101

점진적 향상 106

책2.indb 5 2015-04-28 오후 2:34:10

목차6

5장: 필요 이상으로 노출하지 마라 115

메서드가 필드보다 낫다 117

생성자보다 팩터리가 낫다 119

모든 것을 final로 만들어라 121

어울리지 않는 곳에 설정자 메서드를 넣지 마라 123

프렌드 코드에서만 접근하는 것을 허용하라 124

객체를 만든 이에게 더 많은 권한을 부여하라 129

깊은 계층구조를 노출하지 마라 136

6장: 구현이 아닌 인터페이스를 대상으로 코드를 작성하라 139

메서드나 필드 제거하기 142

클래스나 인터페이스를 제거하거나 추가하기 143

기존 계층구조에 인터페이스나 클래스 집어넣기 143

메서드나 필드 추가하기 144

자바 인터페이스와 클래스 비교 146

외유내강 147

메서드를 추가하길 좋아하는 사람들의 천국 149

추상 클래스는 유용한가? 152

매개변수 증가를 위한 대비 153

인터페이스 대 클래스 156

7장: 모듈화 아키텍처를 사용하라 157

모듈화 설계의 유형 161

상호컴포넌트 룩업과 통신 165

확장점 작성하기 181

순환 의존성의 필요성 183

Lookup은 어디에나 있다 189

Lookup의 남용 195

02실제 설계

PART

책2.indb 6 2015-04-28 오후 2:34:10

목차 7

8장: 클라이언트와 제공자를 위한 API를 분리하라 199

C와 자바로 API/SPI 표현하기 200

API 진화는 SPI 진화와 다르다 203

Writer의 자바 1.4와 자바 1.5 사이의 진화 204

API를 적절히 나눠라 219

9장: 테스트 용이성을 염두에 둬라 224

API와 테스트 226

명세의 쇠퇴 230

좋은 도구는 API를 더 사용하기 쉽게 만든다 233

테스트 호환성 도구 235

10장: 다른 API와 협동하기 239

다른 API를 사용하는 것을 조심하라 240

추상화 누출 246

API의 일관성 강제하기 247

위임과 합성 252

API를 잘못 사용하지 않게 하라 263

자바빈 리스너 패턴을 남용하지 마라 268

11장: API의 런타임 측면 273

고치기 여정 276

신뢰성과 무지 280

동기화와 교착상태 283

재진입성 호출 대비 314

메모리 관리 318

12장: 선언형 프로그래밍 324

객체를 불변적으로 만들어라 328

불변적인 동작 방식 333

문서의 호환성 334

책2.indb 7 2015-04-28 오후 2:34:10

목차8

13장: 해로운 것으로 여겨지는 극단적인 조언 341

API는 아름다워야 한다 343

API는 정확해야 한다 344

API는 단순해야 한다 347

API는 성능이 좋아야 한다 349

API는 100퍼센트 호환성을 갖춰야만 한다 350

API는 대칭적이어야 한다 354

14장: API 설계의 역설 356

API 이중 사고 358

보이지 않는 일 362

안정적인 API를 약속하는 두려움 극복하기 363

유지보수 비용 최소화하기 367

15장: API 우주의 진화 372

망가진 라이브러리 되살리기 375

의식적 업그레이드 대 무의식적 업그레이드 382

대체 동작 방식 386

비슷한 API의 연계와 공존 394

16장: 협동 작업 409

코드를 커밋하기 전에 검토 절차 밟기 410

개발자들이 API를 문서화하도록 설득하기 414

빅 브라더는 잠들지 않는다 417

API 패치 수락하기 423

17장: 게임을 활용한 API 설계 실력 향상 426

개요 427

1일차 429

2일차 444

03일상 생활

PART

책2.indb 8 2015-04-28 오후 2:34:11

목차 9

3일차: 평가의 날 453

여러분도 해보시길! 464

18장: 확장 가능한 비지터 패턴 사례 연구 465

추상 클래스 471

진화 준비 473

기본 탐색 476

명확한 버전 정의 479

비단조적 진화 482

인터페이스를 사용하는 자료구조 484

클라이언트 비지터와 제공자 비지터 485

삼중 디스패치 489

비지터를 위한 행복한 결말 492

편의성 문법 492

19장: 시한부 절차 496

명세 버전의 중요성 498

모듈 의존성의 중요성 499

제거된 부분을 영원히 놔둬야 하는가? 502

모놀리식 API 나누기 503

후기 507

참고 문헌 522

책2.indb 9 2015-04-28 오후 2:34:11

10

야로슬라프 툴라흐(Jaroslav Tulach )는 나중에 썬에 인수된 넷빈즈의 설립자

이자 초기 아키텍트다. 넷빈즈의 기반이 되는 기술을 만든 사람으로서 지금도 넷

빈즈 오픈소스 프로젝트의 성공에 기여하는 모든 프로그래머들의 설계 실력을

향상시키는 방법을 모색하는 프로젝트를 진행하고 있다.

저자 소개

책2.indb 10 2015-04-28 오후 2:34:11

11

내가 지금까지 만난 최고의 편집자인 게르트얀(Geertjan )과 패트릭(Patrick )

의 도움이 없었다면 이 책은 쓸 수 없었을 것이다. 그 밖의 다른 모든 분들께도

정말 감사드린다. 더 자세한 사항은 http://thanks.apidesign.org를 참고한다.

감사의 글

책2.indb 11 2015-04-28 오후 2:34:12

들어가며

또 한 권의 설계 책인가?

책2.indb 12 2015-04-28 오후 2:34:12

13 들어가며: 또 한 권의 설계 책인가?

“프로그래밍 세계에는 이미 설계 책이 충분하다”라고 생각할지도 모르겠다. 사실 너무나도 많아서

내가 왜 또 한 권의 설계 책을 쓰려고 하는 것인지(그리고 특히 왜 여러분이 읽어야 할지) 묻는 것도

이해가 된다. 특별히 객체 지향 시스템의 디자인 패턴에 관해서는 『디자인 패턴: 재사용성을 지닌 객

체지향 소프트웨어의 핵심 요소』1가 있다. 이 책은 이른바 “4인조(Gang of Four )”가 쓴 책으로, 객

체 지향 언어를 이용하는 모든 개발자가 반드시 읽어야 하는 책이다. 더불어 디자인 패턴을 설명하

는 데 특화된 책도 많으며, 그러한 책은 모두 특정 유형의 애플리케이션을 작성할 때 유용하다. 게다

가 비공식적인 자바 프로그래머의 바이블인 『이펙티브 자바』2도 있다. 이러한 사실을 감안하면 또 한

권의 설계 책이 정말로 필요할까?

나는 그럴 필요가 있다고 생각한다. 나는 넷빈즈 API (Application Programming Interface )를

1997년부터 설계해왔다. 나는 프레임워크나 공유 라이브러리를 설계하는 사람이 거칠 수 있는 거

의 모든 단계를 거쳐왔다. 초창기에는 자바 언어의 감을 천천히 익히면서 다른 언어에서 효과적이라

고 알고 있던 코드 작성 스타일을 적용해보려고 노력했다. 그 이후로 자바에 유창해졌다. 그 당시에

는 자바로 작성한 내 코드에 다양한 패턴들을 적용하는 것이 너무 간단해 보였다. 이윽고 겉으로 보

이는 것만큼 늘 간단하지만은 않다는 사실을 깨달았지만 말이다. 나는 전통적인 패턴들이 넷빈즈 같

은 객체 지향 애플리케이션 프레임워크에는 적절하지 않으며, 완전히 다른 기술이 필요하다는 사실

을 깨달았다.

가장 오래된 넷빈즈 API는 1997년에 설계됐다. 그중 일부는 여전히 사용되고 있으며, 10년간의 서

비스 이후에도 적절히 동작하고 있다. 솔직히 말하자면 처음 설계됐을 때와는 정확히 같은 API가

아니었지만 말이다. 시간이 지나면서 새로운 요구사항을 수용하고 라이브러리의 기능을 확장하며,

초보자의 실수를 고쳐야 했다. 그럼에도 API 클라이언트는 여전히 자신이 작성하고 컴파일한 코드

를 실행할 수 있다. 요즘 나오는 최신 버전의 라이브러리를 사용하는 경우에도 말이다. 이것은 우리

가 늘 가능한 한 하위 호환성을 유지하기 위해 노력했기 때문에 가능한 일이다. 그 결과, 10년이 넘

은 라이브러리를 대상으로 작성된 프로그램이 현재 버전에서도 동작할 가능성이 높다. 이러한 투자

보전, 즉 하위 호환성을 보장하는 방식으로 라이브러리를 진화하게 한 결정은 일반적인 설계 책, 최

소한 내가 지금까지 읽어본 책에서는 볼 수 없는 내용이다. 모든 넷빈즈 API가 문제 없이 진화한 것

1 에릭 감마, 리처드 헬름, 랄프 존슨, 존 블라시디스 지음, GoF의 디자인 패턴: 재사용성을 지닌 객체지향 소프트웨어의 핵심 요소(Design Patterns: Elements of Reus-

able Object-Oriented Software), 피어슨에듀케이션코리아(PTG), 2007

2 조슈아 블로크 지음, 이병준 옮김, 이펙티브 자바(Effective Java), 인사이트, 2014

책2.indb 13 2015-04-28 오후 2:34:12

자바 API 디자인: 자바 프레임워크 아키텍트가 알려주는 API 설계 이론과 실제14

은 아니지만 넷빈즈 팀은 이제 이 기술을 높은 수준까지 익혔다고 생각하며, 이 기술이 다른 프로그

래머들에게도 폭넓게 필요할 것이라고 생각한다. 이러한 이유로 이 책의 상당 부분은 하위 호환성을

유지하는 것과 하위 호환성을 보장하는 방식으로 유지보수하는 데 적합한 코드를 제작하는 특별한

API 설계 패턴에 관한 내용에 할애했다.

넷빈즈 프로젝트를 진행할 때 직면한 또 하나의 도전과제는 협동 작업의 확장성이었다. 1997년 당

시에는 API를 내가 직접 작성했다. 다른 넷빈즈 엔지니어들은 “그냥” 코드를 작성했다. 즉, 계속해

서 내가 제공한 API를 활용하면서 다양한 넷빈즈 IDE의 사용자 인터페이스와 구현체를 만들었다.

그 결과, 자연스럽게 병목지점이 생겨났다. 다양한 넷빈즈 IDE의 기능을 작업하는 사람의 수가 늘

어나 API에 대한 수요를 한 명의 “아키텍트”가 처리하기에는 벅찰 정도가 된 것이다. 시간이 지나면

서 변화가 절실해졌다. 우리는 넷빈즈 개발팀의 대다수가 직접 API를 설계할 수 있기를 바랬다. 동

시에 사람들이 만든 API 간에 일정 수준의 일관성도 유지하고 싶었다. 이것은 큰 문제로 발전했는

데, 개발자들이 일관성을 보장하고 싶지 않았기 때문이 아니라 내가 일관성의 의미를 개발자들에게

설명할 수 없었기 때문이다. 어쩌면 여러분은 뭔가를 조리 있게 설명하는 방법을 모르는 상태에서

도 뭔가를 하는 방법을 알고 있다는 느낌을 알지도 모르겠다. 이게 바로 내가 처한 상황이었다. 나는

API를 어떻게 설계하는지 알고 있다고 생각했지만 다른 사람들이 따랐으면 하는 가장 중요한 제약

조건을 가까스로 공식화하기까지 수개월이 걸렸다.

늦은 밤의 API 이야기

나는 API 설계 및 API 공표에 대해 오랫동안 관심이 있었다. 나는 이 주제로 썬 마이크로시스템즈 내에서, 그리고 넷빈즈 협

력사를 대상으로 갖가지 강연을 했다. 그러나 이 주제와 관련된 나의 첫 공개 강연은 샌 프란시스코에서 열린 자바원 2005

에서 한 것이었다. 친구인 팀 부드로(Tim Boudreau)와 나는 “오랫동안 건재할 API를 작성하는 법”이라는 제목으로 제안서

를 제출했다. 강연은 오후 10시 30분에 시작하는 것으로 예정됐는데, 아마도 제안서 초록에 “Ajax”나 “웹 2.0” 같은 유행어

가 포함돼 있지 않았기 때문일 것이다. 그 야심한 시각은 강연을 하기에는 적당하지 않았는데, 파티, 공짜 맥주, 기타 늦은

밤에 집중력을 떨어뜨리는 것들과 경쟁해야 했기 때문이다. 우리는 비관적이었고 한두 명만이 우리를 위로해주기 위해 나

타날 것이라고 예상했다. 강연 장소에 도착했을 때 바로 옆 방의 JDBC 드라이버 강연이 있을 곳을 보고는 기분이 더욱 안

좋아졌다. JDBC 강연장 복도에는 사람들로 가득 차 있었다. 우리는 그곳에 있는 사람들이 모두 데이터베이스 관련 주제에

관심이 있는 이들일 거라고 생각했다. 하지만 놀랍게도 거기에 있던 대부분의 사람들은 우리 강연을 기다리고 있던 것이었

다! 발표장은 금방 채워졌다. 전 좌석이 찼고, 사람들은 바닥에 앉거나 벽에 기대 서기 시작했다. 심지어 문을 열어둬야만 했

고 많은 사람들이 밖에서 들어야만 했다. 결국 내가 참여했던 것 중에서 가장 흥미진진한 강연이었다.

그 이후로 나는 API 설계와 관련된 정보가 필요하다는 사실을 알게 됐다. 그 강연에 대한 기억은 이 책을 쓰는 동안 동기부

여가 되지 않을 때마다 기운을 북돋아줬다. 내가 발견한 적절한 API 설계 규칙을 문서화할 필요가 있음을 떠올리는 데 도움

이 됐다. 이러한 규칙은 일반적인 설계 책에 널리 퍼져 있는 지식을 토대로 하지만 이 책에서 강조되고 확장되는데, API를

설계하는 것은 그 자체로 특별한 요건을 가지고 있기 때문이다.

책2.indb 14 2015-04-28 오후 2:34:13

15

API 설계는 다르다

기존 설계 책으로 충분하지 않은 이유는 프레임워크나 공유 라이브러리를 설계하는 것이 사내 시스

템을 설계하는 것보다 복잡한 작업이기 때문이다. 폐쇄적인 시스템(사설 데이터베이스에 접근하면

서 직접 구축한 서버에서 실행되는 웹 애플리케이션 같은)을 구축하는 것은 집을 짓는 것과 같다.

어떤 집은 작고, 어떤 집은 크며, 때로는 마천루도 있다. 하지만 이 모든 경우에도 집은 각기 주인이

한 명씩 있고 그 주인은 변경에 대해 책임진다. 필요하다면 주인은 지붕을 바꾸거나 창을 새로운 것

으로 교체하거나 방 안에 벽을 새로 세우거나 기존 벽을 허무는 등을 할 수 있다. 물론 그중에서 적

용하기가 쉬운 변경사항도 있다. 지붕을 교체하는 것은 바닥에 큰 피해를 주지 않을 것이다. 창을 같

은 크기의 다른 창으로 교체하는 것은 다른 부분에 영향을 줄 가능성이 낮다. 하지만 창을 더 큰 창

으로 교체하는 것은 그리 간단하지 않을 수도 있다. 엘리베이터의 크기를 두 배로 늘리는 것은 보통

거의 불가능한 작업이다. 특이한 상황을 제외하면 기존의 1층 바닥과 그 위의 바닥들을 위로 옮기면

서 새로운 1층 바닥을 그 아래에 집어넣으려고 할 사람은 없다. 그러자면 너무나도 많은 문제가 발

생하기 때문에 그렇게 해서 얻게 될 혜택이 비용을 상쇄하지 못할 것이다. 한편으로 이 모든 것은 기

술적으로는 가능해 보인다. 주인이 그렇게 할 필요성을 느낀다면 그렇게 할 수도 있다.

사내 소프트웨어 시스템도 이와 비슷하다. 전형적인 한 명의 주인이 있고 그 주인은 대개 모든 것을

통제할 수 있다. 시스템의 특정 부분에 대해 새로운 버전을 업로드할 필요가 있다면 그렇게 할 수 있

다. 데이터베이스 스키마를 변경할 필요가 있다면 그것도 가능하다. 변경사항 중에는 복잡한 것들도

분명 있다. 데이터베이스 스키마를 변경하는 것은 어딘가에서 NullPointerException을 예방하는 한

줄짜리 버그 수정에 대한 변경보다 훨씬 더 큰 파급효과를 줄 가능성이 높다. 그럼에도 상상 속에서

는 어떠한 변경도 가능하다. 주인은 모든 것을 통제할 수 있고 시스템을 메이저 업그레이드할 필요

가 실제로 있다면 심지어 잠시 동안 시스템을 내릴 수도 있다. 게다가 사내 시스템의 변경사항을 관

리하는 데 유용한 설계 원칙도 많다. 개발자들이 코드를 구조화하는 데 유용한 디자인 패턴에 관한

책도 있다. 시스템 설계와 정확성 테스트를 위한 방법론도 있다. 사람들의 업무를 조직화하고 이끄

는 방법을 설명하는 책도 있다. 결국 중요한 것은 사내 시스템을 유지보수하는 것은 잘 알려져 있고

문서화된 프로세스처럼 보인다는 것이다.

하지만 API를 작성하는 것은 다르다. 이를 우주에 비유해보자. “집”에 비유한 것만큼 직관적이지는

않지만 이러한 사고 훈련은 유용할 것으로 입증될 것이다. “알려진” 우주를 떠올려보는 것으로 시작

해보자. 여기서 “알려진”이라고 분명하게 말한 이유는 우주 전체, 즉 기존의 별, 은하계, 그 밖의 것

들어가며: 또 한 권의 설계 책인가?

책2.indb 15 2015-04-28 오후 2:34:13

자바 API 디자인: 자바 프레임워크 아키텍트가 알려주는 API 설계 이론과 실제16

들, 그리고 중요하지 않은 예를 들자면 모든 물리 법칙을 아는 인간은 아무도 없기 때문이다. 인간은

지금껏 우주의 아주 작은 부분만을 볼 수 있을 뿐이다. 우리의 시야가 우주에서 보여지는 모든 것들

을 규정한다. 다시 말해 우리의 눈 앞에 있는 것은 “알려진” 우주다. 여기엔 수많은 물체와 현상이 있

지만 우리의 예상과 경험을 토대로 시야 너머에는 다른 별과 은하계가 있고 그것들은 여태껏 인간에

게 알려지지 않은 것임을 알 수 있다. 이러한 경험은 때때로 사람들이 더 나은 장비를 제작하거나 새

로운 자연 법칙을 인식하고 이해하는 과정을 통해 시야 너머로 나아가 새로운 사물이나 규칙을 발견

해왔다는 사실에 기초한다.

우주는 그대로 있는 것이 아니라 언제나 변화한다. 그러나 완전히 무작위로 변화하지는 않는다. 행

성과 별, 그 밖의 것들에 어떤 일이 일어날지는 일정한 규칙을 따른다. 예를 들어, 누군가가 시야

너머로 가서 새로운 별을 찾더라도 그 별은 당연히 내일도, 그다음 날도, 그리고 그다음 날도 거기

에 있을 것이다. 사실 별은 이동하고, 회전하며 심지어 폭발할 수도 있다. 하지만 이 모든 것들은

자연 법칙을 따른다. 별이 무작위로 나타나고, 사라지고, 움직인다는 우주 마일스톤 X (Universe

Milestone X )를 2주마다 발표할 사람은 아무도 없다. 세계가 그런 식으로 작동한다면 우리가 우주

를 인식하고 이해하는 바와 충돌할 것이다. 우리는 그저 별이 발견되고 나면 그것이 영원할 것이라

고만 안다. 심지어 아무도 지켜보고 있지 않을 때도 그 별이 여전히 있을 것이라고 믿는다. 음, 분명

그렇다. 별은 지구상의 누군가가, 다른 태양계의 누군가가, 우주상의 다른 어떤 생명체가 관찰하거

나 아니면 아무도 관찰하지 않을 수도 있다. 하지만 별 자체는 그것이 관찰되고 있는지 알지 못하며,

별이 할 수 있는 유일한 일은 자연 법칙을 따르는 것이며, 따라서 일단 발견되고 나면 영원히 존재하

는 것이다.

훌륭한 API도 이와 비슷하다. 공유 라이브러리가 특정 버전에서 새로운 함수를 도입하면 그것은 새

로운 별을 발견하는 것과 같다. 새로운 버전을 사용하는 사람은 해당 함수를 보고 그것을 사용할 수

있다. 해당 함수를 사용할 수 있지만 반드시 사용할 필요는 없다. 이것은 어디까지나 프로그래머의

시야에 달린 문제다. API 사용자의 거의 대다수가 알지 못하는 기능을 추가하는 것도 가능하다. 하

지만 거기에 의존해서는 안 된다. 내가 경험한 바로는 API 사용자는 정말로 창의적이다. API 사용

자의 시야가 API 설계자의 시야보다 훨씬 더 넓을 때도 있다. 뭔가를 오용하는 방법이 있다면 사용

자가 그렇게 할 가능성이 높다. 결과적으로 함수 자체나 해당 함수의 제작자도 그것이 사용되거나

얼마나 자주 사용되는지 알지 못할 가능성이 높다. 전 세계에 수많은 사용자가 있을 수도 있고, 아예

한 명도 없을 수도 있지만 훌륭한 API 설계 법칙을 위반하려고 하지만 않는다면, 즉 하위 호환성을

책2.indb 16 2015-04-28 오후 2:34:14

17

위반하려고 하지만 않는다면 누군가가 지켜보고 있다고 가정하고, 따라서 함수도 그대로 유지보수

해야 한다. “API는 별과 같아서 한번 도입되고 나면 영원히 그 자리에 존재한다.”

우주와 API 설계를 비유하는 것이 또 있다. 그것은 우리가 우주를 이해하는 방법과 라이브러리를

진화시키는 방법과 관련이 있다. 고대 그리스인들은 행성, 즉 토성과 목성까지의 움직임을 파악하

고 관찰할 수 있었고, 따라서 “알려진” 우주의 행성들을 정의할 수 있었다. 하지만 고대 그리스인

들이 행성이 움직이는 이유를 설명하려고 노력했음에도 현재 기준에 따르면 그들은 성공하지 못했

다. 행성을 움직이게 하는 법칙은 여전히 그들의 시야 밖에 존재했다. 이것은 니콜라스 코페르니

쿠스(Nicolaus Copernicus )가 태양 중심 체계 지동설을 제안하고 요하네스 케플러(Johannes

Kepler )가 태양 주위로 행성이 움직이는 궤도와 속도를 설명하는 세 개의 법칙을 발견했던 르네상

스 시대까지도 이어졌다. 이러한 발견은 “대상”을 정확히 설명해줌으로써 우주에 대한 지식 수준을

드높였다. 하지만 “이유”를 아는 사람은 아무도 없었다. 1687년이 돼서야 비로소 아이작 뉴턴이 케

플러의 법칙을 설명하고 물리적인 힘의 개념을 소개했다. 이로써 케플러의 법칙이 왜 참인지 밝혀졌

을 뿐 아니라 알려진 우주의 엄청난 팽창이 시작되기도 했는데 뉴턴의 법칙 덕분에 물리학이 알려진

우주에서 사물 간에 일어나는 거의 모든 것을 설명할 수 있었기 때문이다.

다양한 측정 수단을 통해 뉴턴의 법칙으로는 설명할 수 없는 행위, 특히 속도가 빠른 사물의 행위가

있다는 것이 증명된 19세기 말까지는 모든 것이 문제 없어 보였다. 뭔가가 그다지 맞지 않다는 축적

된 증거들은 알베르트 아인슈타인이 상대성 이론을 발견하는 데 이바지했고, 상대성 이론은 굉장히

빠른 속도로 움직이는 사물을 비롯해 우주를 이해하는 데 크게 기여했다. 사실 아인슈타인의 이론은

뉴턴의 이론을 확장한 것으로서 사물이 적당히 느리게 움직이는 경우에는 두 이론이 같은 결과를 보

인다.

이러한 물리적이고 역사적인 여행이 대체 API 설계와 무슨 관계가 있을까? 이어지는 몇 개의 단락

에서는 어떤 신이 API 라이브러리를 통해 사람들과 의사소통하고 있다고 가정해보자. 이 라이브러

리에서는 인간에게 “알려진” 우주에 대한 인터페이스를 부여한다. 고대 그리스인들이라면 0.1 버전

의 라이브러리를 사용할 텐데, 이 버전에서는 행성과 각 행성의 이름만 열거할 것이다. 그리 풍부하

지 않은 API라는 점은 분명하지만 어떤 사용자와 특정 시점에서는 이것으로도 충분할지 모른다. 가

령, 행성과 행성의 이름을 확인하는 데는 충분하다. 기존 라이브러리의 상태와는 상관없이 개선을

제안하는 사람들은 늘 있을 것이다. 비슷하게 0.1 버전의 우주 라이브러리는 미흡한 것으로 파악됐

는데, 케플러가 행성의 움직임에 대한 법칙을 정말로 이해하고 싶어했기 때문이다. 따라서 이 단락

들어가며: 또 한 권의 설계 책인가?

책2.indb 17 2015-04-28 오후 2:34:14

자바 API 디자인: 자바 프레임워크 아키텍트가 알려주는 API 설계 이론과 실제18

에 존재하는 가상의 신은 케플러에게 우주 1.0이라는 업데이트를 내려준다. 이 버전의 라이브러리

에서는 특정 시간대의 각 행성의 공간 좌표를 제공할 수 있으며, 그리스인들에게 제공됐던 원래의

기능은 그대로 유지되고 계속해서 동작할 것이다.

그러나 사용자는 절대로 만족하는 법이 없고, 이것은 물리학자들도 마찬가지다. 그래서 가상의 신도

뉴턴이 새로운 메이저 버전의 우주 2.0을 출시하게끔 도와야 했다. 이 버전에서는 태양과 각 행성

간의 실제 중력에 관한 정보뿐 아니라 힘, 가속도, 우주에서의 물체(행성에만 국한된 것이 아니라)

의 속도를 계산하는 편리한 서브루틴까지 제공했다. 말할 것도 없이 그리스인들과 케플러가 제공한

이전 버전의 기능은 모두 이전 버전에서처럼 계속 동작할 것이다.

여기까지는 모든 추가사항을 쉽게 이해할 수 있었다. 이전 단락에 존재하는 가상의 신은 단순히 새

로운 기능만 추가했을 뿐이다. 그런데 역사상의 한 지점에서 물리학자들이 우주의 법칙이 모두 알려

졌고 물리학 자체에도 설명할 게 아무것도 남아있지 않은 것 같다고 주장한다면 어떻게 해야 할까?

인류를 괴롭혀보자! 가상의 신은 마이컬슨(Michelson ) 실험을 만들어내는데, 이 실험은 아인슈타

인으로 하여금 상대성 이론을 공식화하도록 이끈다. 최신 버전의 우주 라이브러리는 이제 더는 손

쉽게 하위 호환성을 보장할 수 없는 문제에 직면하는데, 새로 도입된 아이디어가 뉴턴을 비롯해 이

전의 물리학자들이 이뤄낸 모든 것들이 약간씩 틀렸다는 것이었기 때문이다! 하지만 그와 같은 급격

한 변화도 하위 호환성을 보장하는 모드로 관리할 수 있다. 아주 높은 속도에서만 잘못된 결과가 도

출될 위험이 있다. 이러한 속도는 뉴턴과 그 전임자들이 측정할 수 있는 것보다 훨씬 더 높은 속도이

고, 따라서 호환되지 않는 부분이 있음에도 이전에 수행했던 측정에서는 비일관성을 증명하거나 우

주 라이브러리의 동작 방식이 바뀌었다는 것을 아무도 증명할 수 없었다.

이처럼 터무니없는 물리학 우화의 교훈은 우주에 대한 우리의 이해가 계속 진화하고 있다는 것이다.

이것은 우리가 만든 라이브러리API도 마찬가지다. 낙관론자들은 동의하지 않을 수도 있겠지만 나

는 인류가 결코 전 우주를 이해하게 될 것이라 생각하지 않는다. 아직까지는 우주에 관해 계속해서

더 배울 것이라고 예상한다. 다르게 생각하는 개발자도 있겠지만 우리가 만든 거의 모든 라이브러리

가운데 활발하게 사용되는 라이브러리의 API는 절대로 완성되지 않을 것이다. 그것들은 언제까지

고 진화할 것이다. 우리는 거기에 대비해야만 한다. 우리는 우주에 대해 우리가 이해하는 바를 수

정할 준비를 갖춰야만 하고 우리가 만든 라이브러리 API를 강화하고 향상시킬 준비를 반드시 해야

한다.

책2.indb 18 2015-04-28 오후 2:34:15

19

집을 짓거나 사내 소프트웨어 시스템을 구축하는 것과 달리 이렇게 하려면 개발자들이 현재 버전의

API를 코딩하고 있는 동안 미래에 관해 생각할 필요가 있다. 내가 알기로 이것은 지금까지 API 설

계에 적용된 일반적인 접근법이 아니다. 게다가 현재 시중에 나오는 책들과 거기서 제안하는 내용은

이 같은 생각에 그다지 도움되지 않는다. 그러한 책에 실린 디자인 패턴은 주로 단일 버전을 기술하

는 데 사용된다. 그러한 디자인 패턴을 사용하는 사람들은 현재 버전의 맥락에서만 생각한다. 사람

들은 이전 버전을 최소한으로 참조하거나 향후 릴리스에서 어떤 일이 일어날지에 관해 별로 생각하

지 않을 때가 많다. 그럼에도 공유 라이브러리나 프레임워크를 작성할 경우에는 이러한 기술이 필요

하다. 우리는 집을 설계하는 일을 그만두고 우주를 설계하는 법을 배울 필요가 있다. 우리는 “API라

는 별이 발견되고 나면 그것은 영원히 우리 곁에 있을 것이다”라는 사실을 배울 필요가 있다.

이 책은 누가 읽어야 할까?

서점에서 이 책을 손에 들고 이 책을 사야 할지 말아야 할지 판단하는 중이라면 이 책이 여러분을 위

한 책인지 궁금할 것이다. 나는 여러분을 모르기 때문에 그 질문에 답할 수는 없다. 하지만 이 책이

왜 나 자신에게 필요했고 왜 이 책을 쓰기로 했는지는 설명할 수 있다. 넷빈즈 API를 설계하고 있었

을 때 나는 그때그때마다 배우는 중이었다. 초기에는 직관에 따라 움직였고 API를 작성하는 일은

일종의 예술이라고 생각했다. 그게 사실일 수도 있는데, 그렇게 하려면 창의적이어야 하기 때문이

다. 그러나 API 작성이 예술적인 훈련에 불과한 것은 아니다. 시간이 지나면서 나는 내가 해야 했던

모든 작업의 이면에 놓인 구조를 파악하기 시작했고, 평범한 API를 훌륭한 API로 바꾸는 측정 가능

한 기준을 공식화했다.

이 책은 넷빈즈 팀에서 API의 품질을 측정할 때 따른 기준을 설명한다. 그뿐만 아니라 우리가 왜 그

러한 기준을 따랐는지도 설명한다. 우리가 현재의 위치에 있기까지는 수년에 걸친 시행착오가 있었

다. 바퀴를 재발명하는 것은 그다지 시간을 생산적으로 쓰는 것은 아니기 때문에 순수하게 예술적인

설계보다 좀 더 공학적인 설계를 선호하는 모든 API 아키텍트에게 이 책을 추천한다. 넷빈즈 초기

에는 API를 작성하는 사람이 나밖에 없었다. 당시에는 “위원회를 통해서는 훌륭한 API가 설계될 수

없다”라는 말을 믿기까지 했다. 설계자가 한 명이면 형식적인 규칙 없이도 일관성을 유지할 수 있다.

하지만 일의 규모가 커지면 한 명의 설계자로는 전혀 감당할 수 없게 된다. 이를 넷빈즈 환경에서도

발견했다. 그래서 내가 하는 일은 전체적인 일관성은 유지하면서 더 넓은 범위의 사람들이 API를

설계하는 방법을 찾는 것이었다. 그때 나는 API 설계 이면의 이론을 비롯해 우리가 API를 작성하도

들어가며: 또 한 권의 설계 책인가?

책2.indb 19 2015-04-28 오후 2:34:15

자바 API 디자인: 자바 프레임워크 아키텍트가 알려주는 API 설계 이론과 실제20

록 이끄는 동기, 그리고 어떤 API가 좋은지 여부를 평가할 때 반드시 따라야 할 규칙들을 설명하기

위해 이 책을 쓰기 시작했다. 그러고 나서 넷빈즈 개발자들에게 내 접근법을 전달하고 그들이 API

를 작성하게 한 다음, 설계 작업의 처음부터 끝까지 개발자들을 지켜보고 조언해줬다. 내가 알기로

이 방법은 효과가 좋았다. API가 10년 동안 진화하고 우리가 그때그때마다 배워왔다는 점을 고려하

면 우리가 만든 API는 비교적 일관되고 대부분의 요구사항을 충족한다. 만약 여러분이 API 설계를

지켜봐야 하는 지위에 있다면 여러분도 이 책에서 제안하는 내용이 유용하다고 생각할지도 모른다.

나 스스로 “API”라는 용어의 의미를 정립하고 있었을 때 사실 이 용어의 의미가 굉장히 넓다는 사실

을 발견했다. API를 작성하기 위해 프레임워크나 라이브러리를 작성할 필요는 없다. 다른 사무실에

서 일하는 동료가 쓸 클래스 하나를 작성하는 경우에도 사실 API를 작성하고 있는 셈이다. 왜일까?

여러분이 만든 클래스를 써야 하는 개발자는 여러분이 해당 클래스에 있었던 메서드를 삭제하거나

메서드의 이름을 바꾼다면, 혹은 클래스 내의 메서드의 동작 방식을 바꾼다면 그다지 달가워하지 않

을 것이기 때문이다. 공유 라이브러리에서 사용할 API를 작성할 때도 정확히 같은 문제가 발생한

다. 어쩌면 클래스 사용자가 여럿일 수도 있는데, 클래스를 변경했을 때 해당 클래스의 모든 사용자

가 코드를 재작성해야 한다면 비효율의 악몽이 시작될 수도 있다. 그러한 악몽이 일어나서는 안 된

다. 클래스를 API로 여긴다면 골칫거리가 덜할 것이다. 게다가 클래스를 그런 식으로 생각하는 것

은 어렵지 않다. 이는 클래스를 좀 더 신중하게 설계하고, 호환성을 보장하는 방식으로 진화시키며,

다른 훌륭한 API 설계 실천법을 적용할 필요가 있다는 의미다. 이 같은 관점에서 거의 모든 개발자

는 API 설계라는 일을 하고 있거나 해야만 한다.

API의 핵심부는 해당 API의 동작 방식에 있다. API가 어떻게 동작하는지 설명할 때 테스트가 중요

한 역할을 한다. 적절히 테스트하지 않고는 훌륭한 API를 작성하기가 거의 불가능에 가깝다. 이 책

의 여러 장에서는 테스트 패턴, 즉 여러 번에 걸친 릴리스에도 유효하게끔 외부에서도 볼 수 있는 라

이브러리의 여러 측면들을 테스트하는 방법을 간략하게 살펴본다. 이 책에서는 시그너처, 단위 테스

트, 호환성 검사 도구를 비롯해 다양한 종류의 테스트를 언급할 것이다. 따라서 이 책은 API 호환성

도 검사해야 하는 사람들에게 가치 있는 책이다.

마지막으로 이야기하지만 한 가지 중요한 점은 널리 사용되는 라이브러리를 가지고 있다는 것은 해

당 라이브러리를 제작하는 사람에게 좋은 자산이 될 수 있다는 것이다. 이 자산을 늘리는 것은 기존

사용자를 만족시키고, 동시에 새로운 사용자가 참여해서 그것을 사용하도록 마음을 이끄는 것을 의

미한다. 사용자 기반이 충분히 풍부해야 라이브러리를 제작하고 유지보수하는 데 들어간 노력을 실

책2.indb 20 2015-04-28 오후 2:34:15

21

제로 현금화할 수 있다. 이 책에서는 이 부분도 살펴볼 것이며, 따라서 좀 더 사업 지향적인 관점에

서 소프트웨어 개발을 검토하는 사람들에게도 흥미로울 수 있다.

이 책은 자바에만 유용한가?

넷빈즈는 자바로 작성된 통합 개발 환경(IDE, Integrated Development Environment )이자

프레임워크이며 내가 가진 대부분의 API 설계 지식은 넷빈즈 프로젝트를 토대로 하고 있기 때문에

이 책이 자바 개발 밖에서도 유용한지 궁금할 수 있다. 이 질문에 대한 내 대답은 ‘그렇다’다. 이 책에

서는 훌륭한 API 설계를 위한 일반적인 가이드라인을 살펴본다. 이러한 가이드라인과 원리는 어떤

프로그래밍 언어의 어떤 API에도 적용할 수 있다. 이 책에서 다루는 내용에는 API를 만들게 되는

이유를 비롯해 훌륭한 API 문서를 작성하고 구조화하기 위한 규칙과 동기, 하위 호환성의 원칙들이

있다. 그러한 원칙들은 C, 포트란, 펄, 파이썬, 하스켈을 비롯한 다양한 언어에 적용할 수 있다.

물론 더 자세히 설명해야 하는 경우에는 자바 같은 언어에 특화된 기능을 언급할 수밖에 없다. 우선

자바는 객체 지향 언어다. 객체 지향 언어를 대상으로 API를 설계하는 것은 상속 설계나 가상 메서

드, 캡슐화 같은 것에 기인한 고유의 고려사항이 있다. 따라서 이 책에서 다루는 원칙 중 일부는 C나

포트란과 같은 “오래된 언어지만 훌륭한” 비객체 지향 언어에 비해 C++나 파이썬, 자바 같은 객체

지향 언어에 좀 더 적용하기 쉽다.

게다가 자바는 가비지 컬렉터를 사용하는 새로운 언어 진영에 속한다. 사실 자바가 업계에서 널리

사용된다는 것은 제품 애플리케이션에서 가비지 컬렉터를 사용하는 것이 가능하고 또 그것으로부터

혜택을 받을 수 있다는 점을 증명한다. 자바가 나오기 전 업계에서는 개발자가 명시적으로 메모리의

할당과 해제를 통제하는 C, C++ 등과 같이 흔히 사용되는 언어에서 제공하는 전통적인 메모리 관

리를 선호했다. 당시에는 스몰토크(Smalltalk )나 에이다(Ada )처럼 가비지 컬렉터를 지원하는 언

어는 실험적으로 여겨지거나 적어도 소프트웨어 업계 전반적으로 사용되기에는 모험스러운 일로 여

겨졌다. 자바는 이 같은 상황을 완전히 바꿨다. 현재 소프트웨어 엔지니어의 대다수는 자동 메모리

관리 체계를 갖춘 고성능 프로그래밍 언어의 개념에 대해 비웃지 않으며, 프로그래머들은 더는 그러

한 언어를 사용하기를 두려워하지 않는다. 하지만 자동 메모리 관리 체계는 여러분이 만드는 API에

영향을 준다. 예를 들어, C와 달리 자바에서는 새로운 객체를 생성하려면 malloc과 비슷한 생성자가

필요하지만 그것과 쌍을 이루는 해제 API는 필요하지 않다. 여러분은 그러한 해제 API를 공짜로 가

들어가며: 또 한 권의 설계 책인가?

책2.indb 21 2015-04-28 오후 2:34:16

자바 API 디자인: 자바 프레임워크 아키텍트가 알려주는 API 설계 이론과 실제22

질 수 있다. 이것은 이 책에서 취하는 특정 접근법이 가비지 컬렉터를 갖춘 언어, 다시 말해 자바에

의해 대중화된 메모리 관리 방식을 사용하는 새로운 언어에 좀 더 적용하기 쉽다는 것을 의미한다.

자바는 가상 머신과 동적 컴파일의 사용을 대중화하기도 했다. 정적 컴파일이 이뤄지는 동안 자바

소스코드는 여러 개의 클래스 파일로 옮겨진다. 그러고 나면 이러한 파일은 배포되고 서로 링크되지

만 그 과정은 프로그램이 실행되는 동안에만 일어난다. 게다가 이러한 클래스 파일은 최종 애플리케

이션이 실행되는 실제 프로세서 아키텍처에 독립적인 형식으로 돼 있다.

이 과정은 개별 클래스 파일을 서로 링크시키기도 하고 클래스 파일의 명령어(instruction )를 실

제 프로세서의 명령어로 변환하기도 하는 런타임 환경을 통해 이뤄진다. 자바 초기에는 이 또한 자

바가 다른 언어와 다른 부분이었다. 성능이 좋은 프로그램은 가상 머신에 의해 해석될 수 없고, 포트

란으로 작성해 그 프로그램을 실행하는 운영체제의 어셈블리 언어에서 가장 최적화된 기능을 사용

하도록 직접적으로 컴파일돼야 한다는 사실을 누구나 알고 있었다. 나를 포함한 일부 사람들은 C나

C++로 코드를 작성해도 빠른 프로그램을 만들어내는 것이 가능하다는 사실을 인정했다. 그러나 여

전히 자바에서 취한 접근법은 많은 이들이 성공할 가능성이 낮을 것이라고 여겼다.

하지만 시간이 지나면서 가상 머신을 기반으로 한 언어가 어떤 장점들을 가지고 있다는 점이 입증됐

다. 예를 들어, 모든 수치형 타입은 프로그램이 실행되는 플랫폼과 무관하게 같은 길이를 가지고 있

는데, 이로써 기반 아키텍처를 이해해야 할 필요성이 대폭 줄어든다. 그뿐만 아니라 자바 프로그램

은 뭔가가 잘못됐을 때 세그먼테이션 폴트를 내면서 망가지지 않는다. 가상 머신은 메모리가 부적절

한 C 포인터 연산으로 손상되지 않고 변수가 언제나 올바른 타입을 갖도록 보장한다. 그럼에도 성능

문제는 초기 자바 구현체에서 지속적으로 발생했다. 하지만 시간이 지남에 따라 인터프리터마저도

속도가 빨라졌고, 새로 만들어지는 다른 언어들도 이러한 “가상” 머신을 활용하는 방식을 채용하게

할 만큼 빠른 코드를 만들어내는 JIT (just-in-time ) 컴파일러로 대체됐다. 그 결과, 현재 “가상 머

신”이라는 용어는 널리 받아들여지고 사용되고 있다. 이 책에서도 클래스 파일의 포맷에 좀 더 집중

하긴 하지만 가상 머신도 어느 정도 다루고 있는데, 클래스 파일의 포맷이 바로 가상 머신의 공통어

이기 때문이다.

자바 언어의 구문이 가상 머신 자체에 어떤 의미를 갖는가를 올바르게 이해하려면 클래스 파일

의 포맷을 이해하는 것이 중요하다. 가상 머신의 언어로 말하고 가상 머신의 눈으로 클래스 파일

을 보면 편할 것이다. C 같은 다른 프로그래밍 언어에도 자체적인 추상 바이너리 인터페이스(ABI,

책2.indb 22 2015-04-28 오후 2:34:16

23

abstract binary interface ) 모델이 있기는 하지만 자바에서 사용되는 것은 적어도 두 가지 측면

에서 특별하다. 첫째, 당연히 객체 지향이다. 둘째, 늦은 링크(late linkage )를 허용한다. 즉, 일반

C 오브젝트 파일에 포함돼 있는 것보다 훨씬 더 많은 정보를 담고 있다. 그 결과, 가상 머신을 연구

해서 얻은 지식은, 오래됐지만 훌륭한 비객체 지향 언어에는 적용하기가 다소 어렵다. 그러한 지식

이 자바의 가상 머신을 흉내 낸 다른 현대 언어에는 유용할 수 있지만 말이다.

자바는 API의 문서화를 실제 코드와 연관시킨 최초의 언어이기도 하다. 자바에는 자바독

(Javadoc )을 통해 누구나 사용할 수 있는 코드에 주석을 다는 대중화된 수단이 있다. 이를 통해

API의 실제 동작 방식과 API의 문서화가 훨씬 더 가까워져서 좀 더 간편하게 최신 내용을 유지할

수 있다. 다른 모든 언어에서도 주석을 사용할 수 있지만 자바독은 주석으로부터 실제로 브라우징이

가능한 문서를 만들어내고, 자바의 모든 API 문서화에 일관성을 부여하는 기본 뼈대를 만들어준다.

한편으로 이것은 더는 자바에만 특화된 부분이 아니다. 이 방식은 아주 유용하다고 입증되어 자바

이후에 만들어진 거의 모든 언어에서는 자바독과 비슷한 개념을 포함하고 있다. 다른 이미 존재하는

언어의 경우에는 이러한 코드와 문서의 연동을 새로 추가하는 별도의 도구가 만들어지고 있다. 이러

한 이유로 API 사용자의 이해를 간소화하기 위한 자바독의 유용성과 장단점을 분석해 보면 이 책에

서는 거의 모든 프로그래밍 언어에 적용 가능한 결론을 낼 것이다.

자바 5에서는 제네릭을 지원하도록 바뀌었다. 이 책에서 모든 자바 언어 구문을 다루지는 않지만 그

것을 무시할 수는 없다. 제네릭은 API 설계에서 중요하고 새로운 현상을 만들어낸다. 왜 새로울까?

전통적인 객체 지향 언어는 상속을 통해 재사용을 장려하기 때문이다. 두 번째로 흔한 형태의 코드

재사용, 즉 합성(composition )을 통한 재사용도 가능했지만 이것은 어디까지나 이차적 구성물

(second-class citizen )에 해당한다. 이렇게 되는 가장 중요한 이유는 상속은 언어 구문으로 내

장돼 있는 반면 합성은 직접 손으로 코드를 작성하고 올바르게 입력하기가 어렵기 때문이다. 그와

동시에 합성을 통한 재사용을 선호하고 상속을 이차적 구성물로 만든 언어들도 만들어졌는데, 특히

하스켈 같은 현대적인 함수형 언어가 여기에 해당한다. 어떤 사람들은 두 접근법 모두 각기 이점이

있고, 객체 지향 언어와 다형적인 타입을 가진 함수형 언어를 결합시키는 데 많은 시간을 쏟는다고

생각하기도 한다.

자바의 제네릭은 이러한 결합의 결과다. 어떤 이들은 제네릭이 너무 복잡하다고 비판하기도 하는데,

1997년에 내가 연구한 바로는 이를 더 나은 방식으로 하기도 어려웠다. 나는 언어 팀에서 이뤄낸 결

과에 만족하는데, 이제 상속과 합성은 거의 동등한 수준에 이르렀기 때문이다. 이러한 이유로 이 책

들어가며: 또 한 권의 설계 책인가?

책2.indb 23 2015-04-28 오후 2:34:17

자바 API 디자인: 자바 프레임워크 아키텍트가 알려주는 API 설계 이론과 실제24

에서도 제네릭에 관해 이야기할 것이다. 그렇게 하면 이 책에서 다루는 부분들이 하스켈 같은 언어

와도 좀 더 가까워질 것이다.

이 책을 다른 언어에 적용할 수 있는 이유가 하나 더 있다. 바로 이 책에서는 자바를 있는 그대로 받

아들이기 때문이다. 이 책에서는 API 설계 문제를 처리하는 데 적합한 새로운 언어를 만들어내지

않는다. 대신 우리가 알고 있는 자바를 이용한다. 모든 원칙과 권장사항은 구체적인 코딩 스타일에

관한 것이지 새로운 키워드나 선행조건 또는 후행조건, 불변식 검사를 추가하는 것과 무관하다. 이

것은 소프트웨어 공학에서나 필요한 것이며, 언어는 정해져 있을 때가 많고, 그러한 제약조건 내에

서 목표(이를테면, 일반적으로 사용되는 라이브러리를 만들어내는)를 달성해야 하기 때문이다. 이

것은 그리 놀랄 만한 일이 아니다. 새로운 API를 배우는 데는 약간의 노력이 필요할 수도 있지만 그

것은 새로운 언어를 배우는 것에 비할 바는 아니다.

사용할 언어는 거의 항상 정해져 있기 때문에 API 설계 원칙들은 그러한 언어로 표현해야 한다. C

로 훌륭한 API를 작성하는 것이 가능하다면 자바로 훌륭한 API를 작성하지 못할 이유도 없을 것이

다. 그러한 이유로 이 책에는 일반 자바로도 충분하다. 요약하자면 이 책에는 어떤 언어에도 적용 가

능한 일반적인 부분들이 들어 있다. 다른 부분에서는 객체 지향 개념에 관해 이야기하며, 좀 더 깊게

파고들어야 할 때마다 자바의 경우를 보여준다.

API를 작성하는 법 배우기

API를 올바르게 개발하는 사람들이 있다는 것은 틀림없는 사실이다. 그렇지 않다면 지금처럼 훌륭

하고 유용한 소프트웨어 제품들은 없을 것이다. 하지만 간혹 설계 원칙들과 API 설계의 주요 규칙

들이 무의식적으로 받아들여질 때가 있다. 설계자들은 결정을 이끄는 원래의 동기를 실제로 인식하

거나 이해하지 않은 채로 규칙을 따르는 경향이 있다. 그 결과, 훌륭한 API 설계에 관한 무의식적

지식이 시행착오로 쌓이고, 이렇게 되는 데는 당연히 시간이 걸린다. 게다가 이러한 과정의 결과로

API 설계를 “올바르게” 하는 방법에 관한 조언들이 체계적이지 못한 방식으로 모일 때가 많다. 이것

은 앞으로 한 걸음 더 나아가는 것이긴 하지만 그러한 조언 모음은 두 가지 문제를 겪을 때가 많다.

첫째, 이러한 조언은 보통 특정 영역에만 국한될 때가 많다. 예를 들어, 한 프로젝트나 특정 그룹의

사람들에게만 효과가 있고, 다른 팀에도 유용하다거나 다른 프로젝트에도 적용할 수 있다는 것이 전

혀 보장되지 않는다.

책2.indb 24 2015-04-28 오후 2:34:17

25

둘째, 이러한 경우 사고 방식이 다른 사람들에게 지식을 전달하기가 어렵다. 여러분이 경험한 바로

는 자바 클래스가 자바 인터페이스보다 더 선호되고 이 경험이 특정 문제를 해결하는 데서 얻은 것

이라면 그 경험을 다른 시나리오에 전달하기는 어렵다. 다른 이들에게 이것이 올바른 접근법이라고

설득할 수는 있겠지만 결국 그와 관련된 이유를 적절히 설명하지 않고는 신념을 기초로 해당 접근법

을 수용하기만을 바랄 수밖에 없다. 신념은 추종자와 거부자만을 만들어낼 수 있을 뿐 지식을 전달

하는 용도로는 적합하지 않다.

무의식적인 넷빈즈 API 설계

넷빈즈 프로젝트의 구성원들도 그러한 시기를 거쳤다. 우리는 무엇이 효과적이고 무엇이 효과적이지 않은 것에 대해 다소

“느낌”만으로 API를 설계하는 갖가지 다양한 경험을 했다. 하지만 이 지식은 기초부터 착실히 쌓이지 않았다. 즉, API 설계

지식이 진지한 추론이나 설계 결정에 대한 이유를 이해하는 과정을 통해 구축되지 않았다. 오히려 느낌에 더 가까웠고 그러

한 느낌을 자아낸 이유는 우리의 무의식 속에 발견되지 않은 채로 그대로 남아 있다. 그렇다 보니 다른 사람에게 지식을 전

달하려고 할 때 문제가 발생했다. 그들은 우리의 경험을 과소평가했고 우리를 신뢰할 이유가 없었다. 이를 계기로 우리는

그들이 우리를 신뢰해야 할 이유와 실제 경험에 관해 훨씬 더 깊게 생각해야 했고, 그 결과 훌륭한 API 설계의 측정 가능성

을 공식화하는 데 이바지했다. 이 책은 그러한 고민의 결과다. 지금까지의 경험들은 그동안 우리가 내려온 가정 너머에 숨

겨진 논리를 밝히는 데 이바지한 정보를 드러낼 것이다. 우리는 이러한 논리를 의식적이자 인식 가능해진, 그리고 듣고 싶

어 하는 모든 이들에게 합리적으로 설명할 수 있는 무언가로 바꿨다.

대답할 만한 가장 중요한 질문은 바로 “왜 API를 만드는 것인가?”와 사실 “API란 무엇인가?”다. 이 책에서는 이러한 질문에

관해 자세히 살펴본다.

우리가 경험한 바로는 여기서 조언한 모든 내용들은 읽거나 이해하거나 심지어 동의하지 않고서도

소프트웨어 제품의 개발에 참여하는 모든 이들이 기본적인 동기와 용어를 이해하는 데 도움될 것이

다. 이로써 문제를 더 잘 파악하고 이해하게 되고 문제의 복잡성이 숨김없이 드러날 것이다. 모든 개

발팀원들이 각자의 눈으로 “API 설계”를 바라볼 수 있을 경우 서로 이해한 바를 공유하게 되어 의

사소통이 단순해지고 의사결정을 따로 설명할 필요가 없어진다. 결국 이것은 개발팀원 간의 협동

뿐 아니라 팀 및 분산 협력사 간의 협동을 향상시키고, 결과적으로 더 나은 품질의 소프트웨어로

이어진다.

이러한 이유로 이 책은 모든 사람들을 대상으로 한다. 이 책에서는 API를 설계하는 기본적인 동기

를 설명하고, 개발자들을 위해 예제와 기법을 제공하며, API를 설계하는 이들을 위해 훌륭한 아키

텍처의 측면들을 설명하고, API 품질을 평가하기 위한 측정 가능한 원칙들을 제공한다.

들어가며: 또 한 권의 설계 책인가?

책2.indb 25 2015-04-28 오후 2:34:17

자바 API 디자인: 자바 프레임워크 아키텍트가 알려주는 API 설계 이론과 실제26

아직도 이 책을 읽어야 할지 자문하고 있다면 훨씬 더 짧은 대답은 다음과 같다. “그렇다, 여러분은

이 책을 읽어야 한다!”

이 책은 정말로 노트인가?

이 책에 적합한 형식을 고민하기 시작했을 때 나는 두 가지 극단적인 접근법 사이에서 선택할 수 있

는 다양한 접근법을 검토했다. 한 극단에서는 API 설계를 수행할 때 필요한 동기, 이유, 과정에 대

해 엄밀하고 과학적인 설명을 쓸 수 있다. 이렇게 하면 어떤 프로젝트에도 적용 가능한 일련의 제안

과 규칙들이 만들어질 것이다. 물론 이것은 이 책의 구체적인 목표 중 하나다. 그것들은 일반적으로

적용 가능해야 하고 우리가 지난 10년간 넷빈즈 프로젝트에서 한 일을 단순히 설명하는 것이어서는

안 된다. 다른 한 극단에서는 적절한 설명이 없는 조언은 소용없다고 굳게 믿는 것이다. 나는 “왜”를

이해할 수 없는 상태에서 “무엇”을 따르는 것을 진짜 싫어한다. 나는 늘 맥락을 이해하고, 직접 다양

한 해법을 평가한 다음, 그 상황에서 최선의 것으로 보이는 해법을 선택한다. 이러한 이유로 우리의

설계 규칙을 받아들이도록 동기를 부여한 맥락을 공유하고 싶다. 이러한 맥락을 제공하는 가장 좋은

방법은 당시에 넷빈즈 프로젝트에서 마주친 실제 문제를 설명하는 것이다. 그 결과, 이 책은 노트에

아주 가깝다.

또한 연구일지 형식은 이 책이 만들어진 과정과 상당히 유사하다. 그것은 한 번에 쓴 것이 아니라 여

러 해에 걸쳐 주제가 추가됐다. 충분히 일반적으로 보이는 문제를 해결해야 할 때마다 이 책의 목차

에 새로운 주제를 추가하고 해법에 관해 생각해본 다음 나중에 그것을 적었다. 이것은 우리의 규칙

을 기록하는 가장 효과적인 방법이었고, 실제로 그 결과인 최종 결과물은 연구일지와 비슷하다. 바

로 매일매일 작성하는 것이 아닌 각 문제마다 작성하는 연구일지 말이다!

두 접근법의 장점을 모두 취하기 위해 이 책에서 분석한 각 주제에는 넷빈즈 프로젝트에서 해결해

야 할 실제 상황을 설명하는 내용이 포함돼 있다. 그런 다음 문제는 어떠한 프레임워크나 공유 라이

브러리 프로젝트에도 적용할 수 있는 일반적인 권장사항으로 바뀐다. 이것은 우리가 사용했던 “사고

경로”와 비슷하다. 즉, 먼저 문제가 있다면 그것을 분석한 후 문제를 극복하는 규칙을 고안해낸다.

마찬가지로 이는 독자로 하여금 우리의 “사고 경로”를 검증하고 조언이 실제로 다른 상황에서도 적

용 가능하고 우리가 일반화한 내용이 실제로 올바른지 확인할 수 있는 기회를 준다. 여러분은 “참고

사례”에서 설명한 상태를 여러분의 프로젝트에 변용하기 시작해서 동일한 사고 단계를 적용하고 그

러한 사고 단계가 실제로 우리가 조언한 내용으로 귀결되는지 확인하는 과정을 시작할 수 있다.

책2.indb 26 2015-04-28 오후 2:34:18

27

API 설계의 세계는 아름답고, 그리고 지금까지 대부분 밝혀지지 않은 채로 남아 있다. 그럼에도

API 설계 지식은 필요하다. 오늘날 구축되고 있는 소프트웨어 시스템들은 규모가 굉장히 커지고 있

고, 소프트웨어 시스템을 적절히 구축하고 신뢰할 수 있게 만들려면 최고의 공학적 실천법을 적용해

야 한다. API 설계는 그러한 실천법 중 하나다. 이 책을 여러분의 21세기 소프트웨어 개발의 안내

서로 삼아라! 우리의 넷빈즈 API 설계 모험이 여러분의 학습 표본이 되게 하고, 그로부터 도출된 일

반적인 조언들이 비슷한 실수를 없애는 데 이바지하게 하라. 여러분이 API 설계 단계들을 매끄럽게

통과하는 데 이 책이 도움되길 바라고, 그리고 그 과정에서 지난 1997년부터 시작된 우리의 여정에

서 발견된 규칙들을 다시금 발명하는 일이 없기를 바란다.

들어가며: 또 한 권의 설계 책인가?

책2.indb 27 2015-04-28 오후 2:34:18

01이론과 정당성

1장: 현대 소프트웨어 구축의 예술

2장: API를 만드는 이유

3장: 훌륭한 API를 결정하는 요소

4장: 시시각각 변하는 표적

PART

책2.indb 28 2015-04-28 오후 2:34:18

291부 ■ 이론과 정당성

애플리케이션 프로그래밍 인터페이스(API; Application Programming Interface )를 만들고

설계하고 작성하는 과정은 예술적인 탐구이자 과학적인 탐구로 볼 수 있다. 관점에 따라 API 아키

텍트는 세상을 바꾸려는 예술가이거나 여러 세계를 잇는 다리를 만들려는 기술자에 해당한다. 내가

아는 대부분의 사람들은 예술가에 가까운데, 예술가야말로 창의성, 자연스러움, 아름다움과 떼려야

뗄 수 없는 관계에 있기 때문이다. 하지만 순수하게 예술적인 접근법에는 중대한 문제가 하나 있다.

바로 감정은 전달 가능하지 않다는 점이다. 감정은 지극히 주관적이다. 다른 이에게 감정을 설명하

는 일에는 복잡성이 따른다. 어떤 정서를 유발하는 작품을 만드는 일은 가능해도, 작품을 감상한 두

사람이 똑같은 반응을 보인다고 보장할 수 없으며, 아마 그것 또한 예술의 목표일 것이다. 결과적으

로 API를 작성하는 아키텍트는 그림을 그리는 예술가와 마찬가지로 자신이 한 일이 잘못 이해될 위

험을 무릅써야 한다. 그러한 경우 API를 사용하는 개발자는 아키텍트의 의도와는 전혀 다른 느낌을

받을 것이다.

그렇더라도 그렇게까지 잘못된 건 아닐지도 모른다. 하지만 문제는 API 아키텍트가 어떤 집단 내에

서 API를 개발하기로 하거나 개발해야 할 때 일어난다. 이 경우 금세 API의 다양한 특성들이 위험

에 노출된다. 예를 들어, API의 가장 중요한 특성은 일관성으로, API 사용자가 미처 예상하지 못한

사항 때문에 생기는 불쾌함을 방지한다. API가 일관성을 유지하려면 설계 집단의 각 구성원 사이에

상당한 조율이 필요하다. 그러나 각 구성원이 API 설계를 개별 예술가의 관점에서 수행한다면 조율

하기가 어렵다. 구성원 사이의 비전 공유가 필요하다. 그리고 그 집단에서 비전을 기술하는 데 쓸 수

있는 어휘가 있어야 한다. 또한 비전을 달성하는 결과를 만들어 내는 데 쓸 방법론도 필요하다. 이를

인식하고 나면 API 아키텍트는 API 설계 프로세스가 예술적 체계가 아닌 공학적 체계가 되기를 바

랄 것이다. 20명의 예술가와 일해본 적이 있고, 그리고 20명의 기술자와 일하는 것과 비교해 본 사

람이라면 왜 그런지 금방 이해할 수 있다.

책2.indb 29 2015-04-28 오후 2:34:19

30 Practical API Design

위원회에 의한 설계

나는 넷빈즈 초창기부터 넷빈즈 API의 대부분을 설계하고 작성했다. 당시 우리는 위원회를 통해서는 훌륭한 API를 설계할

수 없다고 굳게 믿고 있었다. 그렇게 생각한 이유는 다른 개발자들은 주로 설계된 API를 사용하고, API의 기능을 구현하며,

이미 존재하는 API를 평가하고 개선하는 데 목표를 뒀기 때문이다. 하지만 점차 자체적인 API를 만드는 개발자가 나오기 시

작했다.

나는 그러한 시도를 가까이에서 지켜보고, 거기에 조언을 해줬으며, 때때로 다른 개발자들에게 다른 식으로 해보거나 내가

보기에 이상한 부분들을 제거해보라고 말해주기도 했다. 때로는 손수 그러한 부분을 다시 작성해보고 내가 만든 버전을 사

용하길 주장하기도 했다. 하지만 점차 불편한 상황에 처하게 된다는 사실을 깨달았다. API가 어떤 모습이었으면 좋겠는지

알고 있어도 내가 가진 비전을 적절히 설명하지는 못했다. 게다가 동료들이 언제나 내 조언을 귀담아 듣거나 따르고 싶어

하진 않았기에 그들이 왜 내 조언을 고려해봐야 하는지도 설명할 수 없었다. 나는 다른 개발자들이 작업한 결과에 거부권을

행사할 수도 있었지만 그렇게 한다고 해서 문제가 해결되는 것도 아니었다. 뭔가가 잘못됐다는 느낌이 들었다. 그렇지만 잘

못된 것이 무엇이고 왜 잘못됐는지 설명할 수 없었다. 서로 공유하는 용어가 부족해서 의사소통은 제한적이었다. API는 순

수하게 예술적인 접근법으로만 설계됐기에 이러한 상황은 불가피했다.

1년이 지나서야 진상을 파악할 수 있었다. 추가로 개발된 API 하나가 외부 개발자의 관심을 끌었다(넷빈즈는 오픈소스 프

로젝트다). 처음에는 외부 기여자가 버그 수정에 열을 올렸다. 그러더니 자신만의 하위 프로젝트를 만들어서 자체적인 API

를 설계하기 시작했다. API의 원소유자가 나한테 와서 하위 프로젝트의 API가 점점 나빠지고 있는 이유를 찾는 것을 도와

줄 수 있는지 물었다. 그는 새로 만들어진 API를 좋아하지 않았고 자신이 참여 중인 프로젝트에 해당 API가 통합되지 않길

바랐다. 하지만 그 API에서 무엇이 잘못됐는지 표현할 재간이 없었다. 할 수 있는 것은 자신이 가지고 있던 비전에 해당 API

가 부합하지 않는다고 말하는 것 정도였다. 이러한 상황은 내게 완벽한 기시감을 불러일으켰다. 그가 작업한 결과가 넷빈즈

API의 비전(아니면 최소한 내가 해석한 바)에 맞지 않는다고 말했던 적이 있기 때문이다!

나조차도 꽤 오랜 시간이 걸렸지만 API를 설계하고 다른 이들과 함께 내가 좋아하는 API를 설계하

는 일을 한 지 몇 년이 지나서야 비로소 API 설계가 공학적 체계로 접근할 수 있다는 사실을 깨달았

다. 처음에는 그리 분명하지 않았지만 이 분야에도 객관적인 구석이 상당히 많다. 결론적으로 말해

서 API 설계 프로세스는 기술자가 이해할 수 있는 무언가, 즉 과학적인 무언가로 바꾸는 것이 가능

하다.

모든 실제 지식 분야에는 배경이 되는 이론, 바로 해당 분야의 주제를 형성하는 세계를 규정하는 이

론이 필요하다. 그러한 세계는 분명하고 명확하게 규정될 필요가 있다. 분명함이 떨어질수록 학문

의 엄밀함도 떨어지고, 예술에 더 가까워진다. 1장에서는 API 설계라는 세계를 정의한다. 여기서는

API 설계에서 다뤄야 할 다양한 주제를 살펴본다. 그리고 API 설계 과정에서 마주치게 될 상황에

대해서도 분석한다. 아울러 동일한 이론을 알고 있는 사람들이 API 세계를 구성하는 요소와 그러한

책2.indb 30 2015-04-28 오후 2:34:19

311부 ■ 이론과 정당성

요소 간의 관계를 더 잘 파악하는 데 활용할 수 있는 공통 어휘를 구축하기 시작한다. 이러한 기반을

토대로 나중에 API 설계 이론이라는 주제에 관해 좀 더 복잡하고 불확실한 결론을 내릴 수 있다.

사용자층이 두터운(특히 전 세계 사람들이 사용하는) 좋은 API를 작성하기란 쉽지 않다. 모든 사람

에게는 문제를 이해하고 바라보는 자신만의 방법이 있다. 그들을 한 번에 모두 만족시키기란 대체로

불가능하다. 게다가 API가 전 세계 사용자를 대상으로 삼는다면 다양한 문화적 차이도 다뤄야 한

다. 이러한 이유로 훌륭하고 사용자층이 두터운 API를 작성하는 일이 어려운 것이다.

전 세계 독자를 대상으로 책을 쓰는 것도 마찬가지로 쉽지 않은 일이다. 다시 말하지만, 개인적 선

호 및 문화적 선호와 관련된 문제는 사람들이 읽고 싶어하는 방식에 영향을 준다. 개중엔 배경을 먼

저 알고 싶어 하는 사람들도 있고 바로 예제로 건너뛰어 전체적으로 내용이 유용한지 알고 싶어하는

사람들도 있다. 이러한 두 진영을 한꺼번에 모두 만족시키기란 불가능해 보인다. 에드거 W. 다익스

트라(Edsger W. Dijkstra )가 자신의 논문인 “대서양에는 두 면이 있다는 사실에 관하여”1에서 아

주 잘 기술했듯이 어떤 사람들은 이론적인 접근법이 어렵고 지루하며, 더 나아가 실전 예제는 훨씬

더 흥미롭다고 생각한다. 아마 그들이 한 말은 적어도 문화적인 맥락에서는 맞을지도 모른다. 반면

또 어떤 사람들은 공통 어휘를 구축하는 데 시간을 더 보내고 탐험 중인 세계를 차근차근 이해하고

싶어 한다. 내용 소개를 빠짐없이 하지 않고는 이렇게 하기가 쉽지 않다. 하지만 그렇게 하지 않으면

용어가 두 가지 의미를 지닐 수도 있고, 이것은 종종 혼동을 야기한다. 분명 두 진영을 한 번에 만족

시키기란 쉬운 일이 아니다. 하지만 나는 모든 사람들을 만족시키기 위해 최선을 다하겠다.

안정적인 API

우리가 탐구하고자 하는 이 세계의 기본적인 용어 중 하나는 안정적인 API다. 나는 이 용어를 넷빈즈 프로젝트에서 다양한

사람들과 이야기할 때 아주 많이 사용해 왔고, 이때 아무런 문제도 예상하지 않았다. 그동안 이 용어는 내게 아주 명확하고

분명한 의미를 지닌 단어로 보였다.

그런 후에 나는 동료 중 한 명이 그 용어를 설명하는 것을 들은 적이 있다. 그는 API가 절대로 변화를 겪지 않아야만 해당 API

가 안정적이라고 이야기했다! 안정적인 API가 일종의 “안정성”을 띨 가능성은 높지만 그럼에도 때로는 변경될 필요가 있다.

나는 이처럼 기본 API 어휘에서 나온 용어의 의미가 사람들마다 다른 해석 오류의 문제를 늘 겪는다. 당연히 이 같은 해석

오류는 대화 전체를 망친다. 사람들이 서로를 이해한다고 생각한다면(실제로는 그렇지 않은데도) 아예 이야기를 나누지 않

는 편이 낫다. 이야기할 때 구체화되는 이미지는 완전히 엇갈리고, 그러한 것들은 의사소통에 결코 도움되지 않는다.

이러한 이유로 기본 용어를 정의하는 데 시간을 들이는 것이 좋다고 생각한다.

1 에드거 다익스트라, “대서양에는 두 면이 있다는 사실에 관하여(On the fact that the Atlantic Ocean has two sides)”(1976), http://www.cs.utexas.edu/~EWD/

transcriptions/EWD06xx/EWD611.html

책2.indb 31 2015-04-28 오후 2:34:20

32 Practical API Design

용어에 관한 혼동을 방지하고자 1부에서는 어휘 구축과 API 설계의 일반적인 측면을 분석하는 데

할애한다. 여기서는 기본 용어의 어휘를 구축하고 전체적인 API 설계 노력의 동기를 설명하며, 설

계 과정의 주요 목표를 대략적으로 잡는다. 이러한 학습 방식이 마음에 들지 않고 기초적인 내용이

필요하지 않는다고 생각한다면 훨씬 많은 코드 예제와 팁, 요령, 다양한 기법이 담긴 2부로 바로 넘

어가도 무방하다. 2부의 내용이 낯설어 보여도 놀라진 말자. 그것은 1부에서 다루는 배경 지식을 건

너뛰었다는 신호일지도 모른다. 아울러 도구, 컴파일러 등에 관한 실질적인 조언을 얻고 싶다면 3부

부터 읽어도 된다. 그러나 재차 말하지만 앞에서 경고한 바를 염두에 두자. 내가 제시한 조언이 이해

되지 않는다면 그것은 기반이 되는 API 설계 이론과 관련 내용을 이해하지 않고 건너뛰었기 때문일

지도 모른다.

더는 지체하지 말고 이론으로 뛰어들자. 먼저 진행 속도에 박차를 가할 기초적인 사항을 살펴보겠

다. 적절한 API 설계에 대한 감을 잡기 위해 왜 API를 설계하고, 무엇을 설계하며, 어떻게 설계하는

가에 관한 가장 기본적인 질문으로 시작해보자.

책2.indb 32 2015-04-28 오후 2:34:20