2nd/10_Wiki/Topics/Architecture/외부_라이브러리_API_설계.md

id, title, category, status, canonical_id, aliases, duplicate_of, source_trust_level, confidence_score, verification_status, tags, raw_sources, last_reinforced, github_commit, tech_stack

id	title	category	status	canonical_id	aliases	duplicate_of	source_trust_level	confidence_score	verification_status	tags	raw_sources	last_reinforced	github_commit	tech_stack
wiki-2026-0508-외부-라이브러리-api-설계	외부 라이브러리 API 설계	10_Wiki/Topics	verified	self	Library API Design Public API Design SDK Design	none	A	0.9	applied	api-design library-design sdk dx		2026-05-10	pending	language framework typescript none

외부 라이브러리 API 설계

매 한 줄

"매 public surface는 영원하다". 외부 라이브러리(npm, PyPI, Maven 배포물)의 public API는 한 번 release되면 호환성 부담을 평생 짊어진다 — Joshua Bloch의 "API design is hard, and the consequences of failure are forever". Hyrum's Law 전제 하에 minimal surface + clear versioning + predictable failure를 설계.

매 핵심

매 5 원칙

• Easy to use, hard to misuse (Bloch): default가 옳고, 잘못된 사용은 type error로 차단.
• Minimal surface: 의심스러우면 빼라 — 추가는 쉽고 제거는 breaking change.
• Orthogonal: 한 기능 = 한 방법. 두 가지가 같은 일을 하면 사용자 confusion + maintenance 부담.
• Failure mode 명확: throw vs Result, sync vs async, retry semantics — 문서가 아닌 type으로.
• SemVer 엄수: minor에서 breaking 금지. CI에 API diff 검사.

매 layered API

• Core (low-level): 모든 capability 노출, escape hatch 제공.
• Sugar (high-level): 80% use case 한 줄 처리. Core 위에 build.
• 두 layer를 분리하면 power user와 casual user 모두 만족.

매 응용

1. HTTP client: fetch-style core + client.get(path, opts) sugar.
2. DB driver: raw query + query builder + ORM (3 layer).
3. AI SDK: messages.create core + messages.stream + agent helper.

💻 패턴

Tagged result로 failure mode를 type에 박기

// 안티: throw + any error type
export async function fetchUser(id: string): Promise<User> { ... }

// 좋음: Result<T, E> — 호출자가 처리 강제
export type Result<T, E> =
  | { ok: true;  value: T }
  | { ok: false; error: E };

export type FetchError =
  | { kind: 'not_found' }
  | { kind: 'unauthorized' }
  | { kind: 'network'; cause: Error };

export async function fetchUser(id: string): Promise<Result<User, FetchError>> {
  // ...
}

// 사용자 코드
const r = await fetchUser('u1');
if (!r.ok) {
  switch (r.error.kind) {  // 컴파일러가 exhaustive 검사
    case 'not_found':    return notFound();
    case 'unauthorized': return redirect();
    case 'network':      return retry();
  }
}

Builder for many optional knobs

// 안티: optional 폭발
client.query('SELECT ...', undefined, undefined, 30_000, true, 'replica');

// 좋음: builder
client.query('SELECT ...')
  .timeout(30_000)
  .readReplica()
  .stream()
  .execute();

Branded types로 misuse 차단

type UserId  = string & { readonly __brand: 'UserId' };
type OrderId = string & { readonly __brand: 'OrderId' };

export const UserId  = (s: string): UserId  => s as UserId;
export const OrderId = (s: string): OrderId => s as OrderId;

export function getUser(id: UserId): Promise<User> { ... }

getUser(orderId);          // ❌ 컴파일 에러 — UserId가 아님
getUser(UserId('u_42'));   // ✅

Default + override

export interface ClientOptions {
  baseUrl?:    string;            // default: 'https://api.example.com'
  timeoutMs?:  number;            // default: 30_000
  fetch?:      typeof globalThis.fetch;
  retry?:      RetryPolicy | false;
}

const DEFAULTS = {
  baseUrl:   'https://api.example.com',
  timeoutMs: 30_000,
  fetch:     globalThis.fetch.bind(globalThis),
  retry:     { attempts: 3, backoff: 'exponential' } as RetryPolicy,
};

export class Client {
  private readonly opts: Required<ClientOptions>;
  constructor(opts: ClientOptions = {}) {
    this.opts = { ...DEFAULTS, ...opts };
  }
}

@deprecated + transition path

/**
 * @deprecated since 2.3.0 — use {@link createClient} which returns a Result.
 *   Will be removed in 3.0.
 */
export function newClient(opts: ClientOptions): Client { ... }

export function createClient(
  opts: ClientOptions,
): Result<Client, ConfigError> { ... }

Public surface diff in CI (api-extractor)

// api-extractor.json
{
  "mainEntryPointFilePath": "<projectFolder>/dist/index.d.ts",
  "apiReport": { "enabled": true, "reportFolder": "etc/" }
}

# CI: 변경 시 api report diff → PR에서 reviewer가 명시적 승인
api-extractor run --local && git diff --exit-code etc/

Stable v1 export root

// src/index.ts — public re-export only
export { Client } from './client';
export type { ClientOptions, Result, FetchError } from './types';
// 내부 구현은 export 금지 — 사용자가 deep import 하면 lock-in

매 결정 기준

상황	Approach
Library 내부 use, 사용자 < 10	가볍게 — minimal versioning
OSS 공개, 사용자 unknown	매 strict — SemVer + API diff CI
Experimental feature	unstable_ prefix + @experimental
Breaking change 필요	major version + codemod 제공

기본값: public export는 index.ts 하나로 묶고, 모든 그 외 path는 internal로 간주.

🔗 Graph

• 부모: API Design · Library Design
• 변형: SDK Design · Public API
• Adjacent: Backward Compatibility

🤖 LLM 활용

언제: 신규 라이브러리 export root 설계, deprecation 전략 수립, API diff PR 리뷰. 언제 X: 단일 앱 내부 모듈 — 그 정도 ceremony는 과잉.

❌ 안티패턴

• 모든 internal export: 사용자가 deep import → 내부 변경 = breaking change.
• boolean flag 폭발: fn(x, true, false, true) — 의미 불명. Object option으로.
• Throw + 문서로만 명시: type system이 강제하지 않으면 무시됨.
• Minor에서 behavior 변경: SemVer 위반 — 신뢰 파괴.

🧪 검증 / 중복

• Verified (Joshua Bloch, "How to Design a Good API and Why It Matters"; Microsoft API Design Guidelines).
• 신뢰도 A.

🕓 Changelog

날짜	변경
2026-05-08	Phase 1
2026-05-10	Manual cleanup — Bloch 원칙·layered API·CI diff 패턴