---
kind: REFERENCE
slug: compare-the-contract-with-both-implementations
title: 계약과 구현은 서버와 화면 양쪽에서 전수 대조한다
topic: declared-but-not-implemented
topicName: 계약에 선언만 있고 구현이 없다
project: TechLog
status: 게시 전
verifiedOn: 2026-09-04
sourceRevision: tech-log@2026-09-02
source:
  - final/document.md#§4.3
  - final/document.md#§4.4
---

# 계약과 구현은 서버와 화면 양쪽에서 전수 대조한다

계약이 한 저장소에 있고 두 저장소가 그것을 반입해 각자 구현하면, 어느 한쪽이 빠뜨린 것을 컴파일러가 보지 못한다. 이 저장소에서 그 구멍이 서버 쪽으로 다섯 번, 화면 쪽으로 네 번 났다. 두 쪽 모두에서 계약과 대조하는 검사를 돌린다.

## 관계

- **계약에 선언만 있고 구현이 없어 화면 다섯 곳이 비어 있었다**
  서버 쪽 누락의 근거 사건이다.
- **타입에는 보이는데 부를 수 없는 연산이 네 번 나왔다**
  화면 쪽 누락의 근거 사건이다.
- **종류를 나열하는 곳은 컴파일러나 계약 대조 검사가 세게 만든다**
  컴파일러가 볼 수 있는 범위 안쪽을 다루는 짝이 되는 기준이다.

## 목적

계약이 선언한 연산에 구현이 없는 상태를 배포 전에 잡는다.

이 상태는 오류를 내지 않는다. 서버는 404 를 주고 화면은 그것을 빈 데이터로 그린다. 계약에서 모델을 생성하는 단계도 스키마와 속성만 보므로 구현이 없어도 모델이 만들어지고 컴파일이 통과한다.

## 규칙

### 1. 서버 쪽은 매핑을 리플렉션으로 모아 계약의 경로와 전수 대조한다

`@RestController` 들을 훑어 실제 매핑을 모으고 계약이 선언한 경로 전부와 맞춘다. 기대 목록을 손으로 적으면 그 목록이 또 하나의 손 목록이 되므로 계약에서 읽는다.

### 2. 화면 쪽은 계약이 선언한 연산이 기여 목록에 등록됐는지 본다

타입은 계약에서 생성되므로 등록을 빠뜨려도 에디터에서 그 연산이 보이고 컴파일이 통과한다. 그 상태에서 부르면 게이트웨이가 등록된 것 중에서 고르므로 옆 분기로 떨어지고, 서버는 그 요청에 정상 응답한다.

### 3. 구현하지 않기로 한 연산은 이유와 함께 명시 목록에 넣는다

「빠뜨린 것」과 구분되지 않으면 대조 결과가 곧 무시된다. 이 저장소는 작업본 API 로 대체된 옛 연산 51개를 그 이름의 상수에 담고, 봉투 없이 바이트를 주는 연산 하나를 별도 상수로 면제한다. 면제가 코드에 이름으로 남아 다음 사람이 세어 볼 수 있다.

### 4. 두 쪽 다 돌린다

한쪽만 대조하면 다른 쪽을 지웠을 때 잡히지 않는다.

### 5. 생성 모델 검사를 이 대조로 세지 않는다

모델 생성은 스키마와 속성만 본다. 구현이 없어도 모델은 멀쩡히 만들어진다.

### 6. 전수 대조가 무거우면 깨지는 모양으로 좁힌다

관리 계약은 86 operation 이라 전수 대조가 무겁다. 이 저장소는 대신 「한 종류만 빠진 항목」을 보게 했다 — 깨진 것이 늘 그 모양이었기 때문이다. 좁힌 기준은 무엇을 보지 않는지도 함께 적는다.

## 적용 조건

- 계약이 한 저장소에 있고 두 저장소가 그것을 반입해 각자 구현하는 구조. 연산을 더하거나 지우는 변경에서 이 대조를 돌린다.

- 화면이 「데이터가 없습니다」를 그리는데 저장소에는 값이 있을 때 이 대조를 먼저 본다. 구현이 없어서 404 인 것과 정말 0건인 것이 화면에서 같아 보인다.

## 예외

- 계약과 구현이 같은 저장소에 있고 같은 빌드를 지나면 컴파일러가 이 대조를 대신한다.

- 연산이 봉투 규약을 따르지 않으면 경로 대조에서 뺀다. 다만 뺀 이유를 목록에 적는다.

## 예시

- 매핑 하나를 떼어 보고 대조 검사가 그 연산 하나를 정확히 짚는 것을 확인한 뒤 커밋했다.

- 두 목록 조회에 컨트롤러가 없어 홈 편집기가 「이 프로젝트에 열린 질문이 없습니다」를 그렸다. 실제로는 넷이 있었고 공개 사이트에도 나오고 있었다.

- 옛 연산 51개를 명시하지 않았다면 대조 결과가 51건의 실패로 나와 아무도 읽지 않았을 것이다.

- 기여 목록에 등록하지 않은 연산 넷을 만났다. 둘은 옆 분기로 떨어져 다른 기록을 다뤘고 둘은 빈 목록이 됐다.