docs(TechLog): 주제 4·5 를 스킬대로 다시 쓴다

what-the-compiler-lets-through 중앙값 2,096 → 2,590 자 seams-no-test-crosses → 3,091 자 bivariance 가 왜 느슨한 판정을 받는지, never 캐스트가 왜 아무것도 요구하지 않는지처럼 「이름을 댔으면 왜 있는지도 댄다」를 채웠다. 네 가지가 각각 무엇을 통과시키고 어디서 드러났는지를 표로 갈랐다. 검사 넷 중 무엇이 SQL 을 실제로 돌리는지도 표로 세웠다. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-09-07 18:57:59 +09:00
parent a8ce0dda07
commit 53537e37e8
8 changed files with 140 additions and 51 deletions
@@ -62,11 +62,13 @@ tech-log-frontend : 03986da · 7600711

 ## 세 결함이 서로를 가렸다

+공개 소스가 정적 픽스처에서 HTTP 어댑터로 바뀐 뒤 로그아웃 상태 방문자가 요청을 하나도 내보내지 못했다. 이 경로는 그 주까지 브라우저에서 한 번도 돌지 않았다.
+
 첫 번째만 고쳤을 때 요청이 나가기 시작했고, 그러자 두 번째가 드러났다. 두 번째를 고치니 세 번째가 나왔다.

-`attachCredentials` 가 Studio 헬퍼에 먼저 묻는데, 그 헬퍼는 자기 것이 아닌 프로파일에 `null` 을 돌려준다. 그 아래 폴백이 세션을 읽고 인증되지 않은 것을 거절한다. 공개 읽기는 ANONYMOUS 프로파일을 선언하므로 그 폴백에 떨어졌다.
+`attachCredentials` 가 Studio 헬퍼에 먼저 묻는데, 그 헬퍼는 자기 것이 아닌 프로파일에 `null` 을 돌려준다. 그 아래 폴백이 세션을 읽고 인증되지 않은 것을 거절한다. 공개 읽기는 익명 프로파일을 선언하므로 그 폴백에 떨어졌다 — 「이 프로파일은 내 것이 아니다」와 「이 요청은 인증되지 않았다」가 같은 `null` 로 표현되고 있었다.

-요청이 흐르자 두 번째가 나왔다. `envelopeError()` 가 `ApiError.code` 를 Studio enum 에 고정해 세 표면이 공유했다. 공개와 관리는 각자 자기 계약에 enum 을 선언하므로 그들이 돌려준 모든 오류가 검증에 실패해 `CONTRACT_VIOLATION` 으로 도착했다.
+요청이 흐르자 두 번째가 나왔다. `envelopeError()` 가 `ApiError.code` 를 Studio enum 에 고정해 세 표면이 공유했다. 공개와 관리는 각자 자기 계약에 enum 을 선언하므로 그들이 돌려준 모든 오류가 검증에 실패해 계약 위반으로 도착했다.

 세 번째는 not-found 경로가 봉투에 없는 `status` 를 읽고 있던 것이다.

@@ -74,13 +76,25 @@ tech-log-frontend : 03986da · 7600711

 > 엄격한 enum 을 잘못된 표면의 계약에 대고 검사해도 여전히 엄격해 보인다.

-검증은 돌고 있었고 통과하고 있었다.
+검증은 돌고 있었고 통과하고 있었다. 대상이 틀렸을 뿐이다. 검증이 「값이 이 enum 에 있는가」를 묻는데 그 enum 이 다른 표면의 것이면, 물음은 성립하고 답만 늘 거짓이 된다.

 ## 스텁이 이음매를 덮지 않는다

 > 이 결함은 공개 소스가 HTTP 가 된 뒤에야 나타날 수 있었다. 이번 주까지 그 경로는 브라우저에서 한 번도 돌지 않았다. **스위트가 잡지 못한 이유는 게이트웨이와 화면을 검사할 뿐 합성 루트의 credential 결정은 검사하지 않기 때문이다 — 그 이음매에는 테스트가 없고, 이것이 그 대가다.**

-같은 모양이 HTTP 매퍼에서도 났다. 게시한 질문의 공개 상세가 「요청을 처리하지 못했습니다」만 띄웠는데, 화면 테스트가 정적 픽스처 어댑터를 쓰므로 계약 모양을 한 번도 통과시키지 않았다. 계약 모양 그대로의 응답을 진짜 게이트웨이에 넣는 테스트를 넣으니 되돌려 보면 운영에서 난 것과 같은 오류로 실패한다.
+게이트웨이 테스트는 실행기를 스텁으로 바꾸고 화면 테스트는 게이트웨이를 스텁으로 바꾼다. 둘 다 자기 층은 검사하지만 그 사이에서 credential 을 정하는 코드는 어느 쪽에도 들어가지 않는다.
+
+## 같은 모양이 HTTP 매퍼에서도 났다
+
+게시한 질문의 공개 상세가 「요청을 처리하지 못했습니다」만 띄웠다.
+
+> 이 사고가 지나간 이유는 HTTP 게이트웨이의 질문 상세 매핑을 지나는 테스트가 없었기 때문이다. **화면 테스트는 정적 픽스처 어댑터를 쓰므로 계약 모양을 한 번도 통과시키지 않는다.**
+
+계약 모양 그대로의 응답을 진짜 게이트웨이에 넣고 네 칸이 채워져 나오는지 묻는 테스트를 넣었다. 되돌려 보면 운영에서 난 것과 같은 오류로 실패한다.
+
+## 회귀 테스트가 무엇을 조립하나
+
+이 이음매의 회귀 테스트는 실제 런타임 어댑터를 배포된 백엔드의 실제 404 본문에 대고 조립한다. 스텁을 하나도 쓰지 않으므로 credential 결정과 봉투 해석이 둘 다 실제로 돈다.

 ## 확인하지 못한 것

@@ -66,26 +66,39 @@ tech-log-backend : 365560e

 ## 계약 결함처럼 보이지 않았다

-파서가 거절한 스키마 15개는 전부 `type: object` 를 명시하고 있었다. 메시지는 「is not of type `object`」였다.
+파생 스펙을 파서에 넣으면 스키마 15개를 「is not of type `object`」로 거절했다. 그 스키마들은 전부 `type: object` 를 명시하고 있어서, 메시지가 가리키는 곳을 열어 봐도 고칠 것이 없었다.

-원인은 그 스키마가 아니라 파생 스펙의 표현이었다. 변환들이 같은 `Map` 인스턴스를 여러 property 에 재사용했고, snakeyaml 은 같은 인스턴스가 두 번 나오면 두 번째를 alias 로 덤프한다. 그 지점이 34곳이었다.
+원인은 그 스키마가 아니라 파생 스펙의 표현이었다. 변환들이 같은 `Map` 인스턴스를 여러 property 에 재사용했고, snakeyaml 은 같은 인스턴스가 두 번 나오면 두 번째를 anchor 와 alias 로 덤프한다. 파서가 alias 를 만나면 그 노드의 타입을 판정할 수 없으므로 거절한다.
+
+파생 스펙에 alias 가 34곳 있었다.

 ## 검증을 끄면 생성이 성공한다

 `validateSpec` 을 끄고 생성하면 모델이 만들어진다. 다만 거절되던 스키마의 일부 필드가 빠진 채로 만들어진다.

-빠진 것은 넷이었다 — `LatestEntry.publishedAt`, `ProjectListItem.updatedAt`, `SearchResultItem.matchedFields`, `ReleaseListItem.changeTypes`.
+| 빠진 필드 | 어디 쓰는 칸인가 |
+|---|---|
+| `LatestEntry.publishedAt` | 홈 최근 기록의 게시일 |
+| `ProjectListItem.updatedAt` | 프로젝트 목록의 갱신일 |
+| `SearchResultItem.matchedFields` | 검색 결과에서 찾은 말 표시 |
+| `ReleaseListItem.changeTypes` | 릴리스 목록의 변경 종류 |

-컴파일은 통과한다. 아직 아무도 그 필드를 안 쓰기 때문이다.
+컴파일은 통과한다. 아직 그 필드를 쓰는 코드가 없기 때문이다 — 넷 다 화면이 그리기로 되어 있지만 아직 안 그리고 있던 칸이라, 모델에 없어도 아무도 부르지 않는다.

 ## 두 가지로 막았다

-덤프 직전에 deep copy 로 노드 identity 를 끊었다. 같은 인스턴스가 두 번 나오지 않으면 alias 가 생기지 않는다. 그래도 남으면 빌드가 실패하도록 fail-closed 게이트를 뒀고, `validateSpec` 은 다시 켰다.
+덤프 직전에 deep copy 로 노드 identity 를 끊었다. 같은 인스턴스가 두 번 나오지 않으면 snakeyaml 이 alias 를 만들 이유가 없다.

-생성 모델 대조도 바꿨다. schema 이름만 세던 것을 property 단위로 강화했다. 이번 누락을 이름 대조가 통과시켰기 때문이다. 지금은 schema 62개와 property 250개를 센다.
+그래도 남으면 빌드가 실패하도록 fail-closed 게이트를 뒀고, `validateSpec` 은 다시 켰다. 원인을 끊은 것과 남은 것을 잡는 것을 둘 다 둔 이유는, deep copy 를 지나지 않는 새 변환이 생기면 alias 가 다시 나올 수 있기 때문이다.
+
+## 이름 대조에서 property 대조로
+
+생성 모델 대조도 바꿨다. schema 이름만 세던 것을 property 단위로 강화했다.
+
+이름 대조는 이번 누락을 통과시켰다. 스키마 자체는 만들어졌고 그 안의 필드만 빠졌기 때문이다. 지금은 schema 62개와 property 250개를 센다.

 ## 확인하지 못한 것

-지금 세는 수는 사람이 갱신한다. 계약이 줄어드는 방향의 누락은 이 게이트가 잡지 않는다.
+지금 세는 수는 사람이 갱신한다. 계약이 줄어드는 방향의 누락은 이 게이트가 잡지 않는다 — 수를 함께 줄이면 통과한다.

 <!-- body:end -->
@@ -60,26 +60,35 @@ DB : 실제 PostgreSQL (Testcontainers)

 ## 없는 컬럼을 조회했다

-`public_resource_projection` 은 한 테이블이 case·question·project·release 를 모두 담는다. 그래서 기록을 가리킬 때 종류와 식별자 두 컬럼을 함께 쓴다. `document_id` 라는 컬럼은 없다.
+작업본을 지우려 하면 500 이 났다. 참조 검사가 공개 투영에서 문서 식별자 컬럼을 조회하는데 그런 컬럼이 없다.

-참조 검사가 그 이름을 쓰고 있었고, 실행하면 500 이 났다.
-
-## 다섯은 대조했고 하나는 가정했다
+이 테이블은 하나로 case·question·project·release 를 모두 담는다. 그래서 기록을 가리킬 때 종류와 식별자 두 컬럼을 함께 쓰고, 종류별 식별자 컬럼은 두지 않는다.

 > 그 쿼리의 여섯 컬럼 중 다섯은 마이그레이션과 대조했다. 이 하나만 가정했고, 그것이 틀렸다.

 ## 그 SQL 은 한 번도 실행되지 않았다

-표준 `check` 는 Testcontainers 를 띄우지 않으므로 persistence SQL 이 한 줄도 실행되지 않은 채 빌드가 통과한다.
+컬럼 이름보다 더 드러난 것은 검사 구조였다.

-컴파일은 SQL 문자열 안을 보지 않는다. 단위 테스트는 어댑터를 스텁으로 바꾼다. 컬럼 이름이 맞는지 묻는 검사가 어디에도 없었다.
+| 무엇이 도는가 | SQL 을 실행하는가 |
+|---|---|
+| 컴파일 | x — 문자열 안을 보지 않는다 |
+| 단위 테스트 | x — 어댑터를 스텁으로 바꾼다 |
+| 표준 check | x — Testcontainers 를 띄우지 않는다 |
+| 삭제 경로 통합 테스트 | o — 실제 PostgreSQL |
+
+표준 검사가 컨테이너를 띄우지 않으므로 어댑터의 SQL 은 한 줄도 실행되지 않은 채 빌드가 통과한다. 컬럼 이름이 맞는지 묻는 검사가 어디에도 없었다.

 ## 전용 태스크로 여덟 시나리오를 돌린다

-삭제 경로 전용 통합 테스트 태스크를 만들었다. 실패했던 그 쿼리를 포함해 여덟 시나리오를 실제 PostgreSQL 에서 돌린다.
+삭제 경로 전용 통합 테스트 태스크를 만들고, 실패했던 그 쿼리를 포함해 여덟 시나리오를 실제 PostgreSQL 에서 돌린다.
+
+전용 태스크로 뺀 이유는 컨테이너를 띄우는 데 시간이 들어 표준 검사에 넣으면 모든 빌드가 느려지기 때문이다. 대신 그 태스크를 돌리는 것은 사람이 기억해야 한다.

 ## 확인하지 못한 것

-이 태스크가 덮는 것은 삭제 경로다. 표준 `check` 는 여전히 Testcontainers 를 띄우지 않고, 새 어댑터 SQL 이 이 태스크에 등록되는지 보는 검사도 없다.
+이 태스크가 덮는 것은 삭제 경로다. 표준 검사는 여전히 컨테이너를 띄우지 않고, 새 어댑터 SQL 이 이 태스크에 등록되는지 보는 검사도 없다.
+
+같은 참조 검사가 지금도 다섯 테이블을 하나로 묶어 확인하므로, 무엇이 막았는지를 응답이 말하지 못한다.

 <!-- body:end -->
@@ -65,13 +65,17 @@ Jackson : 이 빌드는 Jackson 3, 클래스패스에 Jackson 2 타입이 전이

 새 활동 어댑터가 생성자를 둘 갖고 있었다. 하나는 운영용, 하나는 테스트가 id 생성기를 넣기 위한 것이다. 둘 중 어느 것에도 `@Autowired` 가 없어 컴포넌트 스캔이 고르지 못했다.

+스캔은 생성자가 하나면 그것을 쓰고, 여럿이면 `@Autowired` 가 붙은 것을 쓴다. 둘 다 아니면 어느 것을 쓸지 정할 수 없으므로 컨텍스트가 refresh 에 실패한다.
+
 > 컴파일도, 단위 테스트도, **실제 PostgreSQL 위에서 도는 통합 테스트 26개도 전부 통과했다. 그 어느 것도 애플리케이션 컨텍스트를 띄우지 않기 때문이다.** 운영에서 파드가 CrashLoopBackOff 로 들어갔고, 그때서야 드러났다.

+통합 테스트가 실제 데이터베이스를 쓴다는 것과 애플리케이션 컨텍스트를 띄운다는 것은 다르다. 어댑터를 직접 만들어 SQL 을 돌리는 테스트는 컨테이너가 필요하지만 스프링 컨텍스트는 필요하지 않다.
+
 ## 클래스패스에 남은 옛 타입

-두 번째 건은 import 였다. `JdbcProjectRepositoryAdapter` 가 `com.fasterxml.jackson.databind.ObjectMapper` 를 요구했다. 이 빌드는 `tools.jackson.databind` 를 쓰므로 그런 빈이 없고, 컨텍스트가 refresh 에 실패한다.
+두 번째 건은 import 였다. 어댑터가 Jackson 2 의 `ObjectMapper` 를 요구했는데 이 빌드는 Jackson 3 을 쓴다. 그런 빈이 없으므로 컨텍스트가 refresh 에 실패한다.

-컴파일이 잡지 못한 이유는 어떤 전이 의존성이 Jackson 2 타입을 클래스패스에 올려 두어 import 가 정상적으로 해석되기 때문이다. 빈이 없다는 것은 컨텍스트를 띄워야 알 수 있다.
+컴파일이 잡지 못한 이유는 어떤 전이 의존성이 Jackson 2 타입을 클래스패스에 올려 두어 import 가 정상적으로 해석되기 때문이다. 컴파일러가 보는 것은 그 타입이 클래스패스에 있는지까지이고, 그 타입의 빈이 컨텍스트에 있는지는 컨텍스트를 띄워야 알 수 있다.

 | 원인 | 왜 컴파일·테스트가 못 잡았나 | 커밋 |
 |---|---|---|
@@ -80,10 +84,14 @@ Jackson : 이 빌드는 Jackson 3, 클래스패스에 Jackson 2 타입이 전이

 ## D20 규칙으로 막은 것

-D20 규칙을 세웠다. 스캔되는 컴포넌트는 생성자가 하나이거나, 여럿이면 그중 하나에 `@Autowired` 가 붙어야 한다. 결함을 되돌려 규칙이 실제로 멈추는 것을 확인한 뒤 커밋했다.
+스캔되는 컴포넌트는 생성자가 하나이거나, 여럿이면 그중 하나에 `@Autowired` 가 붙어야 한다는 아키텍처 규칙을 세웠다.
+
+이 규칙은 컨텍스트를 띄우지 않고도 돈다. 바이트코드를 훑어 스캔 대상 애노테이션이 붙은 클래스의 생성자를 세면 되므로 빌드 시간이 늘지 않는다. 결함을 되돌려 규칙이 실제로 멈추는 것을 확인한 뒤 커밋했다.

 ## D20 이 보지 않는 것

-D20 은 생성자 쪽만 본다. 클래스패스에 남은 옛 라이브러리 타입을 import 하는 것은 이 규칙이 잡지 않는다. 그 경로를 막는 검사는 아직 없고, 컨테이너가 뜰 때 알게 된다.
+이 규칙은 생성자 개수만 센다. 클래스패스에 남은 옛 라이브러리 타입을 import 하는 것은 대상이 아니다.
+
+그 경로를 막으려면 컨텍스트를 실제로 띄우는 검사가 필요하고, 그것은 아직 없다. 지금은 컨테이너가 뜰 때 알게 된다.

 <!-- body:end -->
@@ -29,38 +29,47 @@ source:

 ## 목적

-층을 스텁으로 나눠 시험하는 구조에서 그 나눈 자국이 검사되지 않고 남는 것을 막는다. 이 부류는 모든 검사가 초록불인 상태로 배포된다.
+층을 스텁으로 나눠 시험하는 구조에서 그 나눈 자국이 검사되지 않고 남는 것을 막는다.
+
+이 부류는 모든 검사가 초록불인 상태로 배포된다. 각 층의 검사는 자기 층을 정확히 보고 통과하며, 통과하지 않은 것은 층과 층 사이다.

 ## 규칙

 **스프링 컨텍스트를 띄우는 검사를 하나 둔다**
-컴파일도 단위 테스트도 실제 DB 위의 통합 테스트도 컨텍스트를 띄우지 않을 수 있다. 스캔되는 컴포넌트의 생성자 규칙은 아키텍처 검사로 대신할 수 있다.
+컴파일도 단위 테스트도, 실제 데이터베이스를 쓰는 통합 테스트도 컨텍스트를 띄우지 않을 수 있다. 컨테이너가 필요해서 통합 테스트인 것과 컨텍스트를 띄우는 것은 다르다. 스캔되는 컴포넌트의 생성자 규칙처럼 정적으로 셀 수 있는 것은 아키텍처 검사로 대신할 수 있고, 그 편이 빌드 시간을 늘리지 않는다.

-**persistence SQL 을 실제 DB 에서 돌리는 태스크를 둔다**
-표준 `check` 가 컨테이너를 띄우지 않으면 어댑터의 SQL 은 한 줄도 실행되지 않는다. 컬럼 이름은 실행해야만 검증된다.
+**persistence SQL 을 실제 데이터베이스에서 돌리는 태스크를 둔다**
+표준 검사가 컨테이너를 띄우지 않으면 어댑터의 SQL 은 한 줄도 실행되지 않는다. 컴파일은 문자열 안을 보지 않고 단위 테스트는 어댑터를 스텁으로 바꾸므로, 컬럼 이름은 실행해야만 검증된다.

 **계약 모양 그대로의 응답을 진짜 게이트웨이에 넣는 검사를 둔다**
-화면 테스트는 정적 픽스처 어댑터를 쓰므로 계약 모양을 한 번도 통과시키지 않는다.
+화면 테스트는 정적 픽스처 어댑터를 쓰므로 계약 모양을 한 번도 통과시키지 않는다. 픽스처를 게이트웨이가 읽는 모양으로 만들면 그 테스트는 늘 통과한다.

 **실제 런타임 어댑터를 실제 응답 본문에 대고 조립하는 검사를 둔다**
-게이트웨이 테스트는 실행기를 스텁으로 바꾸고 화면 테스트는 게이트웨이를 스텁으로 바꾼다. 합성 루트의 credential 결정은 둘 다 덮지 않는다.
+게이트웨이 테스트는 실행기를 스텁으로 바꾸고 화면 테스트는 게이트웨이를 스텁으로 바꾼다. 합성 루트에서 credential 을 정하는 코드는 둘 다 덮지 않는다.

 **생성기는 모델이 만들어졌는지가 아니라 property 가 계약과 같은지로 본다**
 모델은 필드가 빠져도 만들어진다. 아직 그 필드를 쓰는 코드가 없으면 컴파일도 통과한다.

+**전용 태스크로 뺐으면 그것을 돌리는 것이 사람 몫이라는 것도 적는다**
+컨테이너를 띄우는 검사를 표준 검사에 넣으면 모든 빌드가 느려진다. 빼는 것은 되지만, 뺀 뒤에 그 태스크가 돌지 않으면 검사가 없는 것과 같다.
+
 ## 적용 조건

 스텁으로 층을 나눠 시험하는 구조. 계약이 다른 저장소에 있고 생성기를 지나 들어오거나, 컨테이너가 필요한 검사를 별도 태스크로 뺀 저장소에서 걸린다.

+「모든 검사가 통과했는데 운영에서 깨졌다」가 나오면 무엇이 깨졌는지보다 어느 이음매를 아무 검사도 지나지 않았는지를 먼저 센다.
+
 ## 예외

 그 층을 실제로 지나는 검사가 이미 있으면 더 두지 않는다.

-스텁을 쓰는 테스트를 늘리는 것은 이 문제를 덮지 않는다.
+스텁을 쓰는 테스트를 늘리는 것은 이 문제를 덮지 않는다. 스텁의 개수가 아니라 어느 층을 대신했는지가 기준이다.
+
+정적으로 셀 수 있는 규칙은 컨텍스트를 띄우지 않고도 걸린다. 그때는 무거운 검사를 새로 두지 않는다.

 ## 예시

-컨텍스트를 띄우지 않아 파드가 CrashLoopBackOff 로 들어간 것을 아키텍처 규칙으로 막았다.
+컨텍스트를 띄우지 않아 파드가 두 번 CrashLoopBackOff 로 들어갔다. 실제 PostgreSQL 위에서 도는 통합 테스트 26개도 통과한 상태였다.

 삭제 경로의 SQL 이 한 번도 실행된 적이 없어서 전용 통합 테스트 태스크를 만들었다.