project-auth-server/docs/standards/design/interface-creation.md

interface 생성 기준

목적

인터페이스는 “있으면 좋아 보이는 추상화”가 아니라, 경계와 계약을 안정적으로 표현해야 할 때만 만든다.
기본값은 “인터페이스를 무조건 만들지 않는다”이다.

공식 의미

• 인터페이스는 구현과 분리된 계약(contract)을 표현하는 타입이다.
• 구현체는 인터페이스가 정한 메서드 계약을 따른다.
• 인터페이스는 추상 메서드, default method, static method, 상수를 가질 수 있다.
• Spring DI는 의존 객체를 생성자/팩토리 메서드/세터를 통해 주입하며, 인터페이스나 추상 베이스 타입에 의존할 때 결합도가 낮아지고 테스트 대역 사용이 쉬워진다.
• Spring AOP는 대상이 인터페이스를 구현하면 JDK dynamic proxy를 기본으로 사용한다.

기본 규칙

1. 기본값은 “필요할 때만 만든다”

다음 중 하나가 아니라면 인터페이스를 만들지 않는다.

• 모듈/레이어 경계를 표현해야 한다
• 교체 가능한 구현이 실제로 존재하거나 가까운 미래에 예상된다
• 테스트에서 대역(stub/mock/fake)으로 치환하는 가치가 크다
• 프레임워크/프록시/AOP/플러그인 구조상 계약 타입이 분명히 필요하다
• 라이브러리/외부 모듈에 공개할 안정된 API 계약이 필요하다

2. “구현체 1개” 자체는 금지 근거가 아니지만, “이유 없는 인터페이스”는 금지

구현체가 1개여도 아래 중 하나면 인터페이스를 둘 수 있다.

• application port
• 외부 연동 client contract
• repository-like boundary
• 인증/토큰/암호화 같은 교체 가능한 정책

반대로 구현체가 1개이고 아래도 아니면 인터페이스를 만들지 않는다.

• 내부 helper/service
• 단순 orchestration class
• 프레임워크가 요구하지 않는 내부 컴포넌트

3. 레이어 경계는 인터페이스를 우선 검토

특히 다음 경계는 인터페이스를 우선 검토한다.

• application port/in
• application port/out
• infrastructure adapter가 구현하는 계약
• 외부 시스템 client contract
• 교체 가능한 정책 객체

즉 “안쪽이 바깥 구현을 모르면 좋은 곳”은 인터페이스 후보가 된다.

4. 내부 구현 디테일에는 기본적으로 인터페이스를 만들지 않는다

같은 모듈 내부에서만 쓰이고, 교체 가능성도 낮고, 테스트 seam 가치도 낮은 클래스는 concrete class 그대로 둔다.

금지 예:

• UserService + UserServiceImpl
• EmailNormalizer + EmailNormalizerImpl
• AuthFacade + AuthFacadeImpl

단, 정말 계약 타입이 먼저이고 구현이 뒤따르는 구조면 예외다.

5. 인터페이스는 “역할”을 표현해야 한다

인터페이스 이름은 구현 방식이 아니라 역할/능력을 드러내야 한다.

좋은 방향:

• UserReader
• PasswordHasher
• JwtSigner
• TokenIssuer
• UserRepository
• OAuthClient

지양:

• DefaultUserService
• CommonManager
• BaseHandler

6. 인터페이스는 작고 응집도 있게 유지

인터페이스는 하나의 역할/계약에 집중해야 한다.

금지:

• unrelated method를 한 인터페이스에 몰아넣기
• “편해서” 여러 책임을 한 계약에 합치기
• consumer마다 일부만 필요한 fat interface

7. 인터페이스는 구현 세부보다 호출 계약을 고정

인터페이스는 아래를 고정해야 한다.

• 어떤 입력을 받는가
• 어떤 결과를 돌려주는가
• 어떤 예외/실패 의미가 가능한가
• 어떤 side effect/보장이 있는가

반대로 아래는 인터페이스에 새지 않게 한다.

• HttpClient/WebClient/JPA/Redis/Jackson 등 기술 세부
• 프레임워크 구체 타입
• 구현체 내부 최적화 방식

8. default method는 “계약 핵심”보다 “하위 호환/작은 공통 동작”에만 제한

Oracle 문서상 default method는 기존 구현과의 binary compatibility를 유지하면서 기능을 추가할 수 있다.
프로젝트에서는 아래일 때만 제한적으로 허용한다.

• 라이브러리/공용 계약의 하위 호환이 중요하다
• 매우 작은 convenience 동작이다
• 구현체 대부분에 동일하게 자연스럽다

기본값은 추상 메서드다.
비즈니스 핵심 로직을 default method로 밀어 넣지 않는다.

9. 인터페이스 static method는 그 계약에만 밀접한 helper일 때만

Oracle 문서상 인터페이스는 static method를 가질 수 있다.
프로젝트에서는 그 helper가 해당 인터페이스 계약과 아주 밀접할 때만 허용한다.

그 외 일반 helper는 별도 타입/유틸로 분리한다.

10. 인터페이스 상수 남용 금지

인터페이스는 상수 묶음 용도로 만들지 않는다.
상수는 계약의 본질이 아닐 경우 별도 적절한 소유 타입에 둔다.

11. Spring 프록시/AOP 때문에 인터페이스를 만들 수는 있지만, 그 이유를 과장하지 않는다

Spring은 인터페이스가 있으면 JDK dynamic proxy를 기본으로 사용한다.
하지만 “프록시 가능”만으로 모든 클래스 앞에 인터페이스를 두지 않는다.

기본 판단 순서:

1. 이 타입이 경계/계약인가?
2. 교체/테스트/AOP 가치가 있는가?
3. concrete class로 두는 것이 더 단순한가?

12. 테스트를 위해서만 인터페이스를 남발하지 않는다

Spring DI 문서는 인터페이스/추상 베이스 타입이 테스트 대역 사용을 쉽게 한다고 설명한다.
하지만 “테스트가 쉬워 보인다”는 이유만으로 의미 없는 인터페이스를 만들지 않는다.

다음도 대안이 될 수 있다.

• package-private concrete class 테스트
• 더 작은 collaborator 분리
• test fixture/fake 구현
• 포트 레벨에서만 seam 만들기

13. public API / multi-module contract는 인터페이스 우선 검토

다른 모듈/패키지/팀이 사용할 public contract면 인터페이스를 우선 검토한다.
이 경우 호출자와 구현체를 느슨하게 분리할 가치가 크다.

14. 조기 추상화 금지

겉보기 유사성만 보고 인터페이스를 먼저 만들지 않는다.

다음 질문 중 “예”가 충분히 쌓일 때 만든다.

• 정말 다른 구현이 필요한가?
• 호출자가 구현이 아니라 계약에 의존해야 하는가?
• 이 추상화가 6개월 뒤에도 자연스러운가?
• 이 인터페이스가 테스트/교체/경계 보호에 실제 도움 되는가?

프로젝트 기준 요약

• 인터페이스 기본값은 “필요할 때만”
• application port / 외부 경계 / 교체 정책은 인터페이스 우선
• 내부 helper/orchestration에는 기본적으로 인터페이스 금지
• XService + XServiceImpl 자동 생성 금지
• 역할 중심 이름 사용
• 기술 세부를 계약에 노출하지 않음
• default/static method는 제한적으로만 허용
• 프록시 가능성만으로 인터페이스를 만들지 않음
• 조기 추상화 금지