DongHyeonkaandClaude Opus 5
193da20d09
게시된 Reference 15편이 전부 규칙을 `### N. 제목` 으로 쓰고 적용 조건·예외·예시를 항목으로 쓴다. 내 15편은 규칙을 `**굵게**` 로, 나머지 셋을 문단으로 쓰고 있었다 — Studio 의 rules[]·applyWhen[]·exceptions[]·examples[] 는 배열이라 문단으로 두면 항목이 하나로 접힌다. 규칙 68개를 `### N. 제목` 으로 바꿨다 (편당 3~7개, 게시된 것은 4~10개) 적용 조건·예외·예시를 항목으로 갈랐다. 한 항목뿐이던 아홉 편은 조건을 나눠 적었다 주제 6 은 본문을 다시 썼다 — location = 이 정확히 일치하는 경로만 잡아 27개가 얼어붙은 구조, 여덟 곳이 우는 시점을 셋으로 가른 표, digest 를 다시 계산할 때 옛 값을 먼저 재현하는 이유. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
4.5 KiB
kind, slug, title, topic, topicName, project, status, verifiedOn, sourceRevision, source
| kind | slug | title | topic | topicName | project | status | verifiedOn | sourceRevision | source | ||
|---|---|---|---|---|---|---|---|---|---|---|---|
| REFERENCE | compare-the-contract-with-both-implementations | 계약과 구현은 서버와 화면 양쪽에서 전수 대조한다 | declared-but-not-implemented | 계약에 선언만 있고 구현이 없다 | TechLog | 게시 전 | 2026-09-04 | tech-log@2026-09-02 |
|
계약과 구현은 서버와 화면 양쪽에서 전수 대조한다
계약이 한 저장소에 있고 두 저장소가 그것을 반입해 각자 구현하면, 어느 한쪽이 빠뜨린 것을 컴파일러가 보지 못한다. 이 저장소에서 그 구멍이 서버 쪽으로 다섯 번, 화면 쪽으로 네 번 났다. 두 쪽 모두에서 계약과 대조하는 검사를 돌린다.
관계
- 계약에 선언만 있고 구현이 없어 화면 다섯 곳이 비어 있었다 서버 쪽 누락의 근거 사건이다.
- 타입에는 보이는데 부를 수 없는 연산이 네 번 나왔다 화면 쪽 누락의 근거 사건이다.
- 종류를 나열하는 곳은 컴파일러나 계약 대조 검사가 세게 만든다 컴파일러가 볼 수 있는 범위 안쪽을 다루는 짝이 되는 기준이다.
목적
계약이 선언한 연산에 구현이 없는 상태를 배포 전에 잡는다.
이 상태는 오류를 내지 않는다. 서버는 404 를 주고 화면은 그것을 빈 데이터로 그린다. 계약에서 모델을 생성하는 단계도 스키마와 속성만 보므로 구현이 없어도 모델이 만들어지고 컴파일이 통과한다.
규칙
1. 서버 쪽은 매핑을 리플렉션으로 모아 계약의 경로와 전수 대조한다
@RestController 들을 훑어 실제 매핑을 모으고 계약이 선언한 경로 전부와 맞춘다. 기대 목록을 손으로 적으면 그 목록이 또 하나의 손 목록이 되므로 계약에서 읽는다.
2. 화면 쪽은 계약이 선언한 연산이 기여 목록에 등록됐는지 본다
타입은 계약에서 생성되므로 등록을 빠뜨려도 에디터에서 그 연산이 보이고 컴파일이 통과한다. 그 상태에서 부르면 게이트웨이가 등록된 것 중에서 고르므로 옆 분기로 떨어지고, 서버는 그 요청에 정상 응답한다.
3. 구현하지 않기로 한 연산은 이유와 함께 명시 목록에 넣는다
「빠뜨린 것」과 구분되지 않으면 대조 결과가 곧 무시된다. 이 저장소는 작업본 API 로 대체된 옛 연산 51개를 그 이름의 상수에 담고, 봉투 없이 바이트를 주는 연산 하나를 별도 상수로 면제한다. 면제가 코드에 이름으로 남아 다음 사람이 세어 볼 수 있다.
4. 두 쪽 다 돌린다
한쪽만 대조하면 다른 쪽을 지웠을 때 잡히지 않는다.
5. 생성 모델 검사를 이 대조로 세지 않는다
모델 생성은 스키마와 속성만 본다. 구현이 없어도 모델은 멀쩡히 만들어진다.
6. 전수 대조가 무거우면 깨지는 모양으로 좁힌다
관리 계약은 86 operation 이라 전수 대조가 무겁다. 이 저장소는 대신 「한 종류만 빠진 항목」을 보게 했다 — 깨진 것이 늘 그 모양이었기 때문이다. 좁힌 기준은 무엇을 보지 않는지도 함께 적는다.
적용 조건
-
계약이 한 저장소에 있고 두 저장소가 그것을 반입해 각자 구현하는 구조. 연산을 더하거나 지우는 변경에서 이 대조를 돌린다.
-
화면이 「데이터가 없습니다」를 그리는데 저장소에는 값이 있을 때 이 대조를 먼저 본다. 구현이 없어서 404 인 것과 정말 0건인 것이 화면에서 같아 보인다.
예외
-
계약과 구현이 같은 저장소에 있고 같은 빌드를 지나면 컴파일러가 이 대조를 대신한다.
-
연산이 봉투 규약을 따르지 않으면 경로 대조에서 뺀다. 다만 뺀 이유를 목록에 적는다.
예시
-
매핑 하나를 떼어 보고 대조 검사가 그 연산 하나를 정확히 짚는 것을 확인한 뒤 커밋했다.
-
두 목록 조회에 컨트롤러가 없어 홈 편집기가 「이 프로젝트에 열린 질문이 없습니다」를 그렸다. 실제로는 넷이 있었고 공개 사이트에도 나오고 있었다.
-
옛 연산 51개를 명시하지 않았다면 대조 결과가 51건의 실패로 나와 아무도 읽지 않았을 것이다.
-
기여 목록에 등록하지 않은 연산 넷을 만났다. 둘은 옆 분기로 떨어져 다른 기록을 다뤘고 둘은 빈 목록이 됐다.