점검표

개요

이 문서는 api-design 섹션의 핵심을 점검표로 압축한 것이다. 현재 API 표면이 하네스 친화적인지 빠르게 확인할 때 쓴다.

1. 합법 경로 우선 ^{legal path}

• 공식 entry point가 가장 먼저 보이는가
• 정상 경로가 우회보다 짧거나 최소한 덜 귀찮은가
• 대부분의 흔한 시나리오가 공식 경로 안에서 끝나는가
• 새 팀원이나 AI가 주변 코드만 보고도 그 경로를 찾을 수 있는가

아니오가 많다면 합법 경로 설계가 먼저다.

2. 표면 축소 ^surface

• 같은 일을 하는 entry point가 여러 개 있지 않은가
• 공개 surface가 내부 계층을 과도하게 노출하지 않는가
• facade, command, query 같은 명확한 진입점이 있는가
• helper가 사실상 두 번째 공식 API가 되어 있지 않은가

아니오가 많다면 표면을 좁히는 편이 낫다.

3. 계약 형태 ^contract

• command와 DTO가 허용된 행위와 경계를 분명히 드러내는가
• raw object나 mutable reference를 불필요하게 노출하지 않는가
• result shape가 실패를 숨기지 않는가
• 호출자가 내부 구현을 추측하지 않아도 되는가

아니오가 많다면 contract shape가 우회를 허용하고 있다.

4. 우회 없는 편의 ^convenience

• convenience API가 공식 경로 위에 있는가
• validation과 guard를 유지하는가
• 실패를 default 처리로 숨기지 않는가
• naming이 실제 경계와 정직하게 맞는가
• test convenience도 production 경계를 존중하는가

아니오가 많다면 convenience가 사실상 bypass일 가능성이 크다.

5. 다음 액션 ^{next action}

다음 항목 중 무엇이 가장 심각한지 먼저 표시하면 된다.

• 가장 자주 쓰이는 비공식 entry point
• 가장 위험한 helper / util shortcut
• 가장 넓게 노출된 raw object
• 가장 자주 fallback을 유발하는 result shape
• 가장 먼저 facade로 수렴시킬 수 있는 surface

이 체크리스트의 목적은 점수화가 아니라, 다음으로 정리할 API 표면을 고르는 것이다.

요약

좋은 하네스 친화적 API는 다음 질문에 예가 많다.

• 정상 경로가 먼저 보이는가
• surface가 좁은가
• 계약이 내부 구조를 숨기는가
• convenience가 bypass가 아닌가

반대로 아니오가 많은 항목이 곧 다음 설계 우선순위다.