편의와 우회의 분리
개요
하네스 친화적 API가 된다고 해서 모든 API를 불편하게 만들어야 하는 것은 아니다. 문제는 편의 자체가 아니라, 편의 API가 경계를 우회하는 shortcut이 되는 순간이다.
이 문서는 편의는 제공하되 우회는 만들지 않는 방법을 다룬다.
1. 왜 convenience가 필요한가
정상 경로가 지나치게 번거로우면, 사람도 AI도 곧 더 짧은 비공식 경로를 만든다.
따라서 convenience는 사치가 아니라 통제를 위한 투자다. 좋은 convenience는 다음을 만든다.
- 정상 경로의 마찰 감소
- API 발견 가능성 증가
- boilerplate 감소
- 공식 경로 재사용 증가
2. 나쁜 convenience의 특징
나쁜 convenience는 사실상 bypass다.
예:
- validation을 건너뛰는 helper
- 내부 service를 직접 노출하는 util
- provider 없이 동작하는 shortcut hook
- command 대신 direct mutation helper
- 실패를 default 값으로 덮는 sugar API
이런 API는 겉으로는 편하지만, 실제로는 경계를 무너뜨린다.
3. 좋은 convenience의 조건
공식 경로 위에 있어야 한다
convenience는 facade, command, validated path 위에 얹혀야 한다. 공식 경로를 대체하면 안 된다.
guard와 validation을 유지해야 한다
편의 때문에 검증이 사라지면 안 된다. 편의는 줄일 수 있어도 생략하면 안 되는 단계가 있다.
실패를 숨기지 않아야 한다
편리하다는 이유로 에러를 default 처리하면, 사용자는 구조 위반을 인식하지 못한다.
naming이 정직해야 한다
helper 이름이 공식 API처럼 보이는데 실제로는 우회라면, 팀은 곧 그 helper를 표준처럼 사용한다.
4. 좋은 convenience 패턴
- validated facade 위에 thin helper 추가
- 자주 쓰는 command 조합을 wrapper로 제공
- common parameter를 묶는 builder 제공
- read-only query helper 제공
- test에서도 같은 공식 경로를 쓰게 하는 fixture helper 제공
공통점은 하나다.
공식 경로를 짧게 만들 뿐, 새 경로를 만들지 않는다.
5. convenience를 설계할 때 보는 질문
- 이 helper는 공식 경로 위에 있나, 밖에 있나
- validation과 guard를 유지하나
- naming이 실제 경계와 맞나
- 실패를 숨기지 않나
- 이 helper가 팀의 새 표준 진입점이 되더라도 구조가 안전한가
마지막 질문에 아니오라면,
그 convenience는 사실상 bypass 후보다.
6. test convenience는 더 조심해야 한다
테스트 helper는 학습 자료가 되기 쉽다. 그래서 test convenience는 특히 더 조심해야 한다.
좋은 방향:
- production과 같은 facade를 사용한다
- fixture 생성만 편하게 하고 경계는 유지한다
- 검증을 끄지 않는다
나쁜 방향:
- test에서만 direct mutation helper 제공
- provider bypass helper 제공
- validation-off helper 제공
요약
좋은 convenience는 다음을 만족한다.
- 공식 경로 위에 존재한다
- validation과 guard를 유지한다
- 실패를 숨기지 않는다
- naming이 정직하다
- 팀의 기본 사용법이 되어도 구조를 무너뜨리지 않는다
좋은 convenience는 shortcut이 아니라, 정상 경로를 더 짧게 만든 공식적인 편의다.