diff --git a/docs/TechLog/tech-log-studio/addresses-frozen-at-publish-time/decision/decision-a-new-route-ships-frontend-first.md b/docs/TechLog/tech-log-studio/addresses-frozen-at-publish-time/decision/decision-a-new-route-ships-frontend-first.md index bfac4e6..5a56264 100644 --- a/docs/TechLog/tech-log-studio/addresses-frozen-at-publish-time/decision/decision-a-new-route-ships-frontend-first.md +++ b/docs/TechLog/tech-log-studio/addresses-frozen-at-publish-time/decision/decision-a-new-route-ships-frontend-first.md @@ -17,7 +17,7 @@ source: 새 라우트를 여는 변경은 프론트엔드를 먼저 배포한다. nginx 설정이 라우트 계약에서 생성되므로, 프론트가 배포되기 전까지 그 경로는 엣지에서 404 다. 백엔드를 먼저 배포하면 서버는 이미 그 주소를 내보내고 사용자는 전부 404 인 화면을 본다. -## 근거 +## 백엔드를 먼저 배포하면 아직 없는 프론트 라우트를 응답할 수 있다 - **축 링크가 자기 자신을 가리켰고, 고친 뒤에는 백엔드를 먼저 배포했다** 이 순서를 정하게 된 사건이다. 반대 순서로 배포해 사용자가 네 링크 전부 404 인 화면을 봤다. @@ -26,11 +26,11 @@ source: - **catch-all 라우트는 nginx 패턴으로 번역하지 않는다** 이 순서가 필요해진 이유가 그 결정에 있다. -## 결정문 +## 새 공개 라우트는 프론트엔드를 먼저 배포한다 새 공개 라우트를 여는 변경은 프론트엔드를 먼저 배포하고, 그 주소를 내보내는 백엔드 변경을 다음 배포에 넣는다. -## 판단 이유 +## 라우트가 실제로 서빙된 뒤 서버가 그 주소를 내보내게 한다 nginx 설정은 라우트 계약에서 생성된다. 프론트 이미지가 배포되기 전까지 그 경로는 서빙 패턴에 없고, 엣지에서 404 로 끝난다. @@ -38,7 +38,7 @@ nginx 설정은 라우트 계약에서 생성된다. 프론트 이미지가 배 catch-all 을 서빙 패턴으로 번역하지 않기로 했으므로 이 구간이 soft 200 으로 덮이지 않는다. -## 영향 +## 배포 순서 검증이 라우트 계약의 일부가 된다 새 주소를 내보내는 백엔드 변경이 한 배포 늦게 나간다. 두 저장소를 한 번에 배포하고 싶은 변경에서 그 사이가 벌어진다. diff --git a/docs/TechLog/tech-log-studio/addresses-frozen-at-publish-time/reference/reference-do-not-draw-a-link-that-does-not-resolve.md b/docs/TechLog/tech-log-studio/addresses-frozen-at-publish-time/reference/reference-do-not-draw-a-link-that-does-not-resolve.md index 4d39259..1c0d53c 100644 --- a/docs/TechLog/tech-log-studio/addresses-frozen-at-publish-time/reference/reference-do-not-draw-a-link-that-does-not-resolve.md +++ b/docs/TechLog/tech-log-studio/addresses-frozen-at-publish-time/reference/reference-do-not-draw-a-link-that-does-not-resolve.md @@ -16,7 +16,7 @@ source: 주소를 서버가 만들어 내보내고 화면이 그대로 링크로 그리면, 그 주소가 틀렸다는 것은 방문자만 안다. 화면 코드 어디에도 그 주소가 없기 때문이다. 만드는 쪽과 그리는 쪽 양쪽에서 라우트 표와 맞춘다. -## 관계 +## 서버가 내려준 주소와 실제 공개 라우트는 함께 검증한다 - **계약은 앵커라고 적었고 만드는 쪽은 경로를 만들었다** 이 기준의 근거 사건이다. @@ -25,11 +25,11 @@ source: - **라우트에 딸린 목록은 라우트 계약에서 유도하고, 유도할 수 없는 것은 대조 검사를 둔다** 라우트 표가 어디서 오는지가 그 기준에 있다. -## 목적 +## 존재하지 않는 주소를 링크로 그리지 않는다 서버가 만든 주소가 열리지 않는 것을 방문자보다 먼저 잡는다. 이 부류는 화면 코드에 흔적이 없어 저장소 안의 링크 리터럴을 훑는 감사로는 잡히지 않는다. -## 규칙 +## 렌더링 전에 route contract와 주소를 대조한다 ### 1. 만드는 쪽에서 생성한 경로를 공개 라우트 패턴에 맞춘다 @@ -47,20 +47,20 @@ source: 저장소를 훑는 감사와 다른 것을 본다. 실제로 나가는 주소는 DB 에 있다. -## 적용 조건 +## 서버가 링크 대상 URL이나 path를 직접 내려줄 때 - 주소를 서버가 만들어 내보내고 화면은 받은 문자열을 링크로 그릴 때 - 게시 시점에 주소가 굳어져 저장되는 구조일 때. 코드만 고치면 이미 저장된 행이 깨진 채 남는다 - 공개 라우트를 더하거나 지워 주소의 모양이 바뀔 때 - 배포 뒤 서버가 내보내는 주소를 전수로 훑을 때 -## 예외 +## 현재 화면의 anchor처럼 별도 상세 route가 없는 경우 - 외부 주소는 라우트 표에 없으므로 이 대조의 대상이 아니다. - 그리는 쪽에만 가드를 두면 링크가 아예 그려지지 않는 것으로 끝나고 원인이 남는다. 만드는 쪽에도 같은 검사를 둔다. -## 예시 +## 결정 목록과 축 링크의 공개 주소 - 결정 링크가 404 였다. 계약은 앵커라고 적었고 만드는 두 곳이 경로를 만들었다. diff --git a/docs/TechLog/tech-log-studio/addresses-frozen-at-publish-time/reference/reference-write-down-what-would-undo-a-workaround.md b/docs/TechLog/tech-log-studio/addresses-frozen-at-publish-time/reference/reference-write-down-what-would-undo-a-workaround.md index a7c549a..70f4fbe 100644 --- a/docs/TechLog/tech-log-studio/addresses-frozen-at-publish-time/reference/reference-write-down-what-would-undo-a-workaround.md +++ b/docs/TechLog/tech-log-studio/addresses-frozen-at-publish-time/reference/reference-write-down-what-would-undo-a-workaround.md @@ -16,7 +16,7 @@ source: 그 화면이 줄 수 있는 것이 아직 비어 있어 링크를 다른 곳으로 돌린 적이 있다. 우회 자체는 틀리지 않았다 — 그때는 채울 내용이 없었다. 되돌릴 조건은 우회를 넣는 커밋에 적고, 그 조건이 충족되면 되돌린다. -## 관계 +## 임시 우회는 나중에 제거할 조건까지 함께 남겨야 한다 - **축 링크가 자기 자신을 가리켰고, 고친 뒤에는 백엔드를 먼저 배포했다** 같은 주제 링크를 다루며 이 기준이 나왔다. @@ -25,11 +25,11 @@ source: - **새 라우트는 프론트엔드를 먼저 배포한다** 같은 사건에서 나온 짝이 되는 결정이다. -## 목적 +## 우회가 영구 설계로 굳는 것을 막는다 임시 조치가 영구 구조로 굳는 것을 막는다. 되돌릴 조건이 적혀 있지 않으면 다음 사람이 그 우회를 설계로 읽는다. -## 규칙 +## 우회 이유와 제거 조건을 같은 기록에 적는다 ### 1. 우회를 넣는 커밋에 되돌릴 조건을 적는다 @@ -43,19 +43,19 @@ source: 그때는 조건이 아니라 근거와 감수한 비용을 적는다. -## 적용 조건 +## 현재 구조 때문에 임시 분기나 예외 처리를 넣을 때 - 그 화면이 줄 수 있는 것이 아직 비어 있어 링크나 흐름을 다른 곳으로 돌릴 때 - 임시라고 말하면서 코드에 남기는 변경을 커밋할 때 - 왜 이 링크가 저기로 가는지 다음 사람이 물을 만한 변경을 넣을 때 -## 예외 +## 장기 정책으로 확정된 동작은 우회로 기록하지 않는다 - 되돌릴 생각이 없는 영구 변경은 우회가 아니다. 조건 대신 근거를 적는다. - 조건을 적을 수 없으면 그것은 우회가 아니라 아직 정하지 않은 것이다. 열린 질문으로 남긴다. -## 예시 +## fallback과 임시 호환 처리 - 주제 화면이 주제 셋을 하드코딩해 두고 있어 실제 주제는 무엇이든 404 였다. 그때 주제 페이지를 채우는 대신 링크를 탐색 필터로 돌렸다. diff --git a/docs/TechLog/tech-log-studio/an-axis-inside-a-topic/concept/concept-topic-variant-and-record-variant.md b/docs/TechLog/tech-log-studio/an-axis-inside-a-topic/concept/concept-topic-variant-and-record-variant.md index 0fd47c5..f86c39a 100644 --- a/docs/TechLog/tech-log-studio/an-axis-inside-a-topic/concept/concept-topic-variant-and-record-variant.md +++ b/docs/TechLog/tech-log-studio/an-axis-inside-a-topic/concept/concept-topic-variant-and-record-variant.md @@ -22,7 +22,7 @@ source: 주제 안의 축은 세 테이블로 표현된다. 주제가 축의 이름을 스스로 정하고, 축의 값들이 따로 있고, 어느 기록이 어느 축에 걸리는지를 종류와 아이디의 쌍으로 적는다. 기록이 종류마다 다른 테이블에 살기 때문에 그 쌍에 외래키를 걸지 못한다. -## 관계 +## Topic Variant와 Record Variant는 서로 다른 분류 축이다 - **주제를 넷으로 쪼개지 않고 주제 안에 축을 하나 뒀다** 이 구조를 만든 결정이다. @@ -31,7 +31,7 @@ source: - **홈의 비교 구역이 세 번 바뀌었다** 이 구조가 화면에서 어떻게 쓰이는지가 그 기록에 있다. -## 본문 +## 주제가 축 이름을 정하고 기록은 kind와 id로 연결된다 @@ -73,7 +73,7 @@ topic (주제) 주제를 지울 때와 반대다. 주제는 그것을 쓰는 기록이 있으면 아예 거절한다. -> 주제를 지웠다는 이유로 그 주제를 쓰던 문서의 분류가 조용히 사라지면 안 되기 때문이다 — 지우려면 먼저 그 문서들을 옮기라는 뜻이다. +> 주제를 지웠다는 이유로 그 주제를 쓰던 문서의 분류가 자동으로 사라지면 안 되기 때문이다 — 지우려면 먼저 그 문서들을 옮기라는 뜻이다. 주제는 그 기록이 무엇에 관한 것인지를 말하는 분류이고, 축은 같은 주제 안에서 무엇과 견주는지를 말하는 비교 축이다. 분류가 사라지면 기록의 뜻이 바뀌고, 비교 축이 사라지면 비교만 없어진다. diff --git a/docs/TechLog/tech-log-studio/an-axis-inside-a-topic/decision/decision-an-axis-inside-a-topic-not-four-topics.md b/docs/TechLog/tech-log-studio/an-axis-inside-a-topic/decision/decision-an-axis-inside-a-topic-not-four-topics.md index eff2f0e..41523bf 100644 --- a/docs/TechLog/tech-log-studio/an-axis-inside-a-topic/decision/decision-an-axis-inside-a-topic-not-four-topics.md +++ b/docs/TechLog/tech-log-studio/an-axis-inside-a-topic/decision/decision-an-axis-inside-a-topic-not-four-topics.md @@ -21,7 +21,7 @@ source: 「브라우저와 서버 사이 credential 책임을 어디에 둘 것인가」 하나의 질문에 네 구조를 만들어 봤는데, 기록에 붙는 축이 주제와 프로젝트뿐이라 그 넷을 담을 데가 없었다. 주제를 넷으로 쪼개는 대신 주제 안에 축을 하나 뒀다. -## 근거 +## 네 패턴은 하나의 인증 주제를 비교하는 축이다 - **축은 주제가 이름을 정하고, 기록은 종류와 아이디의 쌍으로 축에 걸린다** 이 결정을 담은 스키마다. @@ -30,13 +30,13 @@ source: - **축의 결론 문장과 기록 수는 기록을 붙여도 따라오지 않는다** 이 결정으로 감수한 비용이 그 질문에 있다. -## 결정문 +## 패턴마다 주제를 만들지 않고 한 주제 안에 축을 둔다 한 질문에 여러 구조를 만들어 비교하는 경우, 주제를 그 수만큼 쪼개지 않고 주제 안에 축을 하나 둔다. 축의 이름은 주제가 정하고, 기록은 여러 축에 걸릴 수 있으며, 아무 축에도 걸리지 않은 기록은 그 주제의 공통 기록으로 읽는다. -## 판단 이유 +## 비교 대상과 프로젝트 맥락을 같은 화면에서 유지한다 주제를 넷으로 쪼개면 네 구조가 함께 쓰는 기록을 어디에 둘지 애매해진다. PKCE(Proof Key for Code Exchange)와 CSRF(Cross-Site Request Forgery) 방어, Authorization Code 흐름이 그런 기록이다. 어느 한 주제에 넣으면 나머지 셋에서 그 기록에 닿을 수 없고, 넷에 복사하면 같은 글이 넷이 된다. @@ -46,7 +46,7 @@ source: 축 이름을 주제가 정하게 한 것은 주제마다 비교하는 것이 다르기 때문이다. 인증 경계 주제는 credential 을 어디에 두느냐로 갈리고 조회 성능 주제는 같은 데이터를 어떻게 읽느냐로 갈린다. -## 영향 +## 축 링크와 기록 연결 규칙을 별도로 관리해야 한다 축의 이름·요약·결론이 기록에서 자동으로 나오지 않는다. 주제의 논지와 축의 요약·결론은 사람이 쓰는 칸이고, 기록을 스무 개 붙여도 그 문장은 누가 고치기 전까지 그대로다. diff --git a/docs/TechLog/tech-log-studio/an-axis-inside-a-topic/question/openquestion-the-conclusion-line-does-not-follow-the-records.md b/docs/TechLog/tech-log-studio/an-axis-inside-a-topic/question/openquestion-the-conclusion-line-does-not-follow-the-records.md index 2dd9f20..29f167f 100644 --- a/docs/TechLog/tech-log-studio/an-axis-inside-a-topic/question/openquestion-the-conclusion-line-does-not-follow-the-records.md +++ b/docs/TechLog/tech-log-studio/an-axis-inside-a-topic/question/openquestion-the-conclusion-line-does-not-follow-the-records.md @@ -19,7 +19,7 @@ source: 홈의 비교 구역에서 줄은 문서가 아니라 축이다. 기록을 스무 개 붙여도 줄 수는 늘지 않고, 줄에 보이는 결론 문장은 축에 손으로 쓴 글이라 누가 고치기 전까지 바뀌지 않는다. 주제 화면에는 축마다 기록 수가 붙는데 홈에는 없다. -## 관계 +## 축의 결론 문장과 기록 수는 서로 다른 값으로 저장된다 - **주제를 넷으로 쪼개지 않고 주제 안에 축을 하나 뒀다** 이 결정으로 감수한 비용이 이 질문이다. @@ -28,7 +28,7 @@ source: - **프록시 지표가 아니라 보이는 것을 측정한다** 화면에서 무엇이 달라지는지 확인하는 방법이 그 기준에 있다. -## 사실 +## 기록을 추가해도 결론 문장과 개수는 자동으로 갱신되지 않는다 홈의 비교 구역에서 한 줄은 축 하나다. 기록을 스무 개 붙여도 줄 수는 그대로다. @@ -42,13 +42,13 @@ source: 주제의 논지와 축의 결론은 2026-09-01 에 AI 가 써서 DB 에 직접 넣은 초안이다. 사용자 검토 대상이고 아직 검토되지 않았다. -## 가정 +## 일부 값은 실제 기록에서 파생할 수 있다 결론을 사람이 쓰게 한 것이 의도라고 보고 있다. 요약은 「무엇인가」이고 결론은 「무엇을 알게 됐나」라서 기록의 요약 첫 줄을 잘라 쓰면 안 된다고 판단했는데, 그 판단이 지금도 맞는지 다시 보지 않았다. 기록 수는 유도할 수 있다고 보고 있다. 주제 화면이 이미 그 수를 그리므로 같은 값을 홈에 붙이면 된다고 짐작하지만, 홈의 목록 호출이 그 수를 싣는지 확인하지 않았다. -## 미지수 +## 작성자 문장과 파생 값의 경계를 어디에 둘 것인가 홈에 기록 수를 붙이면 축에 기록을 더했을 때 화면이 달라지는가. 달라진다면 결론 문장이 낡았다는 것도 같은 화면에서 드러나는가. @@ -56,13 +56,13 @@ source: DB 에 직접 넣은 초안을 누가 언제 검토하는가. 검토 전까지 그 문장을 공개 화면에 그대로 둘지. -## 제약 +## 수동 입력과 자동 집계를 함께 두면 불일치가 생긴다 축의 요약과 결론은 기록을 합쳐 자동으로 만들지 않는다. 결론은 비교표가 읽는 칸이라 기록의 요약 첫 줄을 잘라 쓰면 안 된다. 홈이 처음 보내는 요청은 목록 하나와 주제 하나로 고정한다. 기록 수를 붙이려고 주제마다 상세를 미리 받지 않는다. -## 선택지 +## 결론을 직접 쓰게 둘지 일부를 파생할지 **홈 비교표에 기록 수를 붙인다** 목록 호출이 이미 그 수를 실을 수 있으면 요청이 늘지 않는다. 결론 문장은 그대로 사람이 쓴다. 기록이 늘면 수가 바뀌므로 결론만 낡은 상태가 화면에 드러난다. @@ -73,7 +73,7 @@ DB 에 직접 넣은 초안을 누가 언제 검토하는가. 검토 전까지 **결론을 쓰지 않은 축은 결론 줄을 비운다** 쓰지 않은 것과 낡은 것을 구분한다. 지금은 초안이 들어 있어 둘이 같아 보인다. -## 다음 검증 +## 기록 추가와 삭제 뒤 축 화면을 다시 확인한다 1. 홈의 목록 호출 응답에 축별 기록 수가 실려 있는지 확인하고, 없으면 싣는 비용을 잰다 2. 축 하나에 기록을 더하고 홈에서 무엇이 달라지고 무엇이 그대로인지 화면으로 가른다 diff --git a/docs/TechLog/tech-log-studio/css-rules-that-leak/reference/reference-measure-what-is-visible-not-a-proxy.md b/docs/TechLog/tech-log-studio/css-rules-that-leak/reference/reference-measure-what-is-visible-not-a-proxy.md index 02d86ec..bc88a21 100644 --- a/docs/TechLog/tech-log-studio/css-rules-that-leak/reference/reference-measure-what-is-visible-not-a-proxy.md +++ b/docs/TechLog/tech-log-studio/css-rules-that-leak/reference/reference-measure-what-is-visible-not-a-proxy.md @@ -19,7 +19,7 @@ source: 격자와 열을 재고 「정상」이라고 답했는데, 전체 페이지 스크린샷을 찍으니 제목이 26px 에 굵기 400 이었다. 목록 간격을 바운딩 박스로만 재서 엉뚱한 곳을 결함으로 지목한 적도 있다. 화면이 잘못됐다는 보고는 보이는 것을 재서 확인한다. -## 관계 +## 간접 지표와 사용자가 보는 결과는 다를 수 있다 - **규칙이 없었던 게 아니라 절반만 있었다** 이 기준의 근거 사건이다. @@ -28,11 +28,11 @@ source: - **홈의 비교 구역이 세 번 바뀌었다** 폭마다 측정을 남긴 기록이다. -## 목적 +## 프록시 지표만 보고 화면 동작을 판단하지 않는다 화면이 잘못됐다는 보고를 확인할 때 엉뚱한 값을 재고 「정상」이라 답하는 것을 막는다. -## 규칙 +## 최종 사용자 결과와 가장 가까운 지점을 직접 측정한다 ### 1. 보고된 증상과 같은 축의 값을 잰다 @@ -52,19 +52,19 @@ source: 축소되어 글자 크기가 실제와 달라진다. 1425x4466 이 638x2000 으로 들어오면 17px 글자가 7~8px 이 되고, 그 그림에서는 크기 문제를 볼 수 없다. 화면 높이만큼 잘라 찍는다. -## 적용 조건 +## 중간 계층의 성공 여부로 UI나 API 결과를 추정할 때 - 화면이 잘못됐다는 보고를 확인할 때 - 배포본의 실제 렌더 결과를 판단 근거로 삼을 때 - 고쳤다고 답하기 전에 무엇을 쟀는지 대야 할 때 - 여러 폭에서 배치가 갈리는 사이트를 검토할 때 -## 예외 +## 프록시 지표 자체가 검증 대상인 경우 - 측정 대상이 좌표나 간격 자체라면 바운딩 박스는 프록시가 아니라 대상이다. - CSS 선언이 정본과 같은지를 보는 검사는 렌더 결과를 재지 않는다. 그 검사가 덮는 범위를 알고 쓰면 된다. -## 예시 +## healthy container와 실제 SPA 403 비교 - 격자와 열만 재고 「정상」이라 답했다. 사용자가 다시 지적한 뒤 전체 페이지 스크린샷을 찍어서야 26px 과 400 을 봤다 - 목록 간격을 바운딩 박스로만 재서 엉뚱한 구역을 결함으로 지목한 적이 있다 diff --git a/docs/TechLog/tech-log-studio/css-rules-that-leak/reference/reference-scope-a-layout-rule-to-what-uses-it.md b/docs/TechLog/tech-log-studio/css-rules-that-leak/reference/reference-scope-a-layout-rule-to-what-uses-it.md index 13b84c8..ab895f6 100644 --- a/docs/TechLog/tech-log-studio/css-rules-that-leak/reference/reference-scope-a-layout-rule-to-what-uses-it.md +++ b/docs/TechLog/tech-log-studio/css-rules-that-leak/reference/reference-scope-a-layout-rule-to-what-uses-it.md @@ -16,7 +16,7 @@ source: 구역 클래스 아래에 태그 선택자로 배치를 걸면 그 구역 안의 모든 같은 태그가 걸린다. 제목 안의 링크가 행용 격자에 갇혀 h2 높이가 199px 이 됐다. 배치를 거는 규칙은 그 배치를 쓰는 요소까지 좁혀 적는다. -## 관계 +## CSS layout rule은 적용 범위를 넓히면 의도하지 않은 요소까지 잡는다 - **구역 전체에 건 격자가 제목까지 잡아 h2 높이가 199px 이 됐다** 이 기준의 근거 사건이다. @@ -25,13 +25,13 @@ source: - **규칙이 없었던 게 아니라 절반만 있었다** 같은 화면에서 난 다른 부류의 CSS 결함이다. -## 목적 +## 배치 규칙을 실제 배치를 쓰는 요소에만 적용한다 「디자인이 안 된 것처럼 보인다」는 보고의 원인이 되는 선택자 누출을 막는다. 이 부류는 규칙 자체는 맞고 걸리는 대상이 넓다. 그래서 규칙을 읽어서는 틀린 것을 찾을 수 없고, 그려진 결과를 봐야 한다. -## 규칙 +## selector 범위를 layout container까지 좁힌다 ### 1. 배치 속성은 그 배치를 쓰는 요소까지 좁혀 적는다 @@ -51,19 +51,19 @@ display: grid|flex·grid-template-columns·padding 을 구역 클래스 아래 module 은 클래스 이름을 빌드 때 바꿔 전역 선택자와 겹치지 않게 만든다. 그래서 전역 규칙을 고쳐도 module 을 쓰는 화면에는 닿지 않고, 한 화면 안에서 두 언어가 섞이면 더 눈에 띈다. -## 적용 조건 +## grid와 flex 규칙을 section 단위로 추가할 때 - 구역 클래스 아래에 태그 선택자로 배치를 거는 CSS 를 쓸 때 - 같은 구역 안에 제목과 목록이 함께 있을 때 - 전역 규칙과 CSS module 이 한 화면에 섞여 있을 때 - 「디자인이 안 된 것처럼 보인다」는 보고를 받았을 때 -## 예외 +## 전체 section이 동일한 layout을 공유하는 경우 - 색이나 글꼴만 거는 규칙은 새어도 티가 나지 않으므로 대상이 아니다. 검사에 넣으면 결과가 늘 빨갛다. - 구역 안의 모든 같은 태그가 실제로 같은 배치를 써야 하는 화면이라면 좁히지 않아도 된다. 그때는 그 의도를 검사의 예외 목록에 적는다. -## 예시 +## home comparison h2가 grid item이 된 문제 - 비교 행을 위한 격자가 제목 안의 링크까지 잡아 제목이 200px 칸에 갇히고 h2 높이가 199px 이 됐다 - 같은 모양이 다른 구역 아홉 곳에도 있어 선택자 51개를 고쳤다 diff --git a/docs/TechLog/tech-log-studio/declared-but-not-implemented/reference/reference-compare-the-contract-with-both-implementations.md b/docs/TechLog/tech-log-studio/declared-but-not-implemented/reference/reference-compare-the-contract-with-both-implementations.md index 635f639..c7182fa 100644 --- a/docs/TechLog/tech-log-studio/declared-but-not-implemented/reference/reference-compare-the-contract-with-both-implementations.md +++ b/docs/TechLog/tech-log-studio/declared-but-not-implemented/reference/reference-compare-the-contract-with-both-implementations.md @@ -17,7 +17,7 @@ source: 계약이 한 저장소에 있고 두 저장소가 그것을 반입해 각자 구현하면, 어느 한쪽이 빠뜨린 것을 컴파일러가 보지 못한다. 이 저장소에서 그 구멍이 서버 쪽으로 다섯 번, 화면 쪽으로 네 번 났다. 두 쪽 모두에서 계약과 대조하는 검사를 돌린다. -## 관계 +## 계약 하나를 서버와 화면이 서로 다르게 구현할 수 있다 - **계약에 선언만 있고 구현이 없어 화면 다섯 곳이 비어 있었다** 서버 쪽 누락의 근거 사건이다. @@ -26,13 +26,13 @@ source: - **종류를 나열하는 곳은 컴파일러나 계약 대조 검사가 세게 만든다** 컴파일러가 볼 수 있는 범위 안쪽을 다루는 짝이 되는 기준이다. -## 목적 +## 타입 생성 성공만으로 계약 구현을 완료로 보지 않는다 계약이 선언한 연산에 구현이 없는 상태를 배포 전에 잡는다. 이 상태는 오류를 내지 않는다. 서버는 404 를 주고 화면은 그것을 빈 데이터로 그린다. 계약에서 모델을 생성하는 단계도 스키마와 속성만 보므로 구현이 없어도 모델이 만들어지고 컴파일이 통과한다. -## 규칙 +## contract operation과 backend handler, frontend call을 전수 대조한다 ### 1. 서버 쪽은 매핑을 리플렉션으로 모아 계약의 경로와 전수 대조한다 @@ -58,13 +58,13 @@ source: 관리 계약에는 86 operation 이 있다. 검사 범위를 좁힌 이유는 그 숫자 자체가 아니라 당시 반복해서 깨진 형태가 「한 종류만 빠진 항목」이었기 때문이다. 그래서 관리 계약 쪽 가드는 그 패턴을 보며, 전체 계약과 구현의 동등성을 증명한다고 말하지 않는다. -## 적용 조건 +## operation이나 field를 계약에 추가하거나 이름을 바꿀 때 이 대조가 필요한 때는 계약이 한 저장소에 있고 두 저장소가 그것을 반입해 각자 구현하는 구조에서 연산을 더하거나 지울 때다. 화면이 「데이터가 없습니다」를 그리는데 저장소에는 값이 있을 때도 먼저 본다. 구현이 없어서 404가 난 경우와 정말 0건인 경우가 화면에서는 같은 빈 상태로 보이기 때문이다. 실제 검증에서는 매핑 하나를 떼었을 때 대조 검사가 그 연산 하나를 정확히 짚는 것을 확인한 뒤 커밋했다. 두 목록 조회에 컨트롤러가 없던 때에는 홈 편집기가 「이 프로젝트에 열린 질문이 없습니다」를 그렸지만 실제로는 넷이 있었고 공개 사이트에도 나오고 있었다. 화면 쪽에서는 기여 목록에 등록하지 않은 연산 넷을 만났고, 둘은 옆 분기로 떨어져 다른 기록을 다뤘으며 둘은 빈 목록이 됐다. -## 예외 +## 자동 생성으로 양쪽 구현까지 함께 만들어지는 항목 계약과 구현이 같은 저장소에 있어도 컴파일러가 대신할 수 있는 범위는 실제로 같은 타입이나 생성 산출물에 연결된 곳뿐이다. 문자열 라우트나 별도 컨트롤러 등록처럼 타입 시스템 밖에 있는 항목은 별도 대조가 필요하다. 봉투 규약을 따르지 않는 연산을 경로 대조에서 빼야 한다면, 제외 이유는 명시 목록에 남긴다. diff --git a/docs/TechLog/tech-log-studio/failure-drawn-as-absence/case/case-it-said-there-were-no-open-questions.md b/docs/TechLog/tech-log-studio/failure-drawn-as-absence/case/case-it-said-there-were-no-open-questions.md index 3044de9..c7118df 100644 --- a/docs/TechLog/tech-log-studio/failure-drawn-as-absence/case/case-it-said-there-were-no-open-questions.md +++ b/docs/TechLog/tech-log-studio/failure-drawn-as-absence/case/case-it-said-there-were-no-open-questions.md @@ -77,7 +77,7 @@ tech-log-backend : 911e8ba — 없던 두 컨트롤러를 구현 홈이 무엇을 앞에 세울지 정하는 설정은 지목한 대상에 외래키를 걸지 않는다. 설정이 대상보다 오래 살아남는 것을 허용하는 설계다. -대신 저장할 때 그 대상이 실제로 있는지 확인한다. 확인하지 않으면 없는 id 가 그대로 저장되고, 공개 화면은 조용히 빈 focus 를 그린다 — 저장은 성공했는데 화면에는 아무것도 안 나오는, 이유를 알 수 없는 실패가 된다. +대신 저장할 때 그 대상이 실제로 있는지 확인한다. 확인하지 않으면 없는 id 가 그대로 저장되고, 공개 화면은 빈 focus를 그린다 — 저장은 성공했는데 화면에는 아무것도 안 나오는, 이유를 알 수 없는 실패가 된다. 확인하는 것은 있는지까지다. 그 대상이 공개인지는 저장할 때 보지 않는다. 아직 게시하지 않은 프로젝트를 미리 지목해 두고 게시와 동시에 홈에 뜨게 하는 것이 정상적인 순서이고, 공개 여부는 공개 조회 쪽이 매번 다시 판단한다. diff --git a/docs/TechLog/tech-log-studio/failure-drawn-as-absence/case/case-records-disappeared-without-a-trace.md b/docs/TechLog/tech-log-studio/failure-drawn-as-absence/case/case-records-disappeared-without-a-trace.md index f9618ab..6e010f3 100644 --- a/docs/TechLog/tech-log-studio/failure-drawn-as-absence/case/case-records-disappeared-without-a-trace.md +++ b/docs/TechLog/tech-log-studio/failure-drawn-as-absence/case/case-records-disappeared-without-a-trace.md @@ -1,7 +1,7 @@ --- kind: CASE slug: records-disappeared-without-a-trace -title: 매퍼가 null 을 돌려주고 호출부가 걸러 내, 기록이 조용히 사라졌다 +title: 매퍼가 null을 반환해 QUESTION과 CONCEPT가 목록에서 누락됐다 topic: failure-drawn-as-absence topicName: 실패를 없음으로 그린다 project: TechLog @@ -12,7 +12,7 @@ source: - final/document.md#§10.6 --- -# 매퍼가 null 을 돌려주고 호출부가 걸러 내, 기록이 조용히 사라졌다 +# 매퍼가 null을 반환해 QUESTION과 CONCEPT가 목록에서 누락됐다 프로젝트 기록 목록에서 Open Question 이 보이지 않았다. 이 목록은 탐색의 지식 목록과 응답 모양이 다른데 그쪽 매퍼를 쓰고 있었다. 그 매퍼는 두 종류가 아니면 null 을 돌려주고 호출부가 걸러 내므로, 질문과 개념은 오류도 빈 줄도 남기지 않고 사라진다. @@ -20,7 +20,7 @@ source: - **화면은 못 읽은 것을 없다고 말하지 않는다** 같은 부류를 다루는 규칙이다. -- **개념을 하나 더하자 열세 곳이 그것을 조용히 삼켰다** +- **CONCEPT를 추가하자 종류 처리 누락이 열세 곳에서 드러났다** 이 매퍼가 그 열세 곳 중 하나다. - **합성 루트에 테스트가 없어 공개 사이트 전체가 오류 화면이었다** 스텁 때문에 매핑이 검사되지 않던 다른 사건이다. diff --git a/docs/TechLog/tech-log-studio/failure-drawn-as-absence/reference/reference-an-expected-failure-must-not-be-counted-as-a-failure.md b/docs/TechLog/tech-log-studio/failure-drawn-as-absence/reference/reference-an-expected-failure-must-not-be-counted-as-a-failure.md index c1dd985..d6250d4 100644 --- a/docs/TechLog/tech-log-studio/failure-drawn-as-absence/reference/reference-an-expected-failure-must-not-be-counted-as-a-failure.md +++ b/docs/TechLog/tech-log-studio/failure-drawn-as-absence/reference/reference-an-expected-failure-must-not-be-counted-as-a-failure.md @@ -16,7 +16,7 @@ source: 배포 뒤 전 화면을 훑는 스윕이 기대된 404 를 실패로 셌다. 건강한 배포 아래에 매번 같은 빨간 줄이 남았고, 그 줄은 곧 읽히지 않게 됐다. 기대된 실패는 조건을 적어 빼고 나머지는 전부 실패시킨다. -## 관계 +## 항상 실패하는 검사가 있으면 실제 회귀 실패가 묻힌다 - **화면은 못 읽은 것을 없다고 말하지 않는다** 같은 프로젝트에서 실패를 어떻게 다룰지 정한 짝이 되는 기준이다. @@ -25,13 +25,13 @@ source: - **계약은 앵커라고 적었고 만드는 쪽은 경로를 만들었다** 같은 스윕이 실제 결함을 잡아야 했던 사건이다. -## 목적 +## 기대된 실패와 새 실패를 구분한다 검사 결과를 사람이 계속 읽게 하려고 정한 기준이다. 매번 늑대를 외치는 검사는 읽히지 않게 되고, 진짜 실패가 그 옆에 눈에 띄지 않은 채 앉아 있게 된다. -## 규칙 +## 기대 실패는 조건을 명시하고 나머지 실패는 그대로 실패시킨다 ### 1. 기대된 실패는 조건을 적어 뺀다 @@ -51,18 +51,18 @@ source: 왜 그 응답이 기대된 것인지 적혀 있지 않으면 다음 사람이 조건을 넓힌다. 비슷한 404 가 하나 더 나왔을 때 같은 조건에 넣을지 판단할 근거가 없기 때문이다. -## 적용 조건 +## 현재 환경에서 의도적으로 통과시킬 수 없는 검사가 있을 때 - 배포 뒤 전 화면을 훑는 스윕처럼 결과를 사람이 훑어보는 검사를 만들 때 - 정상 동작이 오류 상태 코드로 나타나는 화면이 있는 서비스에서 - 같은 빨간 줄이 매번 남기 시작했을 때 -## 예외 +## 원인과 제거 조건을 설명할 수 없는 실패 - 기계가 판정하고 사람이 결과를 읽지 않는 검사라면 빨간 줄이 쌓여도 무뎌지지 않는다. 그래도 통과 기준은 정해야 한다. - 그 응답이 정말 고쳐야 하는 것이면 조건으로 빼지 말고 고친다. 뺄지 고칠지는 사람이 고칠 것이 있는가로 가른다. -## 예시 +## 배포 전 guard와 환경 의존 검사 - 미리보기가 없는 문서의 404 를 스윕이 실패로 셌다. 건강한 배포 아래에 매번 같은 빨간 줄이 남았다 - 로그인 전 세션 탐침의 401 도 같은 부류라 같은 조건으로 제외했다 diff --git a/docs/TechLog/tech-log-studio/failure-drawn-as-absence/reference/reference-say-you-could-not-read-it.md b/docs/TechLog/tech-log-studio/failure-drawn-as-absence/reference/reference-say-you-could-not-read-it.md index 4bbce1f..1e340b5 100644 --- a/docs/TechLog/tech-log-studio/failure-drawn-as-absence/reference/reference-say-you-could-not-read-it.md +++ b/docs/TechLog/tech-log-studio/failure-drawn-as-absence/reference/reference-say-you-could-not-read-it.md @@ -17,22 +17,22 @@ source: 목록이나 요약처럼 「비어 있음」이 정상값인 화면에서는 실패와 0건이 같은 모양으로 그려진다. 작성자는 그것을 자기가 아직 쓰지 않은 것으로 읽는다. 못 읽었으면 못 읽었다고 적는다. -## 관계 +## 조회 실패와 빈 결과는 다른 상태다 - **「이 프로젝트에 열린 질문이 없습니다」 — 실제로는 넷이 있었다** 이 규칙의 근거 사건이다. - **한 칸의 실패가 옆 칸을 끌고 내려갔다** 실패가 어디까지 번지는지를 다룬 사건이다. -- **매퍼가 null 을 돌려주고 호출부가 걸러 내, 기록이 조용히 사라졌다** +- **매퍼가 null을 반환해 QUESTION과 CONCEPT가 목록에서 누락됐다** 실패가 아니라 항목이 사라진 변종이다. -## 목적 +## 읽지 못한 데이터를 없다고 표시하지 않는다 작성자가 「아직 안 썼다」와 「못 읽었다」를 구분할 수 있게 한다. 이 둘이 같은 화면이면 작성자는 다음에 무엇을 할지 정할 수 없다. 실패면 다시 부르거나 서버를 봐야 하고 0건이면 쓰면 되는데, 화면이 「없습니다」 하나로 답하면 뒤쪽으로 읽고 다시 쓰게 된다. -## 규칙 +## 오류와 empty state를 UI에서 분리한다 ### 1. 요청이 실패하면 실패했다고 적는다 @@ -58,19 +58,19 @@ source: 목록에 몇 개가 있어야 하는지 아는 사람만 알아챌 수 있다. 공개 화면에서는 그것을 아는 사람이 작성자뿐이다. -## 적용 조건 +## 목록 API 실패를 화면에서 처리할 때 - 목록·요약·카운트처럼 「비어 있음」이 정상값이라 실패와 구분되지 않는 화면을 만들 때 - 작성 도구를 만들 때. 작성자가 자기 작업물과 화면을 대조하므로 오독이 곧바로 작업 판단이 된다 - 한 화면이 여러 목록을 함께 받아 그릴 때 - 매퍼가 모르는 값에 빈 값을 돌려주고 호출부가 그것을 거를 때 -## 예외 +## 계약상 실패를 빈 결과로 정의한 endpoint - 정말로 0건인 것과 못 읽은 것을 구분할 수 없는 화면이라면 그 구분을 먼저 만든다. 구분 없이 문구만 바꾸면 0건이 실패로 읽힌다. - 읽는 사람이 그 데이터를 만들지 않는 화면에서는 실패를 화면 전체의 오류로 다뤄도 된다. 방문자에게는 어느 목록이 실패했는지가 할 일을 바꾸지 않는다. -## 예시 +## 질문 조회 404가 열린 질문 0개로 보인 문제 - 「이 프로젝트에 열린 질문이 없습니다」가 적혀 있는 동안 그 프로젝트에는 질문이 넷 있었고 공개 사이트에도 나오고 있었다 - 결정 목록만 404 인데 함께 묶어 읽은 질문 목록까지 「불러오지 못했습니다」가 됐다 diff --git a/docs/TechLog/tech-log-studio/hand-listed-kinds/case/case-one-new-kind-fell-through-thirteen-places.md b/docs/TechLog/tech-log-studio/hand-listed-kinds/case/case-one-new-kind-fell-through-thirteen-places.md index 795cf5f..b9fbac6 100644 --- a/docs/TechLog/tech-log-studio/hand-listed-kinds/case/case-one-new-kind-fell-through-thirteen-places.md +++ b/docs/TechLog/tech-log-studio/hand-listed-kinds/case/case-one-new-kind-fell-through-thirteen-places.md @@ -1,7 +1,7 @@ --- kind: CASE slug: one-new-kind-fell-through-thirteen-places -title: 개념을 하나 더하자 열세 곳이 그것을 조용히 삼켰다 +title: CONCEPT를 추가하자 종류 처리 누락이 열세 곳에서 드러났다 topic: hand-listed-kinds topicName: 손으로 나열한 종류 목록 project: TechLog @@ -20,7 +20,7 @@ source: - final/document.md#§10.3 --- -# 개념을 하나 더하자 열세 곳이 그것을 조용히 삼켰다 +# CONCEPT를 추가하자 종류 처리 누락이 열세 곳에서 드러났다 문서 종류에 CONCEPT 을 더했다. 컴파일도 통과하고 테스트도 통과했는데, 개념을 지우면 「질문을 찾을 수 없습니다」가 나오고 개념 상세 주소는 404 였고 탐색에서 type=CONCEPT 은 0건이었다. 그 뒤로도 같은 모양이 계속 나와 열세 번을 셌다. 매번 원인이 같았다 — 다섯 종류를 손으로 적어 둔 곳이 있었고 새 종류가 마지막 else 로 떨어졌다. @@ -39,7 +39,7 @@ source: 문서 종류는 다섯이다 — CASE, REFERENCE, QUESTION, CONCEPT, PROJECT_DECISION. 새 종류를 하나 더하면 그 종류를 아는 곳이 전부 함께 늘어나야 한다. -실제로는 늘지 않은 곳이 열세 곳 있었고, 그중 어느 곳도 오류를 내지 않았다. 삼항 사슬의 마지막 else 와 배열 리터럴의 끝이 모르는 값을 조용히 받아 갔다. +실제로는 늘지 않은 곳이 열세 곳 있었고, 그중 어느 곳도 오류를 내지 않았다. 삼항 사슬의 마지막 else 와 배열 리터럴의 끝이 모르는 값을 오류 없이 마지막 분기로 처리했다. ## 결론 diff --git a/docs/TechLog/tech-log-studio/hand-listed-kinds/concept/concept-exhaustive-switch-and-record-tables.md b/docs/TechLog/tech-log-studio/hand-listed-kinds/concept/concept-exhaustive-switch-and-record-tables.md index b4d4495..60afec0 100644 --- a/docs/TechLog/tech-log-studio/hand-listed-kinds/concept/concept-exhaustive-switch-and-record-tables.md +++ b/docs/TechLog/tech-log-studio/hand-listed-kinds/concept/concept-exhaustive-switch-and-record-tables.md @@ -17,16 +17,16 @@ source: 같은 언어 안에서도 어떤 분기는 새 값을 더할 때 컴파일러가 빠진 값을 짚고 어떤 분기는 아무 말도 하지 않는다. 삼항 사슬과 배열 리터럴은 후자이고, Record 와 식으로 쓴 sealed switch 는 전자다. -## 관계 +## 유한한 종류 목록은 누락을 컴파일 시점에 드러내야 한다 -- **개념을 하나 더하자 열세 곳이 그것을 조용히 삼켰다** +- **CONCEPT를 추가하자 종류 처리 누락이 열세 곳에서 드러났다** 이 개념이 없으면 그 열세 건이 왜 컴파일을 지나갔는지 읽히지 않는다. - **종류를 나열하는 곳은 컴파일러나 계약 대조 검사가 세게 만든다** 이 개념에서 두 방법을 골라 규칙으로 굳혔다. - **TypeScript 가 검사를 놓아 주는 네 곳** 같은 컴파일러가 검사를 놓아 주는 다른 곳들이다. -## 본문 +## Record 표와 exhaustive switch가 빠진 가지를 잡는 방식 @@ -102,7 +102,7 @@ Java 에서도 같은 갈림이 있다. `switch` 를 문으로 쓰면 아무 가 위 `pathOf` 는 식으로 쓴 switch 인데도 `default` 가 있어 그 요구를 받지 않는다. 분기 대상이 `String` 이라 컴파일러가 셀 수 있는 값 집합이 없고, `default` 없이는 컴파일되지 않기 때문이다. -이 저장소의 백엔드에서 게시 상태 코드와 활동 유형과 소유자 유형과 slug 중복 검사와 렌더 모델은 전부 sealed 타입을 대상으로 식으로 쓰인 switch 를 지난다. 그래서 종류를 하나 더했을 때 백엔드에서 조용히 넘어간 곳이 프론트보다 적었다. +이 저장소의 백엔드에서 게시 상태 코드와 활동 유형과 소유자 유형과 slug 중복 검사와 렌더 모델은 전부 sealed 타입을 대상으로 식으로 쓰인 switch 를 지난다. 그래서 종류를 하나 더했을 때 백엔드에서 누락을 오류 없이 통과시킨 곳이 프론트보다 적었다. ## 같은 함수 안에서 두 목록이 갈릴 수 있다 diff --git a/docs/TechLog/tech-log-studio/hand-listed-kinds/question/openquestion-two-kind-tables-outside-the-compiler.md b/docs/TechLog/tech-log-studio/hand-listed-kinds/question/openquestion-two-kind-tables-outside-the-compiler.md index 09d9386..f6b98e5 100644 --- a/docs/TechLog/tech-log-studio/hand-listed-kinds/question/openquestion-two-kind-tables-outside-the-compiler.md +++ b/docs/TechLog/tech-log-studio/hand-listed-kinds/question/openquestion-two-kind-tables-outside-the-compiler.md @@ -18,16 +18,16 @@ source: 종류를 나열하는 곳을 표와 sealed switch 식으로 바꾸면서 둘을 남겼다. 하나는 담기는 값이 종류 밖으로 나가서, 하나는 아직 손대지 않아서다. 둘 다 새 종류를 더할 때 컴파일이 통과하고 값만 틀린다. -## 관계 +## 문서 종류를 나열하는 곳 대부분은 컴파일러가 확인한다 -- **개념을 하나 더하자 열세 곳이 그것을 조용히 삼켰다** +- **CONCEPT를 추가하자 종류 처리 누락이 열세 곳에서 드러났다** 이 질문이 남은 사건이다. - **컴파일러가 빠진 가지를 요구하게 만드는 두 가지 — Record 표와 sealed switch 식** 왜 이 두 곳이 표로 바뀌지 못했는지가 그 개념에 있다. - **계약은 앵커라고 적었고 만드는 쪽은 경로를 만들었다** pathOf 가 만든 주소가 틀렸던 다른 사건이다. -## 사실 +## 두 종류 표는 아직 문자열 목록으로 남아 있다 공개 경로 생성기는 문서 종류가 아니라 공개 투영의 종류 칸(String)으로 switch 하고 default -> null 이 남아 있다. @@ -41,7 +41,7 @@ PublicPathsTest 가 지금 종류마다 만들어 낸 경로를 공개 라우트 남은 사슬은 배타적이 아니라 가산형이다. 종류를 빠뜨리면 잘못된 분기로 떨어지는 것이 아니라 그 종류의 추가 칸을 검사하지 않는다. -## 가정 +## 계약에서 파생하면 새 종류 누락을 줄일 수 있다 PROJECT 와 RELEASE 를 다른 분기로 빼면 나머지를 sealed 로 좁힐 수 있다고 보고 있다. 그 둘이 공개 투영에서 어떤 경로를 갖는지 전수로 확인하지 않았다. @@ -49,7 +49,7 @@ PROJECT 와 RELEASE 를 다른 분기로 빼면 나머지를 sealed 로 좁힐 홈 focus 의 최근 결정 경로가 PublicPathsTest 를 지나지 않는다고 보고 있다. 그 테스트가 도는 대상 목록을 직접 세지 않았다. -## 미지수 +## 두 표를 어느 정본에서 만들 것인가 공개 경로 생성기가 읽는 칸이 종류 밖의 값도 담는 상태에서, 그 둘을 어디로 옮기면 나머지를 컴파일러가 세게 만들 수 있는가. @@ -57,13 +57,13 @@ PublicPathsTest 가 닿지 않는 경로가 몇 개인가. 문자열 칸 목록을 표로 바꾸면 지금과 다른 결과를 내는 종류가 있는가. -## 제약 +## 런타임 데이터와 빌드 타임 타입의 경계가 다르다 공개 투영은 한 테이블이 문서와 프로젝트와 릴리스를 함께 담는다. 이 구조는 바꾸지 않는다. 계약의 문서 종류는 다섯이고 여기에 프로젝트와 릴리스를 더하지 않는다. 그 둘은 문서 게시 파이프라인을 타지 않고, 릴리스는 자체 상태로 공개되므로 투영에 행이 아예 없다. -## 선택지 +## Record 표로 옮길지 계약 대조 검사를 둘지 **경로 생성기를 두 분기로 가른다** 문서 종류를 받는 sealed switch 와 프로젝트·릴리스를 받는 분기로 나눈다. 호출부가 어느 쪽인지 알아야 하므로 호출부를 함께 본다. @@ -74,7 +74,7 @@ PublicPathsTest 가 닿지 않는 경로가 몇 개인가. **문자열 칸 목록만 먼저 표로 바꾼다** 가산형이라 위험이 낮고 다른 것과 얽히지 않는다. 이 선택만으로는 경로 생성기가 null 을 내보내는 것을 막지 못한다. -## 다음 검증 +## 새 kind를 하나 추가해 두 표가 실패하는지 확인한다 1. 경로 생성기를 문서 종류 switch 와 프로젝트·릴리스 분기로 갈라 보고, 새 종류를 하나 더해 컴파일이 멈추는지 본다 2. PublicPathsTest 가 도는 대상 목록을 세고, 홈 focus 의 최근 결정 경로가 거기 있는지 확인한다. 없으면 그 경로를 테스트에 넣는다 diff --git a/docs/TechLog/tech-log-studio/hand-listed-kinds/reference/reference-enumerate-kinds-where-the-compiler-sees-it.md b/docs/TechLog/tech-log-studio/hand-listed-kinds/reference/reference-enumerate-kinds-where-the-compiler-sees-it.md index 1b6c927..3000ba3 100644 --- a/docs/TechLog/tech-log-studio/hand-listed-kinds/reference/reference-enumerate-kinds-where-the-compiler-sees-it.md +++ b/docs/TechLog/tech-log-studio/hand-listed-kinds/reference/reference-enumerate-kinds-where-the-compiler-sees-it.md @@ -16,24 +16,24 @@ source: # 종류를 나열하는 곳은 컴파일러나 계약 대조 검사가 세게 만든다 -값이 유한한 집합을 코드 여러 곳에서 분기할 때, 그 목록을 사람이 세면 새 값이 조용히 빠진다. 이 저장소에서 같은 실수가 열세 번 났고, 그 뒤로 두 가지만 쓴다 — 컴파일러가 항목을 요구하게 만들거나, 컴파일러가 못 보는 경계에는 계약을 읽어 대조하는 검사를 두거나. +값이 유한한 집합을 코드 여러 곳에서 분기할 때, 그 목록을 사람이 세면 새 값이 누락돼도 오류가 나지 않는다. 이 저장소에서 같은 실수가 열세 번 났고, 그 뒤로 두 가지만 쓴다 — 컴파일러가 항목을 요구하게 만들거나, 컴파일러가 못 보는 경계에는 계약을 읽어 대조하는 검사를 두거나. -## 관계 +## 새 kind 누락은 손으로 나열한 분기에서 반복됐다 -- **개념을 하나 더하자 열세 곳이 그것을 조용히 삼켰다** +- **CONCEPT를 추가하자 종류 처리 누락이 열세 곳에서 드러났다** 이 규칙의 근거가 되는 사건이다. - **컴파일러가 빠진 가지를 요구하게 만드는 두 가지 — Record 표와 sealed switch 식** 규칙이 쓰는 두 방법을 그 개념이 설명한다. - **계약과 구현은 서버와 화면 양쪽에서 전수 대조한다** 컴파일러가 못 보는 경계를 다루는 짝이 되는 기준이다. -## 목적 +## 유한한 종류 목록을 컴파일러나 계약 검사에 맡긴다 새 값을 더했을 때 오류 없이 잘못된 값이 나가는 것을 막는다. 이 부류는 컴파일도 테스트도 지나간다. 마지막 else 가 모르는 값을 받아 가면 모든 값에 갈 곳이 있고 각 가지가 내놓는 타입도 같으므로, 타입 검사가 물을 것이 남지 않는다. 그래서 배포된 뒤 사용자가 만나기 전까지 아무도 모른다. -## 규칙 +## Record와 exhaustive switch를 우선 사용한다 ### 1. 유한한 집합의 분기는 값마다 항목을 요구하는 형태로 쓴다 @@ -63,15 +63,15 @@ Record 는 키 집합이 K 와 정확히 같은 객체 타입이라, 키 세 계약을 파싱해 「일부 값만 열거한 enum」을 전부 뽑는 편이 눈으로 찾는 것보다 빠르고 빠뜨림이 없다. -## 적용 조건 +## CASE·REFERENCE·QUESTION 같은 닫힌 종류 집합을 분기할 때 - 값이 유한한 집합인 것을 코드나 계약 여러 곳에서 분기하거나 열거하는 곳. 문서 종류, 상태, 역할, 오류 코드, 라우트 이름이 여기 해당한다. -- 새 값을 더하는 변경을 시작할 때 이 규칙을 먼저 건다. 다 더한 뒤에 빠진 곳을 찾는 순서로는 조용히 빠진 곳을 못 찾는다 — 조용히 빠진 곳은 증상이 없으므로 훑어서는 나오지 않는다. +- 새 값을 더하는 변경을 시작할 때 이 규칙을 먼저 건다. 다 더한 뒤에 빠진 곳을 찾는 순서로는 오류 없이 누락된 곳을 찾기 어렵다. 이런 누락은 증상이 없으므로 훑어서는 나오지 않는다. - 계약을 소유한 저장소가 따로 있으면 계약 쪽 열거형에도 같이 건다. 이 저장소에서 열세 건 중 셋이 계약 안에 있었다. -## 예외 +## 런타임 계약 데이터처럼 컴파일러가 볼 수 없는 경계 - 그 칸이 집합 밖의 값도 담으면 표로 좁힐 수 없다. 공개 투영의 resource_type 이 그런 칸이다 — 문서 종류 다섯에 더해 PROJECT 와 RELEASE 를 담는다. 이때는 대조 검사를 대신 둔다. @@ -79,11 +79,11 @@ Record 는 키 집합이 K 와 정확히 같은 객체 타입이라, 키 - 값이 하나뿐이거나 분기가 한 곳에만 있으면 표로 바꾸는 비용이 이득보다 크다. -## 예시 +## CONCEPT 추가 뒤 열세 곳에서 드러난 누락 - 종류를 하나 더한 커밋에서 컴파일러가 게시 상태 코드와 활동 유형과 소유자 유형과 slug 중복 검사와 렌더 모델까지 짚었다. 식으로 쓴 switch 였기 때문이다. -- 같은 종류를 더할 때 프론트엔드에서는 열세 곳이 조용히 지나갔다. 삼항 사슬과 배열 리터럴이었다. +- 같은 종류를 더할 때 프론트엔드에서는 열세 곳의 누락이 오류 없이 통과했다. 삼항 사슬과 배열 리터럴이었다. - 계약에서 CONCEPT 을 빼자 백엔드의 계약 대조 테스트가 빨개졌다. 그 확인을 하고 커밋했다. diff --git a/docs/TechLog/tech-log-studio/one-route-many-hand-kept-lists/decision/decision-do-not-translate-the-catch-all-route.md b/docs/TechLog/tech-log-studio/one-route-many-hand-kept-lists/decision/decision-do-not-translate-the-catch-all-route.md index 5a7d0c7..f39e06b 100644 --- a/docs/TechLog/tech-log-studio/one-route-many-hand-kept-lists/decision/decision-do-not-translate-the-catch-all-route.md +++ b/docs/TechLog/tech-log-studio/one-route-many-hand-kept-lists/decision/decision-do-not-translate-the-catch-all-route.md @@ -19,7 +19,7 @@ source: 라우트 계약에서 nginx 서빙 패턴을 만들 때 catch-all 라우트는 번역하지 않는다. 모든 미매치 주소에 index.html 을 주면 엣지의 404 가 soft 200 이 되고, 깨진 링크가 크롤러에도 우리 감사에도 잡히지 않는다. -## 근거 +## SPA catch-all과 nginx의 정적 파일 경로는 같은 계약이 아니다 - **nginx 가 모르는 라우트는 새로고침에서 404 다** 서빙 패턴을 라우트 계약에서 유도하기로 한 사건이고, 이 결정이 그 유도 규칙의 일부다. @@ -28,13 +28,13 @@ source: - **계약은 앵커라고 적었고 만드는 쪽은 경로를 만들었다** 엣지의 404 가 감사에 잡혀야 하는 이유를 보여 주는 사건이다. -## 결정문 +## catch-all 라우트를 nginx location 패턴으로 변환하지 않는다 라우트 계약에서 nginx 서빙 패턴을 생성할 때, catch-all 라우트는 패턴으로 번역하지 않고 버린다. 등록된 Public 라우트마다 정규식 하나를 만들고, 파라미터는 한 세그먼트만 잡되 슬래시는 잡지 않는다. -## 판단 이유 +## 정적 파일 요청까지 SPA fallback으로 보내는 오동작을 막는다 모든 미매치 URL 에 index.html 을 주면 엣지에서 404 였을 요청이 200 으로 바뀐다. 라우터는 그 주소를 모르므로 「없는 화면」을 그리지만, 상태 코드는 200 이다. @@ -44,7 +44,7 @@ source: 대안은 catch-all 을 번역하고 라우터가 404 화면을 그리게 하는 것이었다. 사람에게 보이는 화면은 같지만 기계가 읽는 상태 코드가 달라지므로 고르지 않았다. -## 영향 +## 공개 라우트와 웹 서버 서빙 규칙을 별도로 검증한다 라우트를 더할 때마다 서빙 패턴이 함께 움직인다. 이 비용은 라우트 계약에서 유도해 없앴다 — 손으로 배열을 고치지 않는다. diff --git a/docs/TechLog/tech-log-studio/one-route-many-hand-kept-lists/question/openquestion-nobody-signed-the-accessibility-evidence.md b/docs/TechLog/tech-log-studio/one-route-many-hand-kept-lists/question/openquestion-nobody-signed-the-accessibility-evidence.md index fb3e1f7..b78357e 100644 --- a/docs/TechLog/tech-log-studio/one-route-many-hand-kept-lists/question/openquestion-nobody-signed-the-accessibility-evidence.md +++ b/docs/TechLog/tech-log-studio/one-route-many-hand-kept-lists/question/openquestion-nobody-signed-the-accessibility-evidence.md @@ -17,7 +17,7 @@ source: CI 게이트가 설치된 라우트마다 수동 접근성 증거 파일을 하나씩 요구한다. 파일은 라우트마다 있고 그중 사람이 서명한 것은 하나도 없다. 게이트는 파일의 존재만 세고 서명은 보지 않는다. -## 관계 +## 라우트 배포에는 수동 접근성 확인 항목이 포함돼 있다 - **라우트 하나가 건드리는 여덟 곳과, 그것들이 우는 시점** 이 게이트가 그 목록의 한 줄이다. @@ -26,7 +26,7 @@ CI 게이트가 설치된 라우트마다 수동 접근성 증거 파일을 하 - **가드는 작동했는데 제가 그것을 돌리지 않아 두 번 새어 나갔다** 이 게이트를 빠뜨려 빨간 채로 지나간 사건이다. -## 사실 +## 필요한 증거 개수는 세지만 실제 확인자는 남지 않는다 `FE-GATE-009` 프론트엔드 게이트는 설치된 라우트마다 증거 파일 하나를 요구하고, 그 집합이 정확히 일치하지 않으면 거절한다. @@ -40,13 +40,13 @@ review:a11y-manual 스크립트는 그래서 실패하는 것이 지금은 정 게이트가 세는 것은 파일의 존재이고 그 안의 서명 상태는 보지 않는다. -## 가정 +## 체크 결과와 확인자를 함께 남기면 누락을 구분할 수 있다 게이트가 파일의 존재만 세는 것이 의도라고 보고 있다. 서명을 조건에 넣으면 라우트를 더할 때마다 배포가 막히므로 그렇게 두었다고 짐작하지만, 그 판단이 적힌 곳을 찾지 못했다. 서명 절차 자체는 사람이 화면을 열어 확인하는 일이라고 보고 있다. 어떤 항목을 어디까지 보는지 정한 문서를 확인하지 않았다. -## 미지수 +## 수동 증거를 어떤 형식과 위치에 보관할 것인가 게이트가 서명 여부까지 보게 하면 지금 몇 개의 라우트가 막히는가. @@ -54,13 +54,13 @@ review:a11y-manual 스크립트는 그래서 실패하는 것이 지금은 정 라우트 하나를 사람이 실제로 검토하는 데 얼마가 드는가. 그 비용을 모르면 어느 쪽도 고를 수 없다. -## 제약 +## 자동 검사만으로 확인할 수 없는 항목이 남아 있다 프론트엔드 게이트 `FE-GATE-009`는 라우트 집합과 증거 집합이 정확히 일치하기를 요구한다. 이 규칙은 바꾸지 않는다 — 빠뜨림이 통과가 되면 게이트가 아니다. 수동 접근성 증거는 사람이 만든다. 자동 검사로 대신하지 않는다. -## 선택지 +## 체크리스트에 서명을 남길지 CI 입력으로 받을지 **서명을 게이트의 통과 조건으로 올린다** 라우트마다 사람이 검토하고 서명해야 배포된다. 지금 상태에서는 모든 라우트가 막히므로 한 번에 올릴 수 없고, 라우트별로 나눠 올려야 한다. @@ -71,7 +71,7 @@ review:a11y-manual 스크립트는 그래서 실패하는 것이 지금은 정 **게이트는 그대로 두고 서명 현황을 별도로 보고한다** 배포는 막지 않고 서명되지 않은 라우트 수를 드러낸다. 막지 않는 지표가 읽히지 않게 되는 것을 감수한다 — 이 저장소에서 매번 우는 검사가 읽히지 않게 된 사례가 이미 있다. -## 다음 검증 +## 새 라우트 하나를 배포 절차 끝까지 따라가 본다 1. 라우트 하나를 골라 실제로 사람이 검토하고 서명해, 그 검토에 얼마가 드는지 잰다 2. 게이트가 서명 여부까지 보게 고치고 나머지 라우트에서 실제로 빨개지는지 확인한다 diff --git a/docs/TechLog/tech-log-studio/one-route-many-hand-kept-lists/reference/reference-derive-the-route-lists-from-the-route-contract.md b/docs/TechLog/tech-log-studio/one-route-many-hand-kept-lists/reference/reference-derive-the-route-lists-from-the-route-contract.md index 40dd048..13a5b0c 100644 --- a/docs/TechLog/tech-log-studio/one-route-many-hand-kept-lists/reference/reference-derive-the-route-lists-from-the-route-contract.md +++ b/docs/TechLog/tech-log-studio/one-route-many-hand-kept-lists/reference/reference-derive-the-route-lists-from-the-route-contract.md @@ -17,7 +17,7 @@ source: 라우트를 하나 더하면 서빙 패턴·청크 이름·게이트 기준값이 함께 움직인다. 손으로 유지하는 목록은 같은 방식으로 두 번 실패했다. 유도할 수 있는 것은 라우트 계약에서 유도하고, 유도할 수 없는 상수는 옛 값을 재현한 뒤에 갱신한다. -## 관계 +## 라우트 목록을 여러 파일에 손으로 복사하면 서로 어긋난다 - **nginx 가 모르는 라우트는 새로고침에서 404 다** 이 기준의 근거 사건이다. @@ -26,13 +26,13 @@ source: - **종류를 나열하는 곳은 컴파일러나 계약 대조 검사가 세게 만든다** 같은 병을 다른 유한 집합에서 다루는 기준이다. -## 목적 +## 파생 가능한 라우트 목록은 route contract에서 만든다 라우트를 더할 때 함께 움직여야 하는 목록이 빠지는 것을 막는다. 이 부류는 우는 시점이 제각각이다. 어떤 것은 빌드 매니페스트 단계에서, 어떤 것은 배포 직전 CI 에서, 어떤 것은 배포한 뒤 방문자가 먼저 만난다. -## 규칙 +## 정본 하나에서 manifest와 검사 목록을 유도한다 ### 1. 서빙 패턴은 라우트 계약에서 유도한다 @@ -54,19 +54,19 @@ source: 빠뜨림이 통과가 되지 않게 하려면 집합이 정확히 일치해야 한다. 그러면 라우트를 더할 때마다 상수들이 함께 움직이고, 그 갱신을 사람이 한다. -## 적용 조건 +## 같은 라우트 집합을 build와 deploy, accessibility에서 함께 쓸 때 - 라우트 하나가 서빙 패턴·청크 이름·게이트 기준값 같은 목록을 함께 움직이는 프론트엔드. 라우트를 더하거나 지우는 변경에서 걸린다. - 새 화면을 여는 작업을 시작할 때 그 목록부터 세고 시작한다. 다 만든 뒤에 세면 배포 직전에 걸린다. -## 예외 +## 정본에서 계산할 수 없는 수동 검증 항목 - catch-all 라우트는 서빙 패턴으로 번역하지 않는다. 모든 미매치 URL 에 index.html 을 주면 엣지 404 가 soft 200 이 된다. - 목록이 하나이고 그 목록을 빌드가 강제하면 유도 규칙을 따로 두지 않아도 된다. -## 예시 +## 새 라우트가 건드리던 여덟 위치 /studio/releases 가 평문 404 였다. 라우트도 청크도 있었고 서빙 계약의 손 배열에만 없었다. diff --git a/docs/TechLog/tech-log-studio/one-thing-many-names/case/case-nine-names-for-five-kinds.md b/docs/TechLog/tech-log-studio/one-thing-many-names/case/case-nine-names-for-five-kinds.md index 4a474c1..2de80fd 100644 --- a/docs/TechLog/tech-log-studio/one-thing-many-names/case/case-nine-names-for-five-kinds.md +++ b/docs/TechLog/tech-log-studio/one-thing-many-names/case/case-nine-names-for-five-kinds.md @@ -21,7 +21,7 @@ source: - **종류 이름을 두 번 바꿨다 — 화면의 이름과 계약의 kind 를 갈랐다** 이 표를 한 곳으로 모은 뒤에 이름 자체를 다시 정한 기록이다. -- **개념을 하나 더하자 열세 곳이 그것을 조용히 삼켰다** +- **CONCEPT를 추가하자 종류 처리 누락이 열세 곳에서 드러났다** 같은 종류 목록이 코드 쪽에서 갈라진 사건이다. - **톤을 지적받으면 고쳐 쓰지 말고 어떤 말을 쓸지 묻는다** 같은 시기에 문구를 다룬 기준이다. diff --git a/docs/TechLog/tech-log-studio/one-thing-many-names/question/openquestion-the-refusal-does-not-name-what-blocks-it.md b/docs/TechLog/tech-log-studio/one-thing-many-names/question/openquestion-the-refusal-does-not-name-what-blocks-it.md index c7bc003..692e21d 100644 --- a/docs/TechLog/tech-log-studio/one-thing-many-names/question/openquestion-the-refusal-does-not-name-what-blocks-it.md +++ b/docs/TechLog/tech-log-studio/one-thing-many-names/question/openquestion-the-refusal-does-not-name-what-blocks-it.md @@ -18,7 +18,7 @@ source: 작업본 삭제가 막히는 이유는 다섯 가지인데 전부 같은 한 문장으로 나온다. 실제 사례에서 막은 것은 프로젝트 링크 한 행이었고, 문구는 「다른 기록이 참조한다」고 말했다. -## 관계 +## 삭제 거부 사유는 서버에서 여러 조건으로 나뉜다 - **서버는 하나를 답했는데 화면은 추측 셋을 출력했다** 화면 쪽 문구를 고친 사건이고, 서버 쪽 문구는 고치지 않았다. @@ -27,7 +27,7 @@ source: - **화면은 못 읽은 것을 없다고 말하지 않는다** 화면이 무엇을 말해야 하는지를 다루는 기준이다. -## 사실 +## 화면에는 다섯 사유가 같은 문장으로 표시된다 작업본 삭제 실패는 다섯 참조 중 무엇이 막았든 같은 오류 코드로 나간다 — DOCUMENT_IN_USE. @@ -43,7 +43,7 @@ source: 사용자는 Project 필드를 「미지정」으로 바꾸고 저장한 뒤 삭제했다. -## 가정 +## 서버의 원인 코드를 유지하면 화면도 정확히 설명할 수 있다 문구가 「another record」라고 하니 사용자가 Studio의 「관계」 편집기를 먼저 확인한다고 보고 있다. 실제 사례가 하나이고, 다른 사용자가 같은 순서로 움직이는지는 확인하지 않았다. @@ -51,7 +51,7 @@ source: 질문 삭제처럼 참조가 둘뿐이면 이 문제가 덜하다고 보고 있다. 질문 삭제에서 사용자가 실제로 헤맨 기록은 없다. -## 미지수 +## 사용자에게 어느 수준까지 원인을 노출할 것인가 무엇이 막는지 말하면서 내부 표 이름을 노출하지 않는 문구가 무엇인가. @@ -59,7 +59,7 @@ source: 코드를 다섯으로 나누면 계약의 오류 코드 열거형도 함께 늘어난다. 그것을 반입하는 두 저장소가 그 값을 알아야 하는데, 그 비용이 얼마인가. -## 제약 +## 도메인 정보와 내부 구현 세부사항을 구분해야 한다 클라이언트에 내보내는 메시지에 내부 표 이름이나 컬럼 이름을 넣지 않는다. @@ -67,7 +67,7 @@ source: 오류 코드는 계약이 열거한다. 코드를 늘리면 계약과 반입한 두 저장소가 함께 움직인다. -## 선택지 +## 원인 코드를 세분화할지 현재 문구를 유지할지 **참조 검사를 종류별로 갈라 어느 것이 걸렸는지 돌려준다** 다섯 개의 존재 검사를 따로 돌리고 걸린 종류를 응답에 싣는다. 화면이 그 종류를 사용자가 고칠 수 있는 화면의 이름으로 옮긴다. 코드를 늘리지 않고 응답의 부가 필드로 실으면 계약 변경이 작다. @@ -81,7 +81,7 @@ source: **문구만 고쳐 프로젝트 연결을 함께 언급한다** 가장 싸다. 다섯 중 어느 것인지는 여전히 말하지 못하고, 사용자가 확인할 화면이 셋으로 늘어난다. -## 다음 검증 +## 다섯 거부 조건을 각각 만들어 응답과 화면을 비교한다 1. 참조 검사를 종류별로 갈라 걸린 종류를 응답에 실어 보고, 삭제 경로의 응답 시간이 얼마나 달라지는지 잰다 2. 다섯 종류를 사용자가 고칠 수 있는 화면 이름으로 옮겨 적고 몇 가지로 줄어드는지 센다 diff --git a/docs/TechLog/tech-log-studio/one-thing-many-names/reference/reference-ask-which-words-to-use.md b/docs/TechLog/tech-log-studio/one-thing-many-names/reference/reference-ask-which-words-to-use.md index 1dcc2ad..669fcfd 100644 --- a/docs/TechLog/tech-log-studio/one-thing-many-names/reference/reference-ask-which-words-to-use.md +++ b/docs/TechLog/tech-log-studio/one-thing-many-names/reference/reference-ask-which-words-to-use.md @@ -16,7 +16,7 @@ source: 사용자가 프로필의 문구가 AI 스럽다고 지적했다. 고쳐 쓴 첫 번째 안도 거절당했고, 결국 사용자가 직접 쓴 텍스트를 그대로 실었다. 이 사이트의 글은 작성자가 자기 말로 쓴다. -## 관계 +## 톤 문제는 기술 사실보다 표현 선택에서 생긴다 - **종류 이름을 두 번 바꿨다 — 화면의 이름과 계약의 kind 를 갈랐다** 두 번째 안을 문어체로 세울 때 이 기준을 썼다. @@ -25,13 +25,13 @@ source: - **한 화면에 종류 이름이 아홉 개 떠 있었다 — 표가 여섯 벌이었다** 같은 시기에 종류 이름을 표 하나로 모았다. -## 목적 +## 사용자가 원하는 말투를 추측으로 다시 만들지 않는다 작성자의 목소리로 쓰인 글을 고쳐 쓰다 두 번 거절당하는 것을 막는다. 톤을 지적할 때 사용자가 가리키는 것은 문장의 품질이 아니라 그 말을 누가 쓰는가다. 「더 나은 문장」을 제안할 때와 그 사람의 말투로 쓸 때 필요한 것이 다르고, 후자는 제안하는 쪽이 잘하지 못한다. -## 규칙 +## 표현 지적을 받으면 사용할 단어와 피할 단어를 확인한다 ### 1. 톤을 지적받으면 고쳐 쓰기 전에 어떤 말을 쓸지 묻는다 @@ -49,18 +49,18 @@ source: 무엇이 무엇으로 바뀌었는지 남겨 두면 다음에 같은 문구를 고칠 때 방향이 정해진다. -## 적용 조건 +## 내용은 맞지만 문체나 용어 선택이 맞지 않을 때 - 공개 화면의 글이 작성자의 목소리인 곳 — 프로필, 프로젝트 소개, 구역 제목, 기록의 소제목 - 톤이 어색하다는 지적을 받았을 때 - 기존 글에 없던 낱말이나 어미를 새로 넣으려 할 때 -## 예외 +## 오탈자나 명백한 문법 오류처럼 의도가 분명한 수정 - 오류 문구처럼 서버가 답한 사실을 그대로 실어야 하는 곳에서는 말투를 묻지 않는다. 무엇을 실을지를 먼저 정한다. - 계약이나 코드가 정한 이름은 이 규칙에서 뺀다. 표시 이름만 바꾸고 계약 값은 그대로 둔다. -## 예시 +## 기술 용어를 사용자 표현으로 맞추는 경우 - 「섞는다」·「함께 기록한다」·「흩어지지 않게」가 무엇을 하는지 말하지 않는 동사로 끝난다고 지적받았다 - 「결론이 서는 조건」·「프로젝트를 답니다」·「접근을 나눠 견주고」가 번역투로 지적받았다 diff --git a/docs/TechLog/tech-log-studio/only-visible-after-deploying/concept/concept-deploying-without-a-registry.md b/docs/TechLog/tech-log-studio/only-visible-after-deploying/concept/concept-deploying-without-a-registry.md index 6f6ff51..946bc20 100644 --- a/docs/TechLog/tech-log-studio/only-visible-after-deploying/concept/concept-deploying-without-a-registry.md +++ b/docs/TechLog/tech-log-studio/only-visible-after-deploying/concept/concept-deploying-without-a-registry.md @@ -17,7 +17,7 @@ source: 이 사이트는 이미지 레지스트리를 쓰지 않는다. 로컬에서 빌드한 이미지를 tar 로 말아 서버에 올리고, 클러스터 안에 일회성 Job 을 띄워 컨테이너 런타임으로 import 한 뒤 이미지 태그를 바꾼다. 이 경로 때문에 빌드 인자와 파일 권한이 배포에서만 드러난다. -## 관계 +## 이미지 Registry 없이도 노드에 같은 이미지를 배포할 수 있다 - **배포 인자를 빠뜨려 배포본이 존재하지 않는 주소를 불렀다** 이 경로에서 빌드 인자가 어떻게 새는지가 그 기록에 있다. @@ -26,7 +26,7 @@ source: - **배포 전에 사람이 돌려야 하는 것과 그 함정** 이 경로에서 사람이 기억해야 하는 것들이 그 기준에 있다. -## 본문 +## tar export와 import를 이용한 이미지 전달 경로 diff --git a/docs/TechLog/tech-log-studio/seams-no-test-crosses/case/case-the-composition-root-had-no-test.md b/docs/TechLog/tech-log-studio/seams-no-test-crosses/case/case-the-composition-root-had-no-test.md index c71003b..d85265e 100644 --- a/docs/TechLog/tech-log-studio/seams-no-test-crosses/case/case-the-composition-root-had-no-test.md +++ b/docs/TechLog/tech-log-studio/seams-no-test-crosses/case/case-the-composition-root-had-no-test.md @@ -24,7 +24,7 @@ source: - **이음매마다 그 이음매를 실제로 지나는 검사를 하나씩 둔다** 합성 루트가 그 목록의 한 줄이다. -- **매퍼가 null 을 돌려주고 호출부가 걸러 내, 기록이 조용히 사라졌다** +- **매퍼가 null을 반환해 QUESTION과 CONCEPT가 목록에서 누락됐다** 스텁 때문에 보이지 않던 다른 매핑 결함이다. - **한 경계를 고쳤으면 값의 여정 끝에서 확인한다** 이 사건이 그 규칙의 근거 하나다. diff --git a/docs/TechLog/tech-log-studio/seams-no-test-crosses/case/case-the-generator-dropped-four-contract-fields.md b/docs/TechLog/tech-log-studio/seams-no-test-crosses/case/case-the-generator-dropped-four-contract-fields.md index 1daf1ae..8586df6 100644 --- a/docs/TechLog/tech-log-studio/seams-no-test-crosses/case/case-the-generator-dropped-four-contract-fields.md +++ b/docs/TechLog/tech-log-studio/seams-no-test-crosses/case/case-the-generator-dropped-four-contract-fields.md @@ -1,7 +1,7 @@ --- kind: CASE slug: the-generator-dropped-four-contract-fields -title: 생성기가 계약 필드 넷을 조용히 빠뜨렸다 — 파생 스펙에 남은 YAML alias 34곳 +title: 생성기가 계약 필드 넷을 누락했고 파생 스펙에 YAML alias 34곳이 생겼다 topic: seams-no-test-crosses topicName: 테스트가 지나지 않는 이음매 project: TechLog @@ -12,7 +12,7 @@ source: - final/document.md#§7.6 --- -# 생성기가 계약 필드 넷을 조용히 빠뜨렸다 — 파생 스펙에 남은 YAML alias 34곳 +# 생성기가 계약 필드 넷을 누락했고 파생 스펙에 YAML alias 34곳이 생겼다 계약에 있는 필드 넷이 생성된 모델에서 사라져 있었다. 파생 단계의 YAML alias 때문에 파서가 스키마 15개를 거절했고, 거절당한 스키마들은 전부 타입을 명시하고 있어 계약 결함처럼 보이지 않았다. 검증을 끄면 생성이 성공했고, 그렇게 만든 모델에 그 넷이 없었다. 컴파일은 통과한다 — 아직 아무도 그 필드를 안 쓰니까. diff --git a/docs/TechLog/tech-log-studio/seams-no-test-crosses/reference/reference-put-one-check-on-each-seam.md b/docs/TechLog/tech-log-studio/seams-no-test-crosses/reference/reference-put-one-check-on-each-seam.md index c5fb60f..95e3859 100644 --- a/docs/TechLog/tech-log-studio/seams-no-test-crosses/reference/reference-put-one-check-on-each-seam.md +++ b/docs/TechLog/tech-log-studio/seams-no-test-crosses/reference/reference-put-one-check-on-each-seam.md @@ -16,7 +16,7 @@ source: 「모든 검사가 통과했는데 운영에서 깨졌다」가 다섯 번 있었다. 매번 그 이음매를 아무 테스트도 지나지 않았다. 층을 스텁으로 나눠 시험하는 구조에서는 그 나눈 자국마다 검사가 하나씩 필요하다. -## 관계 +## 값이 여러 변환 경계를 지나면 각 경계에서 누락될 수 있다 - **파드가 두 번 CrashLoopBackOff 로 들어갔다** 스프링 컨텍스트 이음매의 근거 사건이다. @@ -24,16 +24,16 @@ source: persistence SQL 이음매의 근거 사건이다. - **합성 루트에 테스트가 없어 공개 사이트 전체가 오류 화면이었다** 합성 루트와 HTTP 매퍼 이음매의 근거 사건이다. -- **생성기가 계약 필드 넷을 조용히 빠뜨렸다** +- **생성기가 계약 필드 넷을 누락했다** 생성기 이음매의 근거 사건이다. -## 목적 +## 경계마다 실제 입력과 출력을 지나는 검사를 둔다 층을 스텁으로 나눠 시험하는 구조에서 그 나눈 자국이 검사되지 않고 남는 것을 막는다. 이 부류는 모든 검사가 초록불인 상태로 배포된다. 각 층의 검사는 자기 층을 정확히 보고 통과하며, 통과하지 않은 것은 층과 층 사이다. -## 규칙 +## 생성·매핑·직렬화·렌더링 경계를 각각 확인한다 ### 1. 스프링 컨텍스트를 띄우는 검사를 하나 둔다 @@ -59,13 +59,13 @@ source: 컨테이너를 띄우는 검사를 표준 검사에 넣으면 모든 빌드가 느려진다. 빼는 것은 되지만, 뺀 뒤에 그 태스크가 돌지 않으면 검사가 없는 것과 같다. -## 적용 조건 +## 한 값이 backend에서 frontend까지 여러 모델을 통과할 때 - 스텁으로 층을 나눠 시험하는 구조. 계약이 다른 저장소에 있고 생성기를 지나 들어오거나, 컨테이너가 필요한 검사를 별도 태스크로 뺀 저장소에서 걸린다. - 「모든 검사가 통과했는데 운영에서 깨졌다」가 나오면 무엇이 깨졌는지보다 어느 이음매를 아무 검사도 지나지 않았는지를 먼저 센다. -## 예외 +## 한 단계 안에서만 사용되고 외부 경계를 넘지 않는 값 - 그 층을 실제로 지나는 검사가 이미 있으면 더 두지 않는다. @@ -73,7 +73,7 @@ source: - 정적으로 셀 수 있는 규칙은 컨텍스트를 띄우지 않고도 걸린다. 그때는 무거운 검사를 새로 두지 않는다. -## 예시 +## 계약 필드와 relation summary 누락 - 컨텍스트를 띄우지 않아 파드가 두 번 CrashLoopBackOff 로 들어갔다. 실제 PostgreSQL 위에서 도는 통합 테스트 26개도 통과한 상태였다. diff --git a/docs/TechLog/tech-log-studio/tech-log-tree.json b/docs/TechLog/tech-log-studio/tech-log-tree.json index 8623b38..7e3791f 100644 --- a/docs/TechLog/tech-log-studio/tech-log-tree.json +++ b/docs/TechLog/tech-log-studio/tech-log-tree.json @@ -92,7 +92,7 @@ "kinds": { "case": [ { - "title": "개념을 하나 더하자 열세 곳이 그것을 조용히 삼켰다", + "title": "CONCEPT를 추가하자 종류 처리 누락이 열세 곳에서 드러났다", "slug": "one-new-kind-fell-through-thirteen-places", "readiness": "READY", "source": [ @@ -720,7 +720,7 @@ "evidenceFiles": [] }, { - "title": "생성기가 계약 필드 넷을 조용히 빠뜨렸다 — 파생 스펙에 남은 YAML alias 34곳", + "title": "생성기가 계약 필드 넷을 누락했고 파생 스펙에 YAML alias 34곳이 생겼다", "slug": "the-generator-dropped-four-contract-fields", "readiness": "READY", "source": [ @@ -1198,7 +1198,7 @@ "evidenceFiles": [] }, { - "title": "매퍼가 null 을 돌려주고 호출부가 걸러 내, 기록이 조용히 사라졌다", + "title": "매퍼가 null을 반환해 QUESTION과 CONCEPT가 목록에서 누락됐다", "slug": "records-disappeared-without-a-trace", "readiness": "READY", "source": [ diff --git a/docs/TechLog/tech-log-studio/values-lost-between-boundaries/concept/concept-eleven-boundaries-a-value-crosses.md b/docs/TechLog/tech-log-studio/values-lost-between-boundaries/concept/concept-eleven-boundaries-a-value-crosses.md index c126471..6858cae 100644 --- a/docs/TechLog/tech-log-studio/values-lost-between-boundaries/concept/concept-eleven-boundaries-a-value-crosses.md +++ b/docs/TechLog/tech-log-studio/values-lost-between-boundaries/concept/concept-eleven-boundaries-a-value-crosses.md @@ -20,7 +20,7 @@ source: 공개 화면의 한 줄은 PostgreSQL 의 투영 테이블에서 출발해 열한 번 모양을 바꾼 뒤에 그려진다. 그 사이 어느 한 곳이 값을 담지 않아도 오류가 나지 않는다. undefined 는 빈 문자열로 그려지고 빈 배열은 「항목이 없습니다」로 그려진다. -## 관계 +## 공개 화면의 값 하나도 여러 계약과 변환을 지난다 - **공개 Reference 가 통째로 비어 있었다 — 이름이 어긋났고 본문은 다른 테이블에 있었다** 이 경계 중 두 곳에서 값이 사라진 사건이다. @@ -29,7 +29,7 @@ source: - **한 경계를 고쳤으면 값의 여정 끝에서 확인한다** 이 경계 수가 그 규칙의 근거다. -## 본문 +## DB에서 공개 화면까지 값이 지나는 열한 경계 diff --git a/docs/TechLog/tech-log-studio/values-lost-between-boundaries/reference/reference-a-missing-contract-field-has-a-signature.md b/docs/TechLog/tech-log-studio/values-lost-between-boundaries/reference/reference-a-missing-contract-field-has-a-signature.md index b6db9bc..a3b02e8 100644 --- a/docs/TechLog/tech-log-studio/values-lost-between-boundaries/reference/reference-a-missing-contract-field-has-a-signature.md +++ b/docs/TechLog/tech-log-studio/values-lost-between-boundaries/reference/reference-a-missing-contract-field-has-a-signature.md @@ -17,7 +17,7 @@ source: Studio 편집기에서는 값이 다 보이는데 공개 화면만 비어 있다면, 작성과 공개 사이의 계약 경계를 먼저 확인할 만한 강한 신호다. 이 저장소에서는 같은 신호가 여덟 번 계약 누락을 가리켰지만, 저장 구조가 종류별로 다른 경우에는 조회 로직이 원인일 수 있다. -## 관계 +## Studio에는 보이는데 공개 화면에만 없으면 경계 중 하나가 값을 버린 것이다 - **공개 Reference 가 통째로 비어 있었다 — 이름이 어긋났고 본문은 다른 테이블에 있었다** 이 신호가 처음 잡힌 사건이다. @@ -26,13 +26,13 @@ Studio 편집기에서는 값이 다 보이는데 공개 화면만 비어 있다 - **한 경계를 고쳤으면 값의 여정 끝에서 확인한다** 칸을 더한 뒤 무엇을 확인할지가 그 기준에 있다. -## 목적 +## UI 문제처럼 보여도 먼저 contract와 mapper를 확인한다 데이터베이스에 값이 있는데 화면이 비어 있을 때 어디를 먼저 볼지 정한다. 이 부류는 오류를 내지 않으므로 로그에서 출발하면 아무것도 나오지 않는다. undefined 는 빈 문자열로 그려지고 빈 배열은 「항목이 없습니다」로 그려진다. -## 규칙 +## DB에서 public response까지 field 이름을 순서대로 대조한다 ### 1. Studio 에서는 보이고 공개 쪽만 비면 그 사이의 계약을 먼저 본다 @@ -54,13 +54,13 @@ Reference 의 본문은 문서 본문 칸이 아니라 규칙과 예시를 담 게이트웨이가 읽는 이름이 계약의 타입에 있는지를 묻는다. 값을 비교하는 검사는 픽스처를 게이트웨이가 읽는 이름으로 만들면 그대로 통과한다 — 테스트 작성자와 게이트웨이 작성자가 이름에 대해 합의한 것을 확인할 뿐이다. -## 적용 조건 +## 작성 화면에는 값이 있지만 공개 화면에는 없을 때 - 같은 데이터를 두 표면이 각자의 계약으로 읽고, 한쪽만 비어 보이는 화면. 작성 계약과 조회 계약이 나뉜 구조에서 걸린다. - 계약에 칸을 더하거나 화면에 칸을 더하는 변경에서도 건다. 화면이 먼저 늘면 그 칸이 응답에 있는지 확인할 곳이 없다. -## 예외 +## 공개 정책상 의도적으로 숨기는 field - 두 표면이 같은 계약을 쓰면 이 신호는 성립하지 않는다. 그때는 매퍼나 질의를 먼저 본다. @@ -68,7 +68,7 @@ Reference 의 본문은 문서 본문 칸이 아니라 규칙과 예시를 담 - 값이 있는데 겹쳐 보이는 경우는 이 신호가 아니다. 빈 칸을 다른 값으로 메우면 같은 글이 두 번 나온다. -## 예시 +## Reference 본문 field 이름 불일치 - 공개 Reference 가 통째로 비었을 때 게이트웨이가 읽던 네 이름이 전부 계약에 없었다. diff --git a/docs/TechLog/tech-log-studio/values-lost-between-boundaries/reference/reference-verify-at-the-end-of-the-value-journey.md b/docs/TechLog/tech-log-studio/values-lost-between-boundaries/reference/reference-verify-at-the-end-of-the-value-journey.md index 05ddfb2..cab5f2c 100644 --- a/docs/TechLog/tech-log-studio/values-lost-between-boundaries/reference/reference-verify-at-the-end-of-the-value-journey.md +++ b/docs/TechLog/tech-log-studio/values-lost-between-boundaries/reference/reference-verify-at-the-end-of-the-value-journey.md @@ -18,7 +18,7 @@ source: 값이 여러 경계를 갈아타는 구조에서 한 경계를 고치고 「고쳤다」고 판단해 세 번 틀렸다. 타입 검사도 단위 테스트도 「코드를 읽어 보니 맞다」도 전부 중간 지점이다. 배포본에서 그 값이 실제로 그려지는 곳까지 가서 확인한다. -## 관계 +## 중간 경계를 고쳐도 최종 화면까지 값이 도달하지 않을 수 있다 - **관계의 요약이 경계 세 곳을 지나며 사라졌다** 한 경계를 고치고 판단해 두 번 틀린 사건이다. 여기서 요약은 공개 계약의 `ResolvedRelation.summary`다. @@ -27,13 +27,13 @@ source: - **TypeScript 가 검사를 놓아 주는 네 곳** 타입 통과가 반영의 증거가 아닌 이유가 그 개념에 있다. -## 목적 +## 수정한 값이 실제 사용 지점까지 도착했는지 확인한다 「고쳤다」는 판단이 틀리는 것을 막는다. 값이 열한 경계를 지나는 구조에서 한 경계만 보고 판단하면, 다음 경계가 같은 값을 다시 버려도 알 수 없다. 이 저장소에서 그 판단이 세 번 틀렸다. -## 규칙 +## 가장 마지막 consumer에서 결과를 재검증한다 ### 1. 고친 값이 실제로 그려지는 곳까지 가서 본다 @@ -55,19 +55,19 @@ source: 값이 아니라 이름을 지키는 검사를 두면 여정의 한 구간을 그 검사가 대신한다. 그 구간이 어디까지인지 적어 두지 않으면 다음 사람이 검사를 여정 전체로 읽는다. -## 적용 조건 +## mapper나 contract field를 수정한 뒤 - 값이 계약·매퍼·포트를 여러 번 갈아타는 구조에서 「고쳤다」를 판단할 때. 계약을 소유한 저장소가 따로 있고 생성기를 지나 들어오면 특히 걸린다. - 앞선 커밋이 같은 값을 고치려다 못 고친 이력이 있으면 반드시 건다. 그 커밋이 무엇을 근거로 고쳤다고 판단했는지가 대개 중간 지점이다. -## 예외 +## 중간 변환 자체가 최종 산출물인 테스트 - 경계가 하나뿐이거나 고친 그 곳이 여정의 끝이면 중간 확인으로 충분하다. - 배포본을 열 수 없는 변경 — 아직 배포되지 않은 경로 — 은 여정의 끝까지 갈 수 없다. 그때는 어디까지 확인했는지를 적는다. -## 예시 +## relation summary를 세 경계에서 수정한 뒤 공개 목록 확인 - 관계 요약을 세 번 고쳤다. 매번 화면을 보고 나서야 다음 경계가 버리는 것을 알았다. diff --git a/docs/TechLog/tech-log-studio/what-the-compiler-lets-through/concept/concept-where-typescript-stops-checking.md b/docs/TechLog/tech-log-studio/what-the-compiler-lets-through/concept/concept-where-typescript-stops-checking.md index 7141a9f..680aca1 100644 --- a/docs/TechLog/tech-log-studio/what-the-compiler-lets-through/concept/concept-where-typescript-stops-checking.md +++ b/docs/TechLog/tech-log-studio/what-the-compiler-lets-through/concept/concept-where-typescript-stops-checking.md @@ -18,7 +18,7 @@ source: 「타입 검사가 통과했으니 반영됐다」는 판단이 이 저장소에서 네 번 틀렸다. 매번 다른 이유였다 — 메서드 매개변수의 bivariance, as 단언, never 로 받아 캐스팅하는 조립기, 그리고 검사할 파일을 갖지 않은 tsconfig 다. -## 관계 +## TypeScript 타입 검사가 모든 런타임 누락을 잡지는 못한다 - **구현이 종류를 좁게 적어도 넓은 포트를 만족했다** bivariance 가 통과시킨 사건이다. @@ -27,7 +27,7 @@ source: - **공개 Reference 가 통째로 비어 있었다** as 단언이 통과시킨 사건이다. -## 본문 +## bivariance와 type assertion, never cast, tsconfig 경계 @@ -65,7 +65,7 @@ as 는 「이 값을 이 타입으로 다루겠다」는 선언이다. 그 이 요청을 만드는 조립기가 입력을 `(input: never)` 로 받아 캐스팅하면, 계약에 인자를 더해도 컴파일러가 아무 말도 하지 않는다. `never` 는 어떤 값도 속하지 않는 타입이라 무엇을 넘겨도 검사할 것이 없다. -조립기가 손으로 나열한 질의 인자에 그 값이 없으면 요청에서 조용히 빠진다. 목록의 페이지 번호를 눌러도 쪽이 넘어가지 않던 것이 이 모양이었다 — `page` 가 조립기의 목록에 없었다. +조립기가 손으로 나열한 질의 인자에 그 값이 없으면 요청에서 누락돼도 오류가 나지 않는다. 목록의 페이지 번호를 눌러도 쪽이 넘어가지 않던 것이 이 모양이었다 — `page` 가 조립기의 목록에 없었다. ## 검사할 파일이 없는 tsconfig diff --git a/docs/TechLog/tech-log-studio/when-a-guard-can-be-trusted/reference/reference-revert-the-defect-and-watch-the-guard-fail.md b/docs/TechLog/tech-log-studio/when-a-guard-can-be-trusted/reference/reference-revert-the-defect-and-watch-the-guard-fail.md index c7da1f9..f5d3ad6 100644 --- a/docs/TechLog/tech-log-studio/when-a-guard-can-be-trusted/reference/reference-revert-the-defect-and-watch-the-guard-fail.md +++ b/docs/TechLog/tech-log-studio/when-a-guard-can-be-trusted/reference/reference-revert-the-defect-and-watch-the-guard-fail.md @@ -20,7 +20,7 @@ source: 결함을 되돌려 실제로 빨개지는 것을 확인한 뒤에 커밋한다. 확인하지 않은 가드는 그 결함이 원래 없었는지 검사가 안 도는지 구별되지 않는다. -## 관계 +## Guard가 존재하는 것과 실제 결함을 잡는 것은 다르다 - **가드는 작동했는데 제가 그것을 돌리지 않아 두 번 새어 나갔다** 가드가 정확해도 돌리지 않으면 소용없다는 사건이다. @@ -29,13 +29,13 @@ source: - **이음매마다 그 이음매를 실제로 지나는 검사를 하나씩 둔다** 어디에 가드를 둘지를 다루는 기준이다. -## 목적 +## 회귀 검사가 문제를 실제로 탐지하는지 확인한다 무엇도 잡지 못하는 가드가 초록불로 남는 것을 막는다. 가드를 넣었다는 것과 그 가드가 무엇을 잡는다는 것은 다르다. 둘은 화면에서 구분되지 않는다 — 검사가 통과했을 때 그 결함이 원래 없었는지 검사가 그것을 안 보는지 알 방법이 없다. -## 규칙 +## 결함을 잠시 되돌려 guard가 실패하는지 본다 ### 1. 결함을 되돌려 그 가드가 실제로 멈추는 것을 확인한 뒤 커밋한다 @@ -55,18 +55,18 @@ source: 사람이 기억해서 돌리는 가드는 절반만 존재한다. 가드가 정확해도 결과를 아무도 읽지 않으면 빨간 채로 여러 커밋을 지나간다. -## 적용 조건 +## 새 회귀 테스트나 CI guard를 추가할 때 - 재발 방지로 테스트·아키텍처 규칙·CI 게이트를 넣을 때 - 결함을 고치는 커밋에서 가드를 함께 넣을 때 - 이미 있는 가드가 무엇을 잡는지 확인해야 할 때 -## 예외 +## 파괴적이거나 외부 시스템을 실제로 손상시키는 재현 - 결함을 되돌릴 수 없는 것 — 이미 마이그레이션으로 고친 데이터, 지난 배포에서만 나던 상태 — 은 현재 상태가 고쳐져 있음을 대신 증거로 남긴다. - 기존 가드를 옮기거나 이름만 바꾸는 변경은 되돌려 확인하지 않아도 된다. 다만 옮긴 뒤에 한 번은 돌린다. -## 예시 +## route와 UI contract guard 검증 - 가드 셋을 각각 결함으로 되돌려 실제로 빨개지는 것을 확인한 기록을 남겼다 - 계약에서 CONCEPT 을 빼자 백엔드의 계약 대조 테스트가 빨개졌다 diff --git a/docs/TechLog/tech-log-studio/when-a-guard-can-be-trusted/reference/reference-what-a-person-must-run-before-deploying.md b/docs/TechLog/tech-log-studio/when-a-guard-can-be-trusted/reference/reference-what-a-person-must-run-before-deploying.md index 2f9b49f..f47b7a3 100644 --- a/docs/TechLog/tech-log-studio/when-a-guard-can-be-trusted/reference/reference-what-a-person-must-run-before-deploying.md +++ b/docs/TechLog/tech-log-studio/when-a-guard-can-be-trusted/reference/reference-what-a-person-must-run-before-deploying.md @@ -20,7 +20,7 @@ source: CI 에 묶이지 않은 검증이 남아 있으면 그것을 돌리는 것은 사람이다. 다섯 명령을 다 돌려야 하고, 그중 둘은 순서와 환경 때문에 그냥 돌리면 틀린 답을 준다. -## 관계 +## 자동화돼 있지 않은 검사는 사람이 실행하지 않으면 빠진다 - **가드는 작동했는데 제가 그것을 돌리지 않아 두 번 새어 나갔다** 이 목록이 필요해진 사건이다. @@ -29,13 +29,13 @@ CI 에 묶이지 않은 검증이 남아 있으면 그것을 돌리는 것은 - **레지스트리 없이 tar 를 import 하는 배포 경로** 빌드 산출물에 커밋 해시가 들어가는 이유가 그 개념에 있다. -## 목적 +## 배포 전에 필요한 수동 명령을 명시한다 배포 전에 돌려야 하는 것을 사람이 기억에 의존해 고르는 것을 막는다. 이 저장소에서 두 번 빠뜨려 결함이 배포까지 갔다. 명령이 여럿이고 그중 일부만 도는 것이 가능한 구조에서는 「돌렸다」가 무엇을 돌렸다는 뜻인지 정해 두어야 한다. -## 규칙 +## 명령과 기대 결과, 실패 시 중단 조건을 함께 적는다 ### 1. 프론트는 다섯 개를 다 돌린다 @@ -57,18 +57,18 @@ npm_config_* 환경 변수가 설정되어 CI 워크플로 생성 테스트가 하위 프로세스를 띄우는 세 케이스는 이 환경에서 실패하고 같은 리비전의 다른 실행에서도 똑같이 재현된다. 코드 변경과 무관하다는 것을 적어 두지 않으면 다음 사람이 그것을 고치려 든다. -## 적용 조건 +## CI가 아직 실행하지 않는 검사나 로컬 검증 - CI 에 묶이지 않은 검증이 남아 있는 저장소에서 배포 직전에 하는 일 - 명령이 여럿이고 그중 일부만 도는 것이 가능할 때 - 빌드 산출물이 작업 트리 상태에 따라 달라지는 저장소에서 -## 예외 +## 이미 배포 파이프라인에서 강제되는 검사 - CI 가 그 명령을 돌리면 이 목록에서 뺀다. 사람이 기억해서 돌리는 가드는 절반만 존재한다. - 테스트 실행기가 메모리를 더 필요로 하는 조합이면 힙을 올린다. 증상이 테스트 실패가 아니라 실행기를 완료할 수 없다는 메시지로 나와 원인을 가린다. -## 예시 +## 별도 화면 테스트와 typecheck 명령 - 화면 테스트를 돌리지 않아 23건이 빨간 채로 여러 커밋을 지나갔다 - 루트 tsconfig 를 직접 부르는 명령이 통과해서 운영의 ReferenceError 를 못 봤다 diff --git a/docs/keycloak-session-store/final/evidence/raw/2026-09-22-test-server-revalidation/a2-12-atomic-revalidation.txt b/docs/keycloak-session-store/final/evidence/raw/2026-09-22-test-server-revalidation/a2-12-atomic-revalidation.txt new file mode 100644 index 0000000..947c42f --- /dev/null +++ b/docs/keycloak-session-store/final/evidence/raw/2026-09-22-test-server-revalidation/a2-12-atomic-revalidation.txt @@ -0,0 +1,33 @@ +BASELINE +db=1/1 +keycloak-0=2.0 +keycloak-1=2.0 +PROBE_READY +CONTROL refresh_local=200 refresh_remote=200 login=200 admin=200 jwks=200 wellknown=200 token_lengths=612/612/758 cid=yes +CACHE_BEFORE +keycloak-0=2.0 +keycloak-1=1.0 +DB_BEFORE=3 +EXTERNAL_BEFORE=200 +2026-09-22T18:04:32+09:00 +DB_DOWN +OUTAGE refresh_local=500 refresh_remote=500 login=500 admin=500 jwks=200 wellknown=200 +TIMELINE t=0 ready=true/true external=200 +TIMELINE t=5 ready=true/true external=200 +TIMELINE t=10 ready=true/true external=200 +TIMELINE t=15 ready=true/true external=200 +TIMELINE t=20 ready=false/true external=200 +TIMELINE t=25 ready=false/true external=200 +TIMELINE t=30 ready=false/false external=503 +DB_ERRORS +keycloak-0=102 +keycloak-1=46 +HEALTH +keycloak-0={ "status": "DOWN", "checks": [ { "name": "Graceful Shutdown", "status": "UP" }, { "name": "Keycloak database connections async health check", "status": "DOWN", "data": { "Failing since": "2026-09-22 09:03:08,754" } }, { "name": "Keycloak Initialized", "status": "UP" }, { "name": "Keycloak cluster health check", "status": "UP" } ]} +keycloak-1={ "status": "DOWN", "checks": [ { "name": "Graceful Shutdown", "status": "UP" }, { "name": "Keycloak cluster health check", "status": "UP" }, { "name": "Keycloak Initialized", "status": "UP" }, { "name": "Keycloak database connections async health check", "status": "DOWN", "data": { "Failing since": "2026-09-22 09:03:14,616" } } ]} +DB_UP +RECOVERY t=0 ready=false/false external=503 +RECOVERY t=5 ready=true/false external=200 +RECOVERY t=10 ready=true/true external=200 +FINAL db=3/3 restarts=0,0->0,0 +RECOVERY_CONFIRMED diff --git a/docs/keycloak-session-store/final/evidence/raw/2026-09-22-test-server-revalidation/a4-02-control-plane-loss.txt b/docs/keycloak-session-store/final/evidence/raw/2026-09-22-test-server-revalidation/a4-02-control-plane-loss.txt new file mode 100644 index 0000000..a16f7b2 --- /dev/null +++ b/docs/keycloak-session-store/final/evidence/raw/2026-09-22-test-server-revalidation/a4-02-control-plane-loss.txt @@ -0,0 +1,43 @@ +BASELINE +running + +NAMESPACE NAME READY STATUS RESTARTS AGE IP NODE NOMINATED NODE READINESS GATES +keycloak-lab keycloak-1 1/1 Running 0 20m 10.42.0.48 kc-lab-1 +kube-system coredns-54996dc9b4-7qwqm 1/1 Running 0 10m 10.42.0.49 kc-lab-1 +kube-system helm-install-traefik-crd-ph2zj 0/1 Completed 0 24h kc-lab-1 +kube-system svclb-traefik-8bc45361-cdnkt 2/2 Running 2 (23h ago) 24h 10.42.0.15 kc-lab-1 +kube-system traefik-5d6fcf895-jfcdt 1/1 Running 0 10m 10.42.0.50 kc-lab-1 +observability grafana-845b5678cf-vjpcm 1/1 Running 1 (23h ago) 23h 10.42.0.19 kc-lab-1 +observability prometheus-6774f94f7c-d6r84 1/1 Running 1 (23h ago) 23h 10.42.0.20 kc-lab-1 +traefik 1/1 1 1 24h +AUTH_BEFORE=200 +DESTROY 2026-09-22T16:58:22+09:00 +Domain 'kc-lab-1' destroyed + +VM_STATE=shut off + +KUBECTL_RC=1 +Unable to connect to the server: net/http: request canceled while waiting for connection (Client.Timeout exceeded while awaiting headers) +CRICTL_SURVIVORS +CONTAINER IMAGE CREATED STATE NAME ATTEMPT POD ID POD NAMESPACE +00477aec4ccdd 60e153026e8f5 8 minutes ago Running keycloak 1 2e216373d9ca6 keycloak-0 keycloak-lab +eccf426dc80e5 81bd698b4594e 8 minutes ago Running postgres 0 d0f0e484f59b0 postgres-7b474b88c8-vxpvn keycloak-lab +AUTH_DOWN=000 curl_rc=28 +START 2026-09-22T16:58:41+09:00 +RECOVERY i=1 api=no auth=000 +RECOVERY i=2 api=yes auth=000 +RECOVERY i=3 api=yes auth=404 +RECOVERY i=4 api=yes auth=404 +RECOVERY i=5 api=yes auth=404 +RECOVERY i=6 api=yes auth=404 +RECOVERY i=7 api=yes auth=502 +RECOVERY i=8 api=yes auth=200 +FINAL +running + +kc-lab-1 Ready +kc-lab-2 Ready +keycloak-0 1/1 Running +keycloak-1 0/1 Error +postgres-7b474b88c8-vxpvn 1/1 Running +AUTH_FINAL=200 diff --git a/docs/keycloak-session-store/final/evidence/raw/2026-09-22-test-server-revalidation/a4-03-full-recovery.txt b/docs/keycloak-session-store/final/evidence/raw/2026-09-22-test-server-revalidation/a4-03-full-recovery.txt new file mode 100644 index 0000000..78b4855 --- /dev/null +++ b/docs/keycloak-session-store/final/evidence/raw/2026-09-22-test-server-revalidation/a4-03-full-recovery.txt @@ -0,0 +1,10 @@ +i=1 k0=true k1=false auth=200 +i=2 k0=true k1=false auth=200 +i=3 k0=true k1=false auth=200 +i=4 k0=true k1=false auth=200 +i=5 k0=true k1=false auth=200 +i=6 k0=true k1=false auth=200 +i=7 k0=true k1=true auth=200 +keycloak-0 1/1 Running 1 (12m ago) 12m 10.42.1.61 kc-lab-2 +keycloak-1 1/1 Running 3 (57s ago) 23m 10.42.0.55 kc-lab-1 +postgres-7b474b88c8-vxpvn 1/1 Running 0 13m 10.42.1.60 kc-lab-2 diff --git a/docs/keycloak-session-store/final/evidence/raw/2026-09-22-test-server-revalidation/a4-04-pv-affinity-command.txt b/docs/keycloak-session-store/final/evidence/raw/2026-09-22-test-server-revalidation/a4-04-pv-affinity-command.txt new file mode 100644 index 0000000..1d119c5 --- /dev/null +++ b/docs/keycloak-session-store/final/evidence/raw/2026-09-22-test-server-revalidation/a4-04-pv-affinity-command.txt @@ -0,0 +1,2 @@ +PV=pvc-6ba2a481-a230-429b-8451-bd6c6b2bbd49 +kc-lab-2 diff --git a/docs/keycloak-session-store/final/evidence/raw/2026-09-22-test-server-revalidation/a5-01-clean-discovery-baseline.txt b/docs/keycloak-session-store/final/evidence/raw/2026-09-22-test-server-revalidation/a5-01-clean-discovery-baseline.txt new file mode 100644 index 0000000..c157a2d --- /dev/null +++ b/docs/keycloak-session-store/final/evidence/raw/2026-09-22-test-server-revalidation/a5-01-clean-discovery-baseline.txt @@ -0,0 +1,4 @@ +keycloak-0-7444|10.42.1.62:7800|f +keycloak-1-38608|10.42.0.59:7800|t +keycloak-0=2.0 +keycloak-1=2.0 diff --git a/docs/keycloak-session-store/final/evidence/raw/2026-09-22-test-server-revalidation/a5-02-atomic-partition.txt b/docs/keycloak-session-store/final/evidence/raw/2026-09-22-test-server-revalidation/a5-02-atomic-partition.txt new file mode 100644 index 0000000..ed626e4 --- /dev/null +++ b/docs/keycloak-session-store/final/evidence/raw/2026-09-22-test-server-revalidation/a5-02-atomic-partition.txt @@ -0,0 +1,55 @@ +BASE K0=10.42.1.62 node0=kc-lab-2 K1=10.42.0.59 node1=kc-lab-1 +BASELINE s0=2.0 s1=2.0 coords=1 +ONEWAY_APPLIED 2026-09-22T17:07:36+09:00 +ONEWAY i=1 s0=2.0 s1=2.0 coords=1 +ONEWAY i=2 s0=2.0 s1=2.0 coords=1 +ONEWAY i=3 s0=2.0 s1=2.0 coords=1 +ONEWAY i=4 s0=2.0 s1=2.0 coords=1 +ONEWAY i=5 s0=2.0 s1=2.0 coords=1 +ONEWAY i=6 s0=2.0 s1=2.0 coords=1 +ONEWAY i=7 s0=2.0 s1=2.0 coords=1 +ONEWAY i=8 s0=2.0 s1=2.0 coords=1 +ONEWAY i=9 s0=2.0 s1=2.0 coords=1 +ONEWAY i=10 s0=2.0 s1=2.0 coords=1 +ONEWAY i=11 s0=2.0 s1=2.0 coords=1 +ONEWAY i=12 s0=2.0 s1=2.0 coords=1 +ONEWAY i=13 s0=2.0 s1=2.0 coords=1 +ONEWAY i=14 s0=2.0 s1=2.0 coords=1 +ONEWAY i=15 s0=2.0 s1=2.0 coords=1 +ONEWAY i=16 s0=2.0 s1=2.0 coords=1 +ONEWAY i=17 s0=2.0 s1=2.0 coords=1 +ONEWAY i=18 s0=2.0 s1=2.0 coords=1 +TWOWAY_APPLIED 2026-09-22T17:09:14+09:00 +TWOWAY i=1 s0=2.0 s1=2.0 coords=1 r0=true r1=true +TWOWAY i=2 s0=2.0 s1=2.0 coords=1 r0=true r1=true +TWOWAY i=3 s0=2.0 s1=2.0 coords=1 r0=true r1=true +TWOWAY i=4 s0=2.0 s1=2.0 coords=1 r0=true r1=true +TWOWAY i=5 s0=2.0 s1=2.0 coords=1 r0=true r1=true +TWOWAY i=6 s0=2.0 s1=2.0 coords=1 r0=true r1=true +TWOWAY i=7 s0=2.0 s1=2.0 coords=1 r0=true r1=true +TWOWAY i=8 s0=1.0 s1=1.0 coords=2 r0=true r1=true +SPLIT_CONFIRMED +keycloak-0-7444|10.42.1.62:7800|true +keycloak-1-38608|10.42.0.59:7800|true +RULES_NODE1 +1 0 0 DROP 6 -- * * 0.0.0.0/0 10.42.0.59 tcp dpt:57800 +2 0 0 DROP 6 -- * * 0.0.0.0/0 10.42.0.59 tcp dpt:7800 +RULES_NODE0 +1 9 516 DROP 6 -- * * 0.0.0.0/0 10.42.1.62 tcp dpt:57800 +2 20 2034 DROP 6 -- * * 0.0.0.0/0 10.42.1.62 tcp dpt:7800 +RULES_REMOVED 2026-09-22T17:10:00+09:00 +RECOVERY i=1 s0=1.0 s1=1.0 coords=2 r0=true r1=true auth=200 +RECOVERY i=2 s0=1.0 s1=1.0 coords=2 r0=true r1=true auth=200 +RECOVERY i=3 s0=1.0 s1=1.0 coords=2 r0=true r1=true auth=200 +RECOVERY i=4 s0=1.0 s1=1.0 coords=2 r0=true r1=true auth=200 +RECOVERY i=5 s0=1.0 s1=1.0 coords=2 r0=true r1=true auth=200 +RECOVERY i=6 s0=1.0 s1=1.0 coords=2 r0=true r1=true auth=200 +RECOVERY i=7 s0=1.0 s1=1.0 coords=2 r0=true r1=true auth=200 +RECOVERY i=8 s0=1.0 s1=1.0 coords=2 r0=false r1=true auth=200 +RECOVERY i=9 s0=1.0 s1=1.0 coords=2 r0=false r1=true auth=200 +RECOVERY i=10 s0=2.0 s1=2.0 coords=1 r0=false r1=true auth=200 +RECOVERY i=11 s0=2.0 s1=2.0 coords=1 r0=false r1=true auth=200 +RECOVERY i=12 s0=2.0 s1=2.0 coords=1 r0=false r1=true auth=200 +RECOVERY i=13 s0=2.0 s1=2.0 coords=1 r0=false r1=true auth=200 +RECOVERY i=14 s0=2.0 s1=2.0 coords=1 r0=true r1=true auth=200 +RECOVERY_CONFIRMED diff --git a/docs/keycloak-session-store/tech-log-studio/losing-a-node-or-the-store/setup/setup-reproduce-a2-database-loss.md b/docs/keycloak-session-store/tech-log-studio/losing-a-node-or-the-store/setup/setup-reproduce-a2-database-loss.md index b5fdcdc..41cd23e 100644 --- a/docs/keycloak-session-store/tech-log-studio/losing-a-node-or-the-store/setup/setup-reproduce-a2-database-loss.md +++ b/docs/keycloak-session-store/tech-log-studio/losing-a-node-or-the-store/setup/setup-reproduce-a2-database-loss.md @@ -151,36 +151,46 @@ done `--rm` 임시 파드는 매번 만들고 지우므로 느리고 경합이 있고, 토큰을 단계 사이로 넘길 수 없다. 이 실험은 DB 정지 전에 발급한 토큰을 정지 후에 써야 하므로 파드를 하나 띄워 두고 `exec` 로 단계를 이어간다. -```bash label="[lab host] ① 상주 탐침 파드를 띄우고 Ready 까지 기다린다" -kubectl -n keycloak-lab run a2-probe --image=curlimages/curl:8.11.1 \ - --restart=Never \ - --env="K0=$K0" --env="K1=$K1" \ - --env="PW=$(kubectl -n keycloak-lab get secret keycloak-lab-secrets \ - -o jsonpath='{.data.KC_BOOTSTRAP_ADMIN_PASSWORD}' | base64 -d)" \ - --command -- sleep 7200 +```bash label="[lab host] ① Secret 값을 꺼내지 않고 상주 탐침 파드를 만든다" +cat < -## 무대 — 페이징 한 줄만 추가 +## 같은 조회에 Pageable만 추가했다 ```java label="통합 테스트 안에서 세운 무대 (프로덕션 아님)" "select f from FeedItemJpaEntity f join fetch f.highlights " // ← 한 bag fetch join diff --git a/docs/n+1liner/tech-log-studio/jpa-feed-query-performance/case/case-eager-toone-nplus1-without-access.md b/docs/n+1liner/tech-log-studio/jpa-feed-query-performance/case/case-eager-toone-nplus1-without-access.md index f6e360f..ea78e5d 100644 --- a/docs/n+1liner/tech-log-studio/jpa-feed-query-performance/case/case-eager-toone-nplus1-without-access.md +++ b/docs/n+1liner/tech-log-studio/jpa-feed-query-performance/case/case-eager-toone-nplus1-without-access.md @@ -26,7 +26,7 @@ source: @ManyToOne의 기본값인 EAGER는 연관을 반환 시점까지 로딩해 둔다는 계약이지 루트 SQL의 JOIN으로 가져온다는 보장이 아니다. 파생 쿼리에서는 루트를 먼저 조회한 뒤 행마다 2차 SELECT가 나갔고, getUser()와 getPage()를 한 번도 호출하지 않은 조회에서도 Page 조회가 N번 실행됐다. 지연 로딩인 highlights도 같은 조회에서 접근하는 순간 N번 나갔다. 왕복 수를 가른 것은 fetch 타입이 아니라 루트를 먼저 조회하고 연관을 행마다 채우는 조회 방식이었다. -## 관계 +## EAGER 연관 관계에서도 조회 방식에 따라 N+1이 생긴다 - **Fetch Type과 Fetch Strategy 구분** 로딩 시점 계약과 실제 조회 방식을 나눠 정리한 기록이다. @@ -35,13 +35,13 @@ source: - **JPA N+1 정량 진단 기준** 엔티티별 fetch 통계로 추가 조회를 세는 방법을 적은 기록이다. -## 문제 +## 필드에 접근하기 전부터 ToOne 추가 조회가 발생했다 이 조회의 총 PreparedStatement에서 컬렉션 조회를 빼도 User·Page 연관 조회가 남았고, 시더 카디널리티로 역산하면 13 / 120 / 1,020이었다. 엔티티에는 fetch를 따로 명시하지 않고 @ManyToOne은 즉시 로딩, @OneToMany는 지연 로딩이라는 JPA 기본값을 그대로 썼다. 즉시 로딩이면 한 번에 가져올 것이라고 예상했는데 실제로는 그렇지 않았다. -## 결론 +## Fetch Type만으로 N+1 여부를 판단하지 않는다 Hibernate 엔티티별 fetch 통계로 직접 읽은 값이 역산한 파생값과 정확히 일치했다. Page fetch는 N이 커지는 만큼 같이 늘어 10, 100, 1,000이 됐고, User fetch는 3에서 20까지 늘었다가 N=1,000에서도 20에 머물렀다. @@ -53,7 +53,7 @@ pages와 users의 실행계획은 둘 다 pk Index Scan이고 실행시간도 지연 로딩인 highlights도 같은 조회에서 접근하는 순간 N번 나갔다. 지연이냐 즉시냐가 아니라 루트를 먼저 조회한 뒤 연관을 행마다 채우는 조회 방식이 N+1을 만든다. -## 검증 환경 +## ToOne 조회를 측정한 환경 Java 21 Spring Boot 4.0.0 @@ -69,7 +69,7 @@ user : max(3, min(20, N/5+1)) (소수 풀 재사용) getEntityFetchCount() : 2차 SELECT로 로드된 엔티티 인스턴스 수 getEntityStatistics(PageJpaEntity).getFetchCount() : 엔티티별 fetch 수 -## 재현 조건 +## 같은 추가 조회를 다시 확인하는 조건 1. seed(N)으로 N ∈ {10, 100, 1000} 데이터를 만들고 loadFeed(0, N)을 실행한다. @@ -83,7 +83,7 @@ getEntityStatistics(PageJpaEntity).getFetchCount() : 엔티티별 fetch 수 6. 반복되는 ToOne 부모 쿼리를 EXPLAIN (ANALYZE, BUFFERS)로 확인한다. -## 본문 +## loadFeed를 실행했을 때 발생한 SQL diff --git a/docs/n+1liner/tech-log-studio/jpa-feed-query-performance/case/case-fetch-join-multibag-and-row-explosion.md b/docs/n+1liner/tech-log-studio/jpa-feed-query-performance/case/case-fetch-join-multibag-and-row-explosion.md index a95c486..ff24da6 100644 --- a/docs/n+1liner/tech-log-studio/jpa-feed-query-performance/case/case-fetch-join-multibag-and-row-explosion.md +++ b/docs/n+1liner/tech-log-studio/jpa-feed-query-performance/case/case-fetch-join-multibag-and-row-explosion.md @@ -24,7 +24,7 @@ source: 나누어 가져오지 말고 한 번에 가져오려고 연관을 모두 join fetch했다. 컬렉션 두 개를 동시에 fetch join하자 MultipleBagFetchException이 발생했고, 하나만 합치자 전송 행수가 시드 하이라이트 총량과 같아졌다. 쿼리 수는 줄었지만 한 쿼리가 나르는 행수와 메모리 적재량은 커졌다. -## 관계 +## N+1을 줄이기 위해 Collection Fetch Join을 적용했다 - **Fetch Join · Batch · Projection 선택 기준** 이 실패에서 나온 선택 기준이다. @@ -33,13 +33,13 @@ source: - **Collection Fetch Join Pagination의 In-memory Paging** 컬렉션 하나만 fetch join한 상태에서 페이징을 적용한 다음 기록이다. -## 문제 +## 두 Bag은 거부되고 하나만 Join해도 행 수가 늘었다 컬렉션 N+1과 User·Page 연관의 숨은 쿼리를 확인한 뒤 user·page·highlights·mentions를 모두 join fetch로 루트 SQL에 합쳐 보았다. MultipleBagFetchException을 재현하려면 fetch join할 컬렉션이 둘 이상 필요했다. 처음 만든 스키마에는 highlights만 있어서 목표 스키마의 feed_item_mentions를 퍼시스턴스 계층까지만 먼저 추가했다. 도메인 애그리거트·응답 매핑·공개 범위 판정은 뒤로 미뤘다. -## 결론 +## 쿼리 수 감소와 전송 행수 감소를 따로 본다 bag은 순서 컬럼이 없는 List 매핑이다. highlights와 mentions가 둘 다 bag이면 feed_item 한 행이 highlights h개 × mentions m개로 늘어난다. Hibernate는 이 곱집합을 원래 컬렉션으로 되돌릴 수 없다고 판단해 쿼리 생성 시점에 예외를 던진다. 데이터가 0건이어도 예외는 그대로 나온다. 실행 결과가 아니라 매핑 단계에서 막기 때문이다. @@ -49,7 +49,7 @@ Hibernate 6 이상이 fetch join의 루트 엔티티를 자동으로 중복 제 같은 N=100에서 PreparedStatement는 손대지 않은 loadFeed의 222개에서 121개로 줄었다. 그중 120개는 여전히 ToOne 2차 SELECT였고, 남은 조인 하나가 1,961행을 전달했다. 쿼리 수만 보면 개선처럼 보여서 항목별로 다시 나눠 세어 보았다. -## 검증 환경 +## MultiBag과 Row Explosion을 확인한 환경 Java 21 Spring Boot 4.0.0 @@ -67,7 +67,7 @@ feed_item_mentions : 대리키 id + UNIQUE(feed_item_id, mentioned_user_id) SELECT count(*) FROM feed_items fi JOIN highlights h ON h.feed_item_id = fi.id 이 절의 쿼리는 원시 JPQL이라 Spring Data count가 없다 -## 재현 조건 +## 컬렉션 수와 데이터 분포를 같은 조건으로 맞춘다 1. highlights와 mentions를 동시에 join fetch하는 JPQL로 createQuery를 호출하고 예외를 확인한다. 원인 체인을 클래스명 문자열로 펼쳐 MultipleBagFetchException 포함 여부를 본다. @@ -79,11 +79,11 @@ SELECT count(*) FROM feed_items fi JOIN highlights h ON h.feed_item_id = fi.id 5. 앞 단계에서 loadFeed를 재던 테스트를 다시 실행해 collectionFetches == N, 접근 0에서 == 0, pageFetch == N이 그대로 유지되는지 확인한다. -## 본문 +## Fetch Join을 늘렸을 때 실제로 생긴 두 문제 -## 실패 하나 — 컬렉션 둘을 동시에 fetch join하면 거부된다 +## 컬렉션 둘을 동시에 Fetch Join하면 MultipleBagFetchException이 발생한다 bag은 순서 컬럼(`@OrderColumn`)이 없는 `List` 매핑이다. `highlights`와 `mentions`가 둘 다 bag인 상태에서 연관을 전부 한 쿼리에 합쳐 보았다. @@ -103,7 +103,7 @@ java.lang.IllegalArgumentException <- org.hibernate.loader.MultipleBagFetchExcep `MultipleBagFetchException`은 `IllegalArgumentException`으로 감싸져 나왔다. 테스트를 `hasCauseInstanceOf`에만 맞추면 래핑 계층이나 버전 차이에 취약해서, 원인 체인을 클래스명 문자열로 펼친 뒤 문자열 포함으로 확인했다. -## 실패 둘 — 컬렉션 하나만 합치면 전송 행수가 늘어난다 +## 컬렉션 하나만 Fetch Join해도 조인 행 수가 늘어난다 컬렉션을 `highlights` 하나만 fetch join하면 예외는 나지 않는다. 대신 `feed_items`와 `highlights`의 조인이 부모 한 행을 자식 수만큼 반복해 내보내므로, 쿼리 수가 아니라 DB가 애플리케이션에 전달한 조인 행수를 쟀다. @@ -148,7 +148,7 @@ Execution Time: 0.959 ms 추정 `rows=4202`와 실제 `rows=1961`의 오차는 대량 시드 직후 `ANALYZE`를 실행하지 않아 생긴 통계 문제다. -## 측정 정정 — 리스트 크기는 N이었다 +## 리스트 크기와 조인 결과 행 수를 구분해서 다시 측정했다 처음에는 `distinct` 없이 받은 결과 리스트 크기가 전송 행수와 같을 것으로 예상했지만, 실제 리스트 크기는 N이었다. Hibernate 6 이상이 fetch join의 루트 엔티티를 자동으로 중복 제거하기 때문이다. diff --git a/docs/n+1liner/tech-log-studio/jpa-feed-query-performance/case/case-projection-row-over-fetch.md b/docs/n+1liner/tech-log-studio/jpa-feed-query-performance/case/case-projection-row-over-fetch.md index 378cf6d..839a25c 100644 --- a/docs/n+1liner/tech-log-studio/jpa-feed-query-performance/case/case-projection-row-over-fetch.md +++ b/docs/n+1liner/tech-log-studio/jpa-feed-query-performance/case/case-projection-row-over-fetch.md @@ -24,7 +24,7 @@ source: DTO 프로젝션으로 하이드레이트한 엔티티가 1,569개에서 0개로 줄고 쿼리도 2개로 고정됐다. 그런데 자식 IN 쿼리는 페이지 부모 20개의 하이라이트를 전부 가져와 1,509행이었다. 화면에 필요한 것은 부모당 최신 3개, 최대 60행이었다. -## 관계 +## Projection으로 엔티티 로드를 줄인 뒤 남은 비용을 확인했다 - **화면 조회는 Read Projection을 사용한다** 이 관측에서 나온 결정이다. @@ -33,13 +33,13 @@ DTO 프로젝션으로 하이드레이트한 엔티티가 1,569개에서 0개로 - **Fetch Join · Batch · Projection 선택 기준** 왕복과 적재를 각각 어느 전략이 푸는지 정리한 기록이다. -## 문제 +## 쿼리는 2개가 됐지만 1,509행을 읽었다 배치로 왕복 수와 페이징 문제를 풀었지만 엔티티는 여전히 통째로 하이드레이트했다. seed 1,000의 첫 페이지 20건에서 FeedItem·User·Page·Highlight를 합해 1,569개가 영속 객체로 올라왔다. 화면에는 일부 컬럼만 필요했으므로, 적재 대상을 줄이려고 필요한 스칼라 값만 조회하는 프로젝션을 추가했다. -## 결론 +## Projection은 엔티티 로드와 Row Volume을 같은 방식으로 줄이지 않는다 프로젝션은 하이드레이트한 엔티티를 0개로 만들었다. SELECT new 캐리어는 영속 엔티티 대신 스칼라 값으로 record를 만들므로 1차 캐시·더티체킹·지연 프록시도 생기지 않는다. join도 컬럼을 읽기 위한 경로일 뿐 엔티티를 만들지 않는다. @@ -49,7 +49,7 @@ DTO 프로젝션으로 하이드레이트한 엔티티가 1,569개에서 0개로 필요한 컬럼만 선택하면 EXPLAIN의 width도 줄어들 것으로 예상했지만 부모 프로젝션의 width는 2088로 엔티티 조회의 1194보다 컸다. users와 pages 조인의 행폭이 반영되고, PostgreSQL의 width가 실제 전송 바이트가 아니라 컬럼 타입의 평균폭 추정치이기 때문이다. -## 검증 환경 +## Projection을 측정한 데이터와 실행 조건 Java 21 Spring Boot 4.0.0 @@ -65,7 +65,7 @@ entitiesLoaded : Statistics.getEntityLoadCount() prepared : Statistics.getPrepareStatementCount() collectionFetch : Statistics.getCollectionFetchCount() -## 재현 조건 +## 같은 행 수와 쿼리 수를 다시 확인하는 조건 1. 부모 스칼라 프로젝션과 자식 IN 스칼라 프로젝션 두 쿼리로 loadFeedProjection을 구현한다. @@ -79,7 +79,7 @@ collectionFetch : Statistics.getCollectionFetchCount() 6. 부모 프로젝션과 엔티티 페이징의 EXPLAIN width를 비교한다. -## 본문 +## 두 Scalar Projection이 실제로 읽은 데이터 @@ -117,7 +117,7 @@ FeedSummary의 마지막 인자가 리스트라 생성자 표현식 한 번으 처음 구현한 loadFeed의 쿼리 수는 N에 비례해 늘었고 배치는 배치 크기 단위로 늘었다. 프로젝션은 2개로 유지되었다. -## 남은 비용 — 페이지당 전량 +## Projection 이후에도 페이지 자식 행은 전부 읽었다 ![페이지 부모에서 자식 IN 조회를 거쳐 자식 행 전량이 나오고, 화면이 그중 부모별 최신 몇 개만 쓰는 흐름. IN 조회 상자에는 엔티티 적재가 없다는 표시가 붙어 있다.](../../../final/assets/diagrams/projection-row-over-fetch/projection-row-over-fetch.svg) diff --git a/docs/n+1liner/tech-log-studio/jpa-feed-query-performance/case/case-visibility-or-breaks-keyset-index.md b/docs/n+1liner/tech-log-studio/jpa-feed-query-performance/case/case-visibility-or-breaks-keyset-index.md index 60ab3e8..30ec80f 100644 --- a/docs/n+1liner/tech-log-studio/jpa-feed-query-performance/case/case-visibility-or-breaks-keyset-index.md +++ b/docs/n+1liner/tech-log-studio/jpa-feed-query-performance/case/case-visibility-or-breaks-keyset-index.md @@ -22,7 +22,7 @@ source: keyset 페이징은 정렬키 인덱스로 커서 이후 20행만 읽었다. 여기에 가시성 세 분기를 OR로 얹자 플래너가 그 인덱스를 쓰지 못하고 BitmapOr로 떨어졌고, 사라졌던 Sort 노드가 다시 나타났다. -## 관계 +## Keyset 조건에 Visibility OR을 추가했다 - **Feed Visibility Query Pattern** 가시성 세 분기를 단일 OR, UNION 분해, 사전계산으로 처리했을 때 실행계획이 어떻게 갈리는지 정리했다. @@ -31,13 +31,13 @@ keyset 페이징은 정렬키 인덱스로 커서 이후 20행만 읽었다. 여 - **feed_visible을 Production CQRS로 승격할 것인가** 사전계산을 프로덕션에서 상시 유지할지는 아직 답하지 않았다. -## 문제 +## 가시성 OR 이후 정렬 인덱스를 그대로 활용하지 못했다 keyset 페이징으로 페이지 깊이 문제를 풀었다. 깊은 페이지에서 OFFSET은 2,000행을 훑고 20행만 남겼지만 keyset은 Index Only Scan으로 20행만 읽었고 buffers는 1이었다. 실서비스 피드는 조회하는 사용자마다 보이는 아이템이 다르다. 이 가시성은 public 아이템, 내가 멘션된 아이템, 내 비공개 아이템 세 분기로 갈린다. 세 분기를 keyset과 같은 쿼리에 얹었다. -## 결론 +## 가시성 조건과 Keyset 정렬을 한 쿼리에 넣을 때 Plan을 다시 확인한다 가시성 조건을 추가하자 플래너는 정렬키 인덱스 ix_feed_items_keyset을 더 이상 쓰지 못했다. 세 분기를 각각 인덱스로 스캔한 뒤 BitmapOr로 합쳤고, 그 과정에서 인덱스가 주던 정렬 순서를 잃어 Sort 노드가 다시 나타났다. @@ -45,7 +45,7 @@ keyset 페이징으로 페이지 깊이 문제를 풀었다. 깊은 페이지에 멘션 조건의 EXISTS는 hashed SubPlan으로 처리됐다. keyset 문법만으로 비용이 줄어든 것이 아니라 커서와 같은 순서의 정렬키 인덱스가 있어야 했는데, 가시성 OR이 그 전제를 깨뜨렸다. -## 검증 환경 +## Visibility Query Plan을 측정한 환경 Java 21 Spring Boot 4.0.0 @@ -62,7 +62,7 @@ ix_feed_items_visibility_sort : (visibility, first_highlighted_at DESC, id) 시드 : seed 2,000 -## 재현 조건 +## OR 전후 Plan을 같은 데이터에서 비교한다 1. 정렬키 전용 인덱스를 만들고 keyset 쿼리가 Index Only Scan으로 20행만 읽는 것을 확인한다. @@ -72,11 +72,11 @@ ix_feed_items_visibility_sort : (visibility, first_highlighted_at DESC, id) 4. 깊은 페이지에서 OFFSET과 keyset의 훑은 행을 대조한다. 훑은 행은 Limit 하위의 actual rows로 계산한다. -## 본문 +## Visibility 조건 전후의 실행계획 -## 가시성을 얹기 전 — 커서 이후 20행만 읽기 +## Visibility 조건 전에는 Cursor 이후 20행만 읽었다 seed 2,000에서 100번째 페이지(offset 1980)를 요청하고 두 방식의 실행계획을 대조했다. @@ -132,7 +132,7 @@ SELECT fi.id, fi.first_highlighted_at FROM feed_items fi keyset이 `Index Only Scan`으로 성립하려면 정렬키·커서·인덱스의 컬럼과 방향이 모두 일치해야 한다. `first_highlighted_at`이 같은 행까지 안정적으로 넘기려면 커서에 `id`를 함께 넣어야 하고, 시각만 커서로 쓰면 경계에서 행이 빠지거나 중복될 수 있다. 가시성 OR은 이 일치를 깨뜨린다. -## 다음 단계 — UNION 분해와 사전계산 +## UNION 분해와 사전계산을 같은 결과로 비교한다 세 분기를 `UNION ALL`로 나눠 각각 정렬 스트림으로 만든 뒤 병합하는 방식과, 조회 사용자별 가시성을 미리 계산해 두는 방식을 비교했다. 처음에는 단일 OR이 `Seq Scan`으로 떨어지고 `UNION` 분해가 읽는 블록을 줄일 것으로 예상했다. diff --git a/docs/n+1liner/tech-log-studio/jpa-feed-query-performance/decision/decision-batch-fetch-for-entity-graph.md b/docs/n+1liner/tech-log-studio/jpa-feed-query-performance/decision/decision-batch-fetch-for-entity-graph.md index ae51656..0bc05b2 100644 --- a/docs/n+1liner/tech-log-studio/jpa-feed-query-performance/decision/decision-batch-fetch-for-entity-graph.md +++ b/docs/n+1liner/tech-log-studio/jpa-feed-query-performance/decision/decision-batch-fetch-for-entity-graph.md @@ -19,7 +19,7 @@ source: 엔티티를 그래프로 조회해야 하는 경로에서는 컬렉션을 fetch join하지 않고 배치 페치를 쓴다. 엔티티만 페이징해 DB가 LIMIT을 발행하게 하고, 지연 연관은 부모 키를 모아 IN으로 채운다. -## 근거 +## Collection Fetch Join은 Pagination과 충돌했다 - **Fetch Join · Batch · Projection 선택 기준** fetch join · 배치 · 프로젝션을 각각 어느 조회에 쓸지 나눠 둔 기록이다. @@ -28,13 +28,13 @@ source: - **Projection 이후에도 1,509행을 읽은 Row Over-fetch** 배치를 적용해도 엔티티가 통째로 올라온다는 것을 확인한 기록이다. -## 결정문 +## 엔티티 그래프 조회의 컬렉션은 Batch Fetch로 묶는다 엔티티 그래프가 필요한 조회에서는 컬렉션을 fetch join하지 않고 hibernate.default_batch_fetch_size를 설정해 지연 연관을 IN으로 묶는다. 이 설정은 세션 전체에 걸리므로 적용 범위를 함께 정한다. 앞서 잰 값을 그대로 두려면 새 테스트 클래스처럼 격리된 범위에만 건다. -## 판단 이유 +## 부모 Pagination을 유지하면서 컬렉션 N+1을 줄일 수 있다 fetch join은 부모와 자식을 한 결과에 합쳐 행을 곱했기 때문에 DB가 부모를 기준으로 LIMIT을 적용할 수 없었다. 배치는 부모만 먼저 페이징하고 자식은 부모 키를 모아 IN으로 따로 가져오므로, 컬렉션 N+1과 페이징이 한꺼번에 풀린다. @@ -46,7 +46,7 @@ N=1,000에서 총 PreparedStatement가 2,022개에서 23개로 줄었다. 초기 엔티티만 페이징한 SQL의 실행계획에는 Limit 노드가 붙었고, 자식 IN 조회는 부모와 자식을 곱하지 않는 준조인으로 나타났다. 앞 단계에서 본 카테시안 곱과 인메모리 페이징이 여기서는 나타나지 않았다. -## 영향 +## Batch Size 적용 범위와 Hibernate 통계 해석을 함께 본다 - 배치를 적용하면 getCollectionFetchCount()가 초기화된 컬렉션 수가 아니라 여러 컬렉션을 함께 채운 fetch SELECT 연산 수를 센다. 처음에는 이 값을 초기화된 컬렉션 수로만 보고 배치를 걸어도 N으로 유지될 것이라고 예상했지만 10 / 100 / 1,000에서 1 / 1 / 10으로 줄었고, 그 결과에 맞춰 지표를 다시 해석했다. 배치가 걸렸는지는 PreparedStatement 수와 이 값을 함께 보고 판단한다. - default_batch_fetch_size는 세션 전체에 걸린다. 앞서 loadFeed로 잰 값과 그대로 비교하려면 새 IT 클래스처럼 격리된 범위에만 걸어야 한다. diff --git a/docs/n+1liner/tech-log-studio/jpa-feed-query-performance/decision/decision-keep-read-model-as-cqrs-lite.md b/docs/n+1liner/tech-log-studio/jpa-feed-query-performance/decision/decision-keep-read-model-as-cqrs-lite.md index bab7c18..1db95df 100644 --- a/docs/n+1liner/tech-log-studio/jpa-feed-query-performance/decision/decision-keep-read-model-as-cqrs-lite.md +++ b/docs/n+1liner/tech-log-studio/jpa-feed-query-performance/decision/decision-keep-read-model-as-cqrs-lite.md @@ -17,9 +17,9 @@ source: # 현재 Read Model은 CQRS-lite로 유지한다 -CQRS(Command Query Responsibility Segregation, 명령과 조회의 책임 분리)는 쓰기 모델과 읽기 모델을 갈라 두는 설계다. 여기서는 그중 모델만 갈라, 읽기 경로를 쓰기 애그리거트인 FeedItem에서 떼어 내되 저장소는 나누지 않는다. 읽기 전용 조회 포트(FeedReadModelQueryPort)와 읽기 DTO, 읽기 최적 쿼리를 쓰기와 같은 저장소 위에 두고, 별도 물리 읽기 저장소는 에스컬레이션 대상으로 남긴다. +CQRS(Command Query Responsibility Segregation, 명령과 조회의 책임 분리)는 쓰기 모델과 읽기 모델을 분리하는 설계다. 현재는 읽기 경로만 쓰기 애그리거트인 FeedItem에서 분리하고 저장소는 그대로 공유한다. `FeedReadModelQueryPort`와 읽기 DTO, 읽기 전용 쿼리를 같은 데이터베이스 위에 두며 별도 물리 읽기 저장소는 아직 사용하지 않는다. -## 근거 +## 화면 조회를 쓰기 Aggregate에 맡기면서 N+1이 생겼다 - **feed_visible을 Production CQRS로 승격할 것인가** 사용자별 가시성을 미리 계산한 테이블을 상시 유지할지, 그래서 저장소까지 나눌지를 아직 답하지 않았다. @@ -28,13 +28,13 @@ CQRS(Command Query Responsibility Segregation, 명령과 조회의 책임 분리 - **Feed Visibility Query Pattern** 공개·멘션·비공개 세 분기를 단일 OR, UNION 분해, 사전계산으로 비교했다. 사전계산을 상시 유지하면 그때부터 읽기 모델 설계가 된다. -## 결정문 +## 읽기 모델은 분리하되 저장소는 아직 나누지 않는다 읽기 경로는 읽기 전용 조회 포트(FeedReadModelQueryPort)와 유스케이스(GetFeedReadModelUseCase), 어댑터(FeedReadModelQueryAdapter)로 분리한다. 읽기 최적 쿼리는 요청 시점에 실행하고 별도 물리 저장소를 두지 않는다. 사전계산 테이블(feed_visible)을 상시 유지하는 구조는 현재 계약의 범위를 넘는 것으로 보고 채택하지 않는다. -## 판단 이유 +## 조회 모델 분리 효과를 먼저 얻고 Projection 동기화 비용은 미룬다 쓰기 애그리거트인 FeedItem으로 화면 조회까지 하려던 데서 N+1이 나왔다. @@ -48,7 +48,7 @@ CQRS(Command Query Responsibility Segregation, 명령과 조회의 책임 분리 발행 쿼리 수는 Hibernate Statistics가 센 값이다. 이 지표에 window 쿼리가 잡히도록 그 쿼리는 JdbcTemplate 대신 Hibernate Session으로 실행했다. -## 영향 +## 가시성 계산은 요청 시점에 계속 수행한다 - 조회 요청마다 읽기 최적 쿼리를 실행한다. 결과를 미리 펼쳐 두는 사전계산과 달리 조회 계산이 매 요청에 들어간다. - 가시성은 공개·멘션·비공개 세 분기라 요청 시점에 셋을 다시 판정한다. 단일 OR은 후보 1,500개를 훑어 buffers가 122였고, 뷰어별로 미리 펼친 feed_visible은 1이었다. diff --git a/docs/n+1liner/tech-log-studio/jpa-feed-query-performance/decision/decision-keyset-for-feed-pagination.md b/docs/n+1liner/tech-log-studio/jpa-feed-query-performance/decision/decision-keyset-for-feed-pagination.md index 588cf0f..6201ebd 100644 --- a/docs/n+1liner/tech-log-studio/jpa-feed-query-performance/decision/decision-keyset-for-feed-pagination.md +++ b/docs/n+1liner/tech-log-studio/jpa-feed-query-performance/decision/decision-keyset-for-feed-pagination.md @@ -19,7 +19,7 @@ source: 피드 목록의 페이징은 OFFSET이 아니라 이전 페이지의 마지막 정렬키를 커서로 넘기는 keyset 방식을 쓴다. 정렬키와 같은 컬럼, 같은 방향의 인덱스를 함께 둔다. -## 근거 +## OFFSET은 페이지가 깊어질수록 버리는 행이 늘었다 - **Keyset Pagination 설계 기준** 커서에 정렬키를 모두 담고 정렬키·커서·인덱스의 컬럼과 방향을 맞추라는 규칙을 여기서 가져왔다. @@ -28,13 +28,13 @@ source: - **Highlight 없는 FeedItem을 허용할 것인가** 정렬 시각이 null인 FeedItem을 허용할지 정하지 않아 커서 비교식이 경계에서 어떻게 동작하는지도 정의되지 않았다. -## 결정문 +## 피드는 정렬 시각과 ID를 Cursor로 사용한다 피드 목록은 (정렬 시각, 식별자)를 커서로 삼아 그 지점 이후만 조회한다. 정렬키 전용 인덱스를 커서와 같은 컬럼, 같은 방향으로 둔다. 전체 페이지 수를 요구하지 않는 화면에서는 전체 건수를 세는 count 쿼리를 발행하지 않는다. -## 판단 이유 +## 이전 행을 다시 읽지 않고 Cursor 이후만 조회한다 OFFSET은 정렬 순서에서 앞의 행을 만든 뒤 버리기 때문에, 100번째 페이지에서는 결과 20행을 만들려고 2,000행을 읽었다. 무한 스크롤에서는 페이지를 넘길수록 읽고 버리는 행이 계속 늘어난다. @@ -44,7 +44,7 @@ keyset은 페이지가 깊어져도 읽은 행이 페이지 크기인 20행에 정렬 시각이 같은 행을 안정적으로 넘기려면 식별자까지 커서에 담아야 한다. 시각만 커서로 쓰면 경계에서 행이 빠지거나 중복될 수 있다. -## 영향 +## 임의 페이지 이동과 전체 페이지 수는 별도 비용이 필요하다 - 임의 페이지로 바로 건너뛸 수 없다. 앞뒤로 이어서 넘기는 탐색만 된다. - 전체 페이지 수를 화면에 표시하려면 전체 건수를 세는 count 쿼리를 따로 발행해야 한다. diff --git a/docs/n+1liner/tech-log-studio/jpa-feed-query-performance/decision/decision-measure-plan-on-real-postgresql.md b/docs/n+1liner/tech-log-studio/jpa-feed-query-performance/decision/decision-measure-plan-on-real-postgresql.md index 1d9fd14..054b792 100644 --- a/docs/n+1liner/tech-log-studio/jpa-feed-query-performance/decision/decision-measure-plan-on-real-postgresql.md +++ b/docs/n+1liner/tech-log-studio/jpa-feed-query-performance/decision/decision-measure-plan-on-real-postgresql.md @@ -19,7 +19,7 @@ source: 조회 성능 측정은 H2 같은 인메모리 DB가 아니라 운영과 같은 PostgreSQL에서 실행한다. -## 근거 +## 실행계획은 DB 엔진의 통계와 비용 모델에 따라 달라진다 - **PostgreSQL Query Plan 측정 기준** 이 결정을 실제로 잴 때 지킬 규칙으로 폈다. @@ -28,13 +28,13 @@ source: - **Visibility OR이 Keyset Index를 깨뜨린 문제** 부분 인덱스와 정렬 인덱스 기능에 기대어 측정했다. -## 결정문 +## Query Plan은 Testcontainers PostgreSQL에서 측정한다 퍼시스턴스 조회 측정은 Testcontainers로 띄운 실제 PostgreSQL에서 수행한다. H2 같은 인메모리 DB로는 실행계획이나 인덱스 동작을 판단하지 않는다. 스키마는 운영 마이그레이션인 Flyway V6__feed.sql을 그대로 적용하고, ddl-auto=validate로 엔티티가 기대하는 테이블·컬럼·타입의 기본 불일치를 조기에 잡는다. -## 판단 이유 +## 운영과 다른 엔진의 Plan으로 인덱스 선택을 판단하지 않는다 비용 기반 옵티마이저는 가능한 여러 계획의 비용을 추정해 가장 싼 것을 고른다. 그런데 그 추정값도, 애초에 고를 수 있는 선택지도 엔진마다 다르다. 갈리는 축은 넷이다. 비용 상수, ANALYZE가 모으는 통계, 저장 구조와 가시성 처리, 쓸 수 있는 인덱스 종류와 기능이 저마다 다르다. @@ -46,7 +46,7 @@ source: 부르는 지점도 골랐다. 퍼시스턴스 어댑터 FeedQueryAdapter를 JPA 슬라이스에서 직접 호출하고 HTTP는 거치지 않는다. 이유는 둘이다. N+1은 조회 계층의 현상이므로 웹·보안·직렬화 노이즈를 배제하고 쿼리 행동만 관찰한다. 그리고 슬라이스 트랜잭션이 열려 있어야 지연 로딩이 결정적으로 재현된다. -## 영향 +## 측정 환경에는 Container Runtime이 필요하다 - 측정을 돌리려면 컨테이너 런타임이 있어야 한다. @Testcontainers(disabledWithoutDocker = true)를 걸어 두어 Docker가 없는 환경에서는 이 테스트가 비활성화된다. - 인메모리 DB보다 기동과 실행이 느리다. 컨테이너 필드를 static으로 두어 테스트 메서드마다 새로 띄우지 않고 FeedPersistenceIT 실행 동안 하나를 공유한다. 첫 테스트 전에 한 번 기동하고 마지막 테스트가 끝나면 종료한다. diff --git a/docs/n+1liner/tech-log-studio/jpa-feed-query-performance/decision/decision-no-collection-fetch-join-with-pagination.md b/docs/n+1liner/tech-log-studio/jpa-feed-query-performance/decision/decision-no-collection-fetch-join-with-pagination.md index 726b24d..7907f9b 100644 --- a/docs/n+1liner/tech-log-studio/jpa-feed-query-performance/decision/decision-no-collection-fetch-join-with-pagination.md +++ b/docs/n+1liner/tech-log-studio/jpa-feed-query-performance/decision/decision-no-collection-fetch-join-with-pagination.md @@ -19,22 +19,22 @@ source: 컬렉션을 fetch join한 쿼리에 페이징을 걸지 않는다. Hibernate가 DB LIMIT을 빼고 결과셋 전체를 메모리에 올린 뒤 부모 기준으로 자르기 때문에, 반환 목록만 한 페이지일 뿐 메모리에 올라오는 부모 엔티티는 데이터셋 전체다. -## 근거 +## Collection Fetch Join에 Pagination을 붙이면 In-memory Paging이 발생했다 - **Collection Fetch Join Pagination의 In-memory Paging** - 발행 SQL에 Limit 노드가 없다는 것과 부모 엔티티 로드 수를 이 기록에서 함께 쟀다. + 발행 SQL에 Limit 노드가 없고 부모 엔티티가 페이지 크기보다 많이 로드되는 것을 함께 확인했다. - **Fetch Join으로 N+1을 해결하다 만난 MultiBag과 행 폭증** 부모 100행짜리 조인이 실제로는 1,961행을 실어 나른다는 것을 확인한 기록이다. - **Fetch Join · Batch · Projection 선택 기준** 컬렉션 fetch join을 버린 뒤 배치와 프로젝션 중 무엇을 쓸지 정한 기록이다. -## 결정문 +## 페이징 목록에서는 Collection Fetch Join을 사용하지 않는다 컬렉션을 fetch join하는 쿼리에 firstResult나 maxResults를 적용하지 않는다. 페이징이 필요한 목록 조회에서는 엔티티만 페이징해 DB LIMIT이 정상 발행되게 하고, 지연 연관은 배치나 별도 쿼리로 채운다. -## 판단 이유 +## DB LIMIT을 부모 단위로 적용하고 자식은 별도 조회로 채운다 컬렉션 fetch join에서는 부모 한 행이 자식 수만큼 늘어난다. 페이지 크기 20으로 DB LIMIT을 걸면 부모 20개가 아니라 조인 행 20개에서 잘리므로 일부 부모의 자식이 누락될 수 있다. @@ -46,7 +46,7 @@ N=1,000에서 반환 목록은 페이지 크기인 20에 머물렀지만 메모 문제의 쿼리는 FeedQueryAdapter가 아니라 통합 테스트 안의 원시 JPQL로만 실행했고, 늘어난 코드는 그 테스트의 측정 메서드뿐이다. -## 영향 +## 컬렉션 조회는 Batch Fetch나 별도 Query가 맡는다 - 컬렉션을 한 번에 가져오는 편의를 포기한다. 자식은 쿼리를 따로 내서 채워야 한다. - 엔티티만 페이징하면 highlights가 다시 지연 로딩이 되어 컬렉션 N+1이 돌아오므로, 페이지 부모 키를 모아 한 번에 조회하는 배치나 프로젝션을 함께 적용해야 한다. diff --git a/docs/n+1liner/tech-log-studio/jpa-feed-query-performance/decision/decision-query-strategy-behind-port.md b/docs/n+1liner/tech-log-studio/jpa-feed-query-performance/decision/decision-query-strategy-behind-port.md index 935f53e..51d001e 100644 --- a/docs/n+1liner/tech-log-studio/jpa-feed-query-performance/decision/decision-query-strategy-behind-port.md +++ b/docs/n+1liner/tech-log-studio/jpa-feed-query-performance/decision/decision-query-strategy-behind-port.md @@ -18,7 +18,7 @@ source: 조회 전략은 퍼시스턴스 어댑터 `FeedQueryAdapter`의 책임으로 둔다. 상위 계층에 드러내는 것은 조회 사용자·페이지 크기와 반환할 `FeedSummary`뿐이고, fetch join·배치 페치·DTO 프로젝션·윈도우 함수 중 무엇을 쓰는지는 `FeedQueryPort` 뒤에 감춘다. -## 근거 +## 조회 전략을 바꿀 때마다 SQL과 반환 구조가 함께 바뀌었다 - **Fetch Join · Batch · Projection 선택 기준** 여기서 비교한 세 전략을 모두 `FeedQueryAdapter` 안에서 갈아 끼웠다. @@ -27,13 +27,13 @@ source: - **화면 조회는 Read Projection을 사용한다** 화면 조회를 DTO 프로젝션으로 바꿀 때도 포트 뒤의 구현만 갈아 끼웠다. -## 결정문 +## Query Strategy 변경은 FeedQueryPort 뒤에서 끝낸다 조회 경로는 FeedController에서 GetFeedUseCase를 거쳐 FeedQueryPort로 이어지고, 퍼시스턴스 어댑터 FeedQueryAdapter가 그 포트를 구현한다. 조회 전략을 바꾸는 일은 이 어댑터 안에서 끝낸다. 쿼리 포트는 엔티티 타입을 노출하지 않는다. 컨트롤러는 엔티티를 의존하거나 반환하지 않는다. -## 판단 이유 +## UseCase와 Controller를 조회 구현 세부사항에서 분리한다 이 프로젝트에서 조회 전략을 여섯 번 바꿨다. 엔티티 매핑, fetch join, 배치 페치, DTO 프로젝션, 윈도우 함수와 LATERAL, 커서 페이징이고, 바꿀 때마다 발행되는 SQL 형태와 반환 구조가 달라졌다. @@ -43,7 +43,7 @@ FeedItemJpaEntity의 연관 게터를 public 대신 package-private로 좁힌 쿼리 포트가 엔티티 타입을 노출하지 않으면 어댑터 안에서 조회 방식을 바꿔도 상위 계층이 보는 계약은 바뀌지 않는다. -## 영향 +## Native SQL도 Persistence Adapter 안에만 남긴다 - 윈도우 함수와 LATERAL은 표준 JPQL(Java Persistence Query Language)로 표현되지 않아서 어댑터 안에 네이티브 SQL이 들어간다. 이 SQL은 포트 밖으로 나가지 않는다. - 화면 요구가 바뀌어 반환 형태가 달라지면 FeedQueryPort 계약까지 함께 바꿔야 한다. diff --git a/docs/n+1liner/tech-log-studio/jpa-feed-query-performance/decision/decision-read-projection-for-screen-query.md b/docs/n+1liner/tech-log-studio/jpa-feed-query-performance/decision/decision-read-projection-for-screen-query.md index 7a12841..d8af8c6 100644 --- a/docs/n+1liner/tech-log-studio/jpa-feed-query-performance/decision/decision-read-projection-for-screen-query.md +++ b/docs/n+1liner/tech-log-studio/jpa-feed-query-performance/decision/decision-read-projection-for-screen-query.md @@ -19,7 +19,7 @@ source: 화면에 내보내는 조회는 엔티티를 하이드레이트하지 않고 필요한 스칼라 값만 캐리어로 받는다. 엔티티 그래프 조회는 쓰기 경로에 남기고 읽기 경로는 프로젝션으로 분리한다. -## 근거 +## Batch Fetch 이후에도 화면에 필요 없는 엔티티까지 Hydration됐다 - **Projection 이후에도 1,509행을 읽은 Row Over-fetch** 하이드레이트한 엔티티는 0개가 됐지만 자식 IN 쿼리가 페이지 부모 20개의 하이라이트 1,509행을 모두 읽은 것을 확인한 기록이다. @@ -28,13 +28,13 @@ source: - **Query Strategy는 FeedQueryPort 뒤에서 소유한다** 프로젝션 구현을 퍼시스턴스 어댑터 안에 두고 상위 계층에는 조회 조건과 반환 형태만 드러낸 결정이다. -## 결정문 +## 화면 조회는 필요한 컬럼만 Projection으로 읽는다 화면 조회 경로에서는 필요한 컬럼만 선택해 캐리어 record로 받는다. 영속 엔티티를 만들지 않는다. 부모와 자식을 각각 스칼라로 조회하고 애플리케이션에서 조립한다. 이 구현은 FeedQueryPort 뒤에 둔다. -## 판단 이유 +## 영속 엔티티 생성 비용을 없애고 화면 데이터만 가져온다 배치를 적용한 뒤에도 엔티티는 통째로 하이드레이트됐다. seed 1,000의 첫 페이지 20건을 조회하자 FeedItem·User·Page·Highlight를 합해 1,569개가 영속 객체로 올라왔다. 화면에 필요한 것은 사용자 이름, 페이지 제목, URL 같은 일부 컬럼이었다. @@ -46,7 +46,7 @@ seed 1,000의 같은 첫 페이지 20건을 loadFeedProjection으로 조회하 배치는 SQL 왕복 횟수를 줄이고 프로젝션은 적재할 엔티티 수를 줄인다. 프로젝션이 엔티티를 만들지 않는 것은 배치 설정 여부와 관계없이 성립하는 동작이다. -## 영향 +## 화면 요구가 바뀌면 Projection Record와 Query도 함께 바뀐다 - 반환 형태가 화면 요구에 묶이므로, 화면이 바뀌면 캐리어 record와 그것을 채우는 두 쿼리도 함께 바뀐다. - FeedSummary의 마지막 인자가 HighlightSummary 목록이라 생성자 표현식 한 번으로는 만들 수 없었다. 목록을 담는 응답은 부모와 자식을 각각 스칼라로 조회한 뒤 feedItemId로 묶어 메모리에서 조립해야 한다. diff --git a/docs/n+1liner/tech-log-studio/jpa-feed-query-performance/question/question-cardinality-estimate-after-analyze.md b/docs/n+1liner/tech-log-studio/jpa-feed-query-performance/question/question-cardinality-estimate-after-analyze.md index c6f4673..cfeeb75 100644 --- a/docs/n+1liner/tech-log-studio/jpa-feed-query-performance/question/question-cardinality-estimate-after-analyze.md +++ b/docs/n+1liner/tech-log-studio/jpa-feed-query-performance/question/question-cardinality-estimate-after-analyze.md @@ -19,14 +19,14 @@ source: 플래너가 계획을 고르기 전에 조건에 걸리는 행이 몇 개일지 어림한 값이 추정 행수(cardinality estimate)이고, PostgreSQL은 `ANALYZE`로 컬럼 분포 통계를 모아 이 값을 낸다. 반복되는 하이라이트 조회의 실행계획에서는 추정 행수가 1이었는데 실제로는 500행이 나왔다. 대량 시드 직후 `ANALYZE`를 실행하지 않아 통계가 `feed_item_id`별 편중을 담지 못했다는 가설을 세웠지만 아직 검증하지 않았다. -## 관계 +## 추정 1행과 실제 500행의 차이를 다시 확인한다 - **PostgreSQL Query Plan 측정 기준** 추정 행수와 실제 행수가 벌어지면 통계를 갱신한 뒤 다시 재고 전후를 비교하라고 적어 두었다. - **Fetch 타입이 아니라 조회 방식이 만든 ToOne N+1** 이 실행계획을 `EXPLAIN`으로 확인하고 500배 차이를 처음 적었다. -## 사실 +## ANALYZE 전 실행계획은 500배를 잘못 추정했다 - 대량 시드 직후 잰 계획에서 추정 행수는 1인데 실제 행수는 500이었다. 500배 차이다. - 이 계획은 feed_item_id 조건을 ix_highlights_feed_items_created 인덱스로 처리했고(Index Scan) 실행시간은 0.173 ms였다. @@ -35,13 +35,13 @@ source: - fetch join 계획의 Hash Join 노드에서도 추정 rows=4202 에 실제 1,961로 어긋났다. - 대량 시드 직후 ANALYZE를 실행하지 않았다. -## 가정 +## 통계가 갱신되면 추정 행수와 플랜이 달라질 수 있다 - 통계를 갱신하면 feed_item_id별 분포가 반영되어 추정 행수가 실제에 가까워진다. - 추정 행수가 달라지면 플래너가 다른 계획을 고를 수 있다. - 편중이 큰 컬럼은 기본 통계 대상 수로 부족할 수 있다. -## 미지수 +## ANALYZE 후 rows와 scan 방식이 어떻게 바뀌는가 - ANALYZE highlights를 실행하고 같은 조회를 다시 EXPLAIN하면 추정 행수가 1에서 얼마로 바뀌는가. - 추정 행수가 바뀌면 Index Scan이 Seq Scan으로, 또는 그 반대로 뒤집히는가. @@ -50,12 +50,12 @@ source: - 통계를 갱신하면 지금까지의 결론 중 무엇이 바뀌는가. 왕복 수와 전송 행수에 관한 판단은 통계와 무관하다. - 운영에서 대량 적재 뒤 ANALYZE를 절차에 넣을 것인가. -## 제약 +## 전후 비교는 같은 데이터와 비슷한 캐시 조건에서 한다 - 통계 갱신 전후를 비교하려면 같은 데이터에서 연속으로 재야 한다. 캐시 상태가 섞이면 읽은 블록 수를 나란히 놓을 수 없다. - 지금까지 기록한 실행계획은 모두 ANALYZE 전 값이다. 갱신 후 값과 섞이지 않도록 ANALYZE 전을 Plan A, 후를 Plan B로 나눠 적는다. -## 선택지 +## ANALYZE만 할지 statistics target까지 조정할지 ### 1. 통계를 갱신하고 전후를 비교한다 @@ -73,7 +73,7 @@ highlights.feed_item_id의 통계 대상 수를 늘린 뒤 다시 잰다. 기본 플래너가 다른 계획을 고르는지는 확인하지 못한다. -## 다음 검증 +## ANALYZE 전후 EXPLAIN을 같은 조건에서 비교한다 1. 대량 시드 직후 계획을 다시 기록한다. ANALYZE 전 값이므로 Plan A로 적는다. diff --git a/docs/n+1liner/tech-log-studio/jpa-feed-query-performance/question/question-concurrency-stability.md b/docs/n+1liner/tech-log-studio/jpa-feed-query-performance/question/question-concurrency-stability.md index b68bf06..23c6d57 100644 --- a/docs/n+1liner/tech-log-studio/jpa-feed-query-performance/question/question-concurrency-stability.md +++ b/docs/n+1liner/tech-log-studio/jpa-feed-query-performance/question/question-concurrency-stability.md @@ -19,14 +19,14 @@ source: 지금까지의 측정은 단일 스레드 퍼시스턴스 통합 테스트에서 아이템 수 N을 키울 때 쿼리 수와 읽는 행수가 얼마나 늘어나는지만 확인했다. 여러 요청이 겹칠 때의 처리량과 커넥션 풀 안정성은 이 테스트가 재지 않았으므로, 조회 구조가 실제 부하를 견디는지는 아직 모른다. -## 관계 +## 지금까지의 성능 값은 단일 스레드에서 측정했다 - **PostgreSQL Query Plan 측정 기준** 무엇을 어디까지 재고 어떤 도구로 잴지 그 기록에서 정했다. - **feed_visible을 Production CQRS로 승격할 것인가** 고트래픽 읽기에서 사전계산이 실제로 필요한지는 부하 결과를 봐야 정할 수 있다. -## 사실 +## 현재 지연 값이 유효한 범위 - 측정은 단일 스레드에서 이미 열린 테스트 트랜잭션 안의 어댑터 호출만 쟀고, HTTP 종단은 거치지 않았다. - 지연 값은 DB 캐시가 이미 채워진 상태에서 잰 로컬 비교값이고, 7회 반복 중 앞 2회를 워밍업으로 버린 5개가 표본이다. @@ -37,13 +37,13 @@ source: - 고트래픽 처리량과 커넥션 풀 안정성, 동시성은 이 측정의 범위 밖이라고 문서 첫머리에 적어 두었다. - 커넥션 풀과 Little's Law는 이번 조회 문제를 해결한 뒤 별도 주제로 검증할 수 있다고 다음 단계에 함께 적어 두었다. -## 가정 +## 왕복 감소가 동시 부하에서도 처리량 이점으로 이어질 수 있다 - 왕복 수가 줄면 같은 트래픽에서 DB 부하도 줄어든다. - 요청마다 반복되는 왕복이 처리량에 곱해지므로, 왕복이 줄면 처리량 한계도 올라간다. - 단일 스레드에서 잰 요청당 쿼리 수와 읽는 행수는 여러 요청이 동시에 돌아도 달라지지 않는다. -## 미지수 +## 커넥션 풀과 p99는 어디에서 포화되는가 - 목표 처리량에서 커넥션 풀이 포화되는가. 포화되지 않으려면 풀을 몇 개로 잡아야 하고 요청은 얼마나 기다리는가. - 요청이 동시에 몰릴 때 지연이 어느 구간에 몰리는가. 꼬리 지연은 어디까지 벌어지는가. @@ -52,13 +52,13 @@ source: - DB 캐시가 비어 있거나 ANALYZE를 돌리지 않아 통계가 낡은 상태에서 실행계획이 달라지는가. - 운영 알람의 기준으로 어느 지표를 삼을 것인가. -## 제약 +## 단일 스레드 결과로 동시 트래픽을 설명할 수 없다 - 단일 스레드에서 잰 값으로는 동시 실행을 말할 수 없어서, 부하 테스트와 APM(Application Performance Monitoring, 애플리케이션 성능 모니터링)으로 도구를 바꿔야 한다. - 안정적인 꼬리 지연(p99)을 말하려면 워밍업 뒤 100회 넘게 반복한 독립 세트가 여러 개 있어야 한다. - 부하 테스트 환경의 데이터 규모와 하드웨어를 운영에 맞추지 않으면 거기서 나온 결과를 운영으로 그대로 옮길 수 없다. -## 선택지 +## HTTP 부하 테스트와 APM을 어디까지 붙일지 ### 1. 부하 테스트와 APM으로 확인한다 @@ -74,7 +74,7 @@ source: 운영에 올린 뒤에야 문제를 발견할 수 있다. -## 다음 검증 +## 목표 처리량과 허용 지연을 정하고 부하를 건다 1. 목표 처리량과 허용 지연을 먼저 정한다. 이 두 값이 없으면 부하 결과가 통과인지 실패인지 판정할 수 없다. diff --git a/docs/n+1liner/tech-log-studio/jpa-feed-query-performance/question/question-isolate-round-trip-and-row-volume.md b/docs/n+1liner/tech-log-studio/jpa-feed-query-performance/question/question-isolate-round-trip-and-row-volume.md index 0c3b786..e89fe46 100644 --- a/docs/n+1liner/tech-log-studio/jpa-feed-query-performance/question/question-isolate-round-trip-and-row-volume.md +++ b/docs/n+1liner/tech-log-studio/jpa-feed-query-performance/question/question-isolate-round-trip-and-row-volume.md @@ -19,14 +19,14 @@ source: 현재 데이터셋은 N을 키우면 반환 FeedItem 수, Highlight 총 행수, 엔티티 생성량, DB 왕복이 한꺼번에 늘어나서 지연이 늘어난 원인을 넷 중 어느 하나에 돌릴 수 없다. 변수를 하나씩 격리한 데이터셋을 만들지는 아직 정하지 않았다. -## 관계 +## 현재 데이터에서는 왕복 수와 전송 행수가 함께 바뀐다 - **JPA N+1 정량 진단 기준** 왕복 수와 전송 행수를 서로 다른 축으로 나눠 센다. - **Fetch 타입이 아니라 조회 방식이 만든 ToOne N+1** 같은 조회에서 왕복 수와 한 번에 읽어 오는 행수를 함께 확인한다. -## 사실 +## Highlight 분포는 FeedItem 수에 비례하지 않는다 - 하이라이트 개수는 순위 기반 편중 분포로 생성된다. 상한 500, 하한 1이다. - 하이라이트 총량은 N에 정비례하지 않는다. N=10에서 이미 1,285개이고 그중 500개가 첫 아이템 하나에서 나오며, N을 100배인 1,000으로 키워도 2,917개에 그친다. @@ -35,13 +35,13 @@ source: - 지연은 단일 스레드에서 7회 반복하고 앞 2회를 워밍업으로 버린 뒤 남은 5개 표본의 중앙값과 최댓값으로 기록했다. - 격리 데이터셋 세 종류를 계획했지만 아직 실행하지 않았다. -## 가정 +## 데이터셋을 나누면 두 비용을 따로 측정할 수 있다 - 왕복 수와 전송 행수는 지연을 서로 다른 방식으로 늘린다. - FeedItem 수만 바꾸고 FeedItem마다 Highlight를 1개로 고정하면 왕복이 지연에 얼마나 붙는지 따로 잴 수 있다. - FeedItem 수를 고정하고 Highlight 수만 바꾸면 한 번에 읽어 오는 행수가 지연을 얼마나 늘리는지 따로 볼 수 있다. -## 미지수 +## 왕복과 행수가 각각 지연에 얼마나 영향을 주는가 - 격리 데이터셋을 추가로 유지할 가치가 있는가. 시더와 테스트가 늘어난다. - FeedItem 수만 바꾼 데이터셋에서 지연이 왕복 수에 선형으로 붙는가. @@ -49,13 +49,13 @@ source: - 왕복과 행수를 갈라 재도 전략 선택이 달라지는가. 이미 배치로 왕복을 2,022개에서 23개로, 프로젝션으로 엔티티 로드를 1,569개에서 0개로 줄였다. - 편중 분포를 유지한 데이터셋과 격리 데이터셋을 모두 유지할 것인가, 격리 데이터셋으로 대체할 것인가. -## 제약 +## 현재 측정은 상대 비교에만 사용할 수 있다 - 현재 지연 값은 단일 스레드에서 같은 JVM으로, DB 캐시가 데워진 상태에서 잰 상대값이라 절대값 비교에 쓸 수 없다. 격리 데이터셋을 만들어도 측정 조건이 같아서 이 값으로는 여전히 N에 따른 증가 방향만 말할 수 있다. - 시더가 복잡해지면 지금까지 잰 값을 다시 재현하지 못할 수 있다. 기존 데이터셋은 그대로 두고 새 데이터셋을 더한다. - 편중 분포는 실제 라이너 데이터와 같다고 주장하려고 만든 것이 아니라 일부 페이지에 하이라이트가 매우 많을 수 있다는 조건을 통제된 방식으로 재현하려고 만든 합성 분포다. 하이라이트 개수를 균일하게 두면 한 아이템에 수백 개가 몰려서 생기는 전송량과 메모리 압박도, 아이템마다 최신 3개를 뽑아야 하는 필요도 데이터셋에서 사라진다. -## 선택지 +## 격리 데이터셋을 별도로 유지할지 ### 1. 세 데이터셋을 모두 만든다 @@ -75,7 +75,7 @@ FeedItem 수만 바꾼 것, Highlight 수만 바꾼 것, 편중 분포를 유지 측정할 때마다 시더를 다시 맞춰야 해서 같은 값을 다시 얻기 어렵다. -## 다음 검증 +## FeedItem 수와 Highlight 수를 따로 바꿔 측정한다 1. FeedItem을 10 / 100 / 1,000으로 바꾸고 FeedItem마다 Highlight를 정확히 1개씩 두는 데이터셋을 만든다. diff --git a/docs/n+1liner/tech-log-studio/jpa-feed-query-performance/question/question-nullable-first-highlighted-at.md b/docs/n+1liner/tech-log-studio/jpa-feed-query-performance/question/question-nullable-first-highlighted-at.md index d352f8c..c8e9677 100644 --- a/docs/n+1liner/tech-log-studio/jpa-feed-query-performance/question/question-nullable-first-highlighted-at.md +++ b/docs/n+1liner/tech-log-studio/jpa-feed-query-performance/question/question-nullable-first-highlighted-at.md @@ -19,14 +19,14 @@ source: 정렬키 first_highlighted_at은 지금 null을 허용한다. 하이라이트가 하나도 없는 FeedItem이 스키마 위에서는 존재할 수 있다는 뜻이다. FeedSeedFixture.seed(N)이 하이라이트가 만든 FeedItem만 넣다 보니 지금까지 쓴 데이터셋에는 이 컬럼이 빈 행이 없었다. 허용할지 말지를 정하기 전에는 정렬에서 그 행을 어디에 둘지도, 커서 비교식에 무엇을 담을지도 정할 수 없다. -## 관계 +## Keyset 정렬키가 nullable인 상태다 - **Keyset Pagination 설계 기준** 정렬키에 null이 섞이면 여기서 세운 커서 설계가 그대로 성립하지 않는다. - **Visibility OR이 Keyset Index를 깨뜨린 문제** - 거기서 플래너가 쓰지 못한 인덱스가 이 질문의 정렬키 인덱스와 같은 ix_feed_items_keyset이다. + Visibility OR 실험에서 활용되지 못한 인덱스가 현재 Keyset 정렬에 사용하는 `ix_feed_items_keyset`과 같다. -## 사실 +## 현재 fixture에서는 null이 만들어지지 않는다 - first_highlighted_at은 timestamptz이고 null을 허용한다. NOT NULL 제약이 붙어 있지 않다. - FeedSeedFixture.seed(N)은 하이라이트가 만든 FeedItem만 생성하므로 이 컬럼을 항상 채운다. 그래서 지금까지의 측정에서는 null이 나타나지 않았다. @@ -34,13 +34,13 @@ source: - keyset 커서는 (first_highlighted_at, id)를 비교식에 담는다. 시각이 같은 행도 안정적으로 넘기려고 id까지 함께 넣었다. - 정렬키 전용 인덱스 ix_feed_items_keyset은 (first_highlighted_at DESC, id DESC)로 만들었다. -## 가정 +## null이 실제 데이터에 들어오면 커서 경계가 달라질 수 있다 - 하이라이트가 하나도 없는 FeedItem이 실제로 만들어지는 경로가 도메인에 있을 수 있다. - null이 섞이면 커서 비교식이 경계에서 행을 빠뜨리거나 중복시킬 수 있다. - 정렬 위치를 정하지 않으면 페이지를 넘길 때 순서가 흔들릴 수 있다. -## 미지수 +## Highlight 없는 FeedItem을 허용할 것인가 - 하이라이트 없는 FeedItem을 만드는 경로가 도메인에 있는가. 있다면 FeedItem을 만드는 코드 중 어느 것인가. - 스키마를 NOT NULL로 좁히는가, null을 허용하고 정렬 위치를 정하는가. @@ -49,13 +49,13 @@ source: - 부분 인덱스 조건을 쓰면 null 행이 인덱스에서 빠지는데, 그 행은 어느 쿼리로 읽는가. - FeedItem을 만든 시각과 첫 하이라이트가 생긴 시각이 다를 수 있는가. -## 제약 +## 스키마와 커서 비교식, 인덱스를 함께 결정해야 한다 - 커서 비교식과 정렬키 인덱스 정의가 이 결정에 달려 있어서, keyset 페이징을 프로덕션에 반영하기 전에 정해야 한다. - 스키마를 NOT NULL로 좁히려면 기존 데이터에 null이 하나도 없어야 하므로, 마이그레이션을 돌리기 전에 세어 봐야 한다. - 지금 데이터셋에는 null 행이 없어 이 경계가 재현되지 않는다. null이 섞인 데이터셋을 따로 만들어야 확인할 수 있다. 시더가 이 컬럼의 값을 시간에 흩어 놓은 것은 시간순 페이징과 정렬 인덱스를 실험할 바탕을 마련하려는 구성이다. 값이 비는 행을 만드는 것은 그 구성에 들어 있지 않다. -## 선택지 +## NOT NULL로 좁힐지 null 정렬 규칙을 둘지 ### 1. NOT NULL로 좁힌다 @@ -75,7 +75,7 @@ FeedItem을 만드는 흐름은 하이라이트 없이도 되지만, 커서에 인덱스는 작아지지만 null 행을 읽는 쿼리를 따로 둬야 한다. -## 다음 검증 +## 실제 생성 경로와 기존 null 데이터를 먼저 확인한다 1. 도메인에서 하이라이트 없는 FeedItem이 생기는 경로가 있는지 확인한다. diff --git a/docs/n+1liner/tech-log-studio/jpa-feed-query-performance/question/question-promote-feed-visible-to-cqrs.md b/docs/n+1liner/tech-log-studio/jpa-feed-query-performance/question/question-promote-feed-visible-to-cqrs.md index 626d517..78d61ba 100644 --- a/docs/n+1liner/tech-log-studio/jpa-feed-query-performance/question/question-promote-feed-visible-to-cqrs.md +++ b/docs/n+1liner/tech-log-studio/jpa-feed-query-performance/question/question-promote-feed-visible-to-cqrs.md @@ -20,7 +20,7 @@ source: 사용자별 가시성을 미리 펼친 feed_visible 테이블을 두자 피드 조회가 커버링 인덱스 하나만 읽는 단일 스캔으로 바뀌었다. 이 테이블을 상시 유지하려면 원본이 바뀔 때마다 투영을 갱신해야 하고, 그러면 쓰기와 분리된 물리 읽기 저장소를 두는 풀 CQRS(Command Query Responsibility Segregation, 명령과 조회를 다른 모델로 나누는 설계)로 넘어간다. 그 비용을 이번 범위에서 바로 받아들일지는 따로 판단해야 할 일로 두었다. -## 관계 +## 사전계산은 가장 적은 행을 읽었지만 유지 비용이 생긴다 - **Feed Visibility Query Pattern** 단일 OR, UNION 분해, 사전계산 세 방식을 같은 결과 집합으로 비교했다. @@ -29,7 +29,7 @@ source: - **Visibility OR이 Keyset Index를 깨뜨린 문제** keyset으로 푼 페이지 조회에 가시성 세 분기를 얹자 BitmapOr와 재정렬이 다시 나타났고, 사전계산은 이것을 없애려던 방식이다. -## 사실 +## 세 조회 방식의 현재 실행계획 차이 - 사전계산 조회는 feed_visible 커버링 인덱스 하나만 읽었다. OR도 조인도 정렬도 없이 20행에 접근했고 buffers는 1이었다. - 단일 OR은 세 분기를 BitmapOr로 합쳐 후보 1,500을 훑은 뒤 정렬로 상위 20을 냈고 buffers는 122였다. UNION 분해는 요청할 때마다 세 분기를 각각 스캔했고 buffers는 200으로 단일 OR보다 컸다. @@ -38,13 +38,13 @@ source: - feed_visible은 FeedVisibilityIT와 FeedCrownIT 안에서 만들고 지우는 실험용 테이블이라 상시 유지하지 않는다. - 지금 읽기 경로는 쓰기와 같은 저장소를 쓰면서 읽기 전용 포트·DTO·쿼리만 분리한 CQRS-lite다. -## 가정 +## 트래픽이 커지면 사전계산의 조회 비용 이점이 커질 수 있다 - 고트래픽 읽기에서는 세 방식의 조회 비용 차이가 실제 부하로 나타난다. - 상시 유지하면 피드·멘션·가시성이 바뀔 때마다 투영을 다시 써야 한다. - 투영이 어긋나면 사용자가 볼 수 없어야 할 항목이 화면에 나오거나 볼 수 있는 항목이 빠진다. -## 미지수 +## 언제 요청 시 계산에서 사전계산으로 넘어가야 하는가 - 지금 트래픽을 단일 OR이나 UNION 분해로 감당할 수 있는가. 사전계산이 필요해지는 읽기 요청량이 어디부터인가. - 쓰기 변경을 투영으로 어떻게 옮기는가. 도메인 이벤트로 보내는가, 아웃박스 테이블을 거치는가. @@ -54,13 +54,13 @@ source: - 투영이 원본과 어긋났을 때 무엇으로 발견하고 어떻게 되돌리는가. - 승격이 현재 계약의 범위를 넘는다는 것은 확인했고, 계약과 가드레일의 어느 조항을 어떻게 고칠지는 아직 정하지 않았다. -## 제약 +## 가시성 투영이 어긋나면 보안 문제가 된다 - 현재 계약은 별도 물리 읽기 저장소를 에스컬레이션 대상으로 두었다. 승격하려면 계약을 먼저 개정해야 한다. - 가시성은 보안에 걸린 조건이라 투영이 어긋나면 볼 수 없어야 할 항목이 노출된다. 그래서 동기화 지연 허용치를 느슨하게 잡을 수 없다. - 지금까지 잰 값은 모두 단일 스레드 로컬 측정이라, 고트래픽에서 어느 방식이 필요한지는 이 값으로 답할 수 없다. -## 선택지 +## 요청 시 조회를 유지할지 feed_visible을 상시 관리할지 ### 1. 현재 범위를 유지하고 요청 시 조회로 푼다 @@ -80,7 +80,7 @@ source: 두 조회 경로를 함께 운영해야 하고, 어느 구간을 투영에 둘지 무엇을 보고 가를지 먼저 정해야 한다. -## 다음 검증 +## 부하와 투영 갱신 비용을 함께 측정한다 1. 부하 테스트로 지금의 조회 방식이 목표 트래픽을 견디는지 확인한다. diff --git a/docs/n+1liner/tech-log-studio/jpa-feed-query-performance/reference/reference-feed-visibility-query-pattern.md b/docs/n+1liner/tech-log-studio/jpa-feed-query-performance/reference/reference-feed-visibility-query-pattern.md index 01a005b..8eccfdc 100644 --- a/docs/n+1liner/tech-log-studio/jpa-feed-query-performance/reference/reference-feed-visibility-query-pattern.md +++ b/docs/n+1liner/tech-log-studio/jpa-feed-query-performance/reference/reference-feed-visibility-query-pattern.md @@ -18,22 +18,22 @@ source: 조회 사용자에 따라 보이는 항목이 갈리는 피드는 공개, 멘션, 비공개 세 분기로 조건이 나뉜다. 세 분기를 하나의 OR로 묶는 방식, UNION으로 나누는 방식, 사용자별로 미리 펼쳐 두는 방식은 같은 항목 집합을 돌려주지만 실행계획과 읽는 블록 수가 다르다. -## 관계 +## Feed Visibility는 공개·멘션·비공개 조건을 함께 처리한다 - **Visibility OR이 Keyset Index를 깨뜨린 문제** keyset 쿼리에 이 세 분기를 얹자 정렬키 인덱스가 계획에서 빠지는 것을 확인한 기록이다. - **feed_visible을 Production CQRS로 승격할 것인가** - 사전계산 테이블을 실험 밖에서 상시 유지할지는 이 질문이 다룬다. + 사전계산 테이블을 실제 운영 경로에서 상시 유지할지는 별도 부하·동기화 검증이 필요하다. - **Keyset Pagination 설계 기준** 가시성 조건을 얹기 전에 커서와 정렬키 인덱스를 어떻게 맞출지 정한 기준이다. -## 목적 +## 같은 결과 집합을 만드는 세 조회 방식을 비교한다 세 분기가 보는 것이 서로 다르다. 공개 분기는 visibility 값만 비교하고, 멘션 분기는 feed_item_mentions를 뒤져 조회자가 멘션됐는지 확인하며, 비공개 분기는 항목의 user_id가 조회자인지 본다. 하나의 인덱스는 선두 컬럼 순서 하나만 주기 때문에 셋을 한 접근 경로로 만족시킬 수 없다. 여기에 정렬과 페이징까지 요구하면 세 분기를 어떻게 합치느냐에 따라 Sort 노드가 붙기도 하고 사라지기도 한다. -## 규칙 +## 결과와 정렬 순서를 고정한 뒤 Plan 비용을 비교한다 ### 1. 단일 OR로 묶으면 Sort 노드가 다시 붙는다 @@ -73,19 +73,19 @@ buffers 하나로 줄 세우면 UNION 분해가 뒤로 밀리지만 훑은 행 미리 계산한 테이블을 실험 밖에서 계속 유지하려면 피드·멘션·가시성이 바뀔 때마다 투영에 반영해야 한다. -## 적용 조건 +## 사용자별 가시성과 Keyset Pagination을 함께 적용할 때 - 조회 사용자에 따라 보이는 항목이 달라지는 목록을 만들 때 - 가시성 조건과 정렬·페이징을 함께 요구할 때 - 고트래픽 읽기에서 조회 비용을 줄여야 할 때 -## 예외 +## 사전계산은 조회 비용 대신 동기화 비용이 생긴다 -- 분기가 하나뿐이면 단일 조건이 가장 단순하다. 이 기준은 분기가 셋 이상일 때 적용한다. +- 분기가 하나뿐이면 단일 조건이 가장 단순하다. 여기서는 공개·멘션·비공개처럼 여러 가시성 분기를 함께 처리하는 경우를 비교한다. - 쓰기가 잦고 읽기가 드물면 사전계산의 갱신 비용이 이득을 넘는다. - 조회 사용자 수가 매우 많으면 사용자별 투영의 저장 공간을 먼저 계산한다. -## 예시 +## 단일 OR과 UNION, feed_visible 사전계산 - 단일 OR : 분기별 스캔을 BitmapOr로 합침, top-N Sort 재등장, 멘션 조건은 hashed SubPlan, buffers 122 - UNION 분해 : 분기별 정렬 스트림을 Merge Append로 병합, 전체 재정렬 없음, 멘션 조건은 Hash Join, buffers 200 diff --git a/docs/n+1liner/tech-log-studio/jpa-feed-query-performance/reference/reference-fetch-strategy-selection.md b/docs/n+1liner/tech-log-studio/jpa-feed-query-performance/reference/reference-fetch-strategy-selection.md index 4128ac4..590848a 100644 --- a/docs/n+1liner/tech-log-studio/jpa-feed-query-performance/reference/reference-fetch-strategy-selection.md +++ b/docs/n+1liner/tech-log-studio/jpa-feed-query-performance/reference/reference-fetch-strategy-selection.md @@ -19,7 +19,7 @@ source: 세 전략은 줄이는 것이 서로 다르다. fetch join은 쿼리 수를 1+N에서 1로 줄이지만 전송 행을 자식 수만큼 부풀리고, 배치는 왕복을 배치 크기 단위로 묶지만 엔티티는 통째로 하이드레이트하고, 프로젝션은 엔티티를 하나도 만들지 않지만 부모당 자식 행은 전부 가져온다. -## 관계 +## Fetch Strategy는 필요한 데이터 형태와 Pagination에 따라 달라진다 - **Fetch Join으로 N+1을 해결하다 만난 MultiBag과 행 폭증** 컬렉션 둘을 동시에 fetch join하면 거부되고, 하나만 걸면 행이 늘어난다. @@ -28,13 +28,13 @@ source: - **Projection 이후에도 1,509행을 읽은 Row Over-fetch** 프로젝션으로 엔티티 로드는 0이 되었지만 자식 행 1,509개는 줄지 않았다. -## 목적 +## Fetch Join과 Batch, Projection을 같은 기준으로 비교한다 컬렉션 fetch join은 쿼리 수를 1+N에서 1로 줄이지만, 부모 100행짜리 조회가 조인 뒤 1,961행을 실어 날랐다. 배치는 왕복을 2,022개에서 23개로 줄였지만 엔티티 1,569개를 하이드레이트했다. 무엇을 줄이려는지 먼저 정하고 그것을 세는 지표로 전후를 비교한다. 왕복은 PreparedStatement 수로, 메모리에 올린 부모 수는 feedItemLoaded로, 영속 엔티티 수는 Statistics.getEntityLoadCount()로 잰다. -## 규칙 +## Query Count와 Row Volume, Entity Hydration을 따로 측정한다 ### 1. 컬렉션 fetch join은 두 개 이상 쓰지 않는다 @@ -78,18 +78,18 @@ SELECT new Carrier(...)로 필요한 스칼라 값만 조회하면 영속 엔티 fetch join은 쿼리 수를 1로 줄이는 대신 행을 곱했고 페이징을 막았다. 배치는 왕복과 페이징을 풀었지만 FeedItem·User·Page·Highlight를 합해 1,569개를 하이드레이트했다. 프로젝션은 그 1,569개를 0개로 만들었지만 페이지 부모 20개의 자식 1,509행을 전부 가져왔다. -## 적용 조건 +## 화면 조회에서 연관 데이터를 함께 가져와야 할 때 - 연관을 포함한 목록 조회를 설계할 때 - N+1을 확인하고 fetch 전략을 고를 때 - 전략을 바꾼 뒤 무엇이 줄고 무엇이 줄지 않았는지 정리할 때 -## 예외 +## Collection Fetch Join과 Pagination은 함께 사용하지 않는다 - 컬렉션이 하나이고 페이징이 없으며 자식 수가 작다면 컬렉션 fetch join이 단순하다. 자식 수가 커질 수 있는 구조에는 쓰지 않는다. - hibernate.default_batch_fetch_size는 세션 전체에 영향을 준다. 앞서 잰 값을 다시 재려면 이 랩처럼 별도 테스트 클래스(FeedBatchFetchIT)에만 설정한다. -## 예시 +## 엔티티 그래프와 화면 Projection의 선택 - 컬렉션 두 개 fetch join : createQuery 시점에 MultipleBagFetchException - 컬렉션 한 개 fetch join : 부모 100행, 조인 행 1,961행 diff --git a/docs/n+1liner/tech-log-studio/jpa-feed-query-performance/reference/reference-fetch-type-vs-fetch-strategy.md b/docs/n+1liner/tech-log-studio/jpa-feed-query-performance/reference/reference-fetch-type-vs-fetch-strategy.md index 51c839b..f57c8b9 100644 --- a/docs/n+1liner/tech-log-studio/jpa-feed-query-performance/reference/reference-fetch-type-vs-fetch-strategy.md +++ b/docs/n+1liner/tech-log-studio/jpa-feed-query-performance/reference/reference-fetch-type-vs-fetch-strategy.md @@ -16,9 +16,9 @@ source: # Fetch Type과 Fetch Strategy 구분 -즉시 로딩(EAGER)과 지연 로딩(LAZY)은 연관을 언제 로딩할지 정하는 계약이지, 어떤 SQL로 가져올지는 정하지 않는다. 그래서 N+1은 fetch 타입을 바꿔서 풀리지 않고 왕복과 적재 방식을 바꾸는 조회 전략으로 푼다. +즉시 로딩(EAGER)과 지연 로딩(LAZY)은 연관을 언제 로딩할지 정하는 계약이지, 어떤 SQL로 가져올지는 정하지 않는다. N+1 여부는 실제 조회 쿼리가 연관 관계를 어떻게 가져오는지 확인하고, 필요한 경우 Fetch Join·Batch Fetch·Projection 같은 조회 전략을 바꿔 해결한다. -## 관계 +## Fetch Type과 실제 SQL Fetch Strategy는 같은 개념이 아니다 - **필드 접근 없이 발생한 EAGER ToOne N+1** 연관 필드를 한 번도 읽지 않았는데 2차 SELECT가 아이템 수만큼 나간 것을 잰 기록이다. @@ -27,13 +27,13 @@ source: - **JPA N+1 정량 진단 기준** 두 축을 나눠 측정하는 방법이다. -## 목적 +## EAGER와 LAZY만 보고 N+1 원인을 판단하지 않는다 즉시 로딩이면 루트와 연관을 한 번에 가져온다고 읽기 쉽다. 실제로는 파생 쿼리가 루트를 먼저 조회한 뒤 연관을 행마다 2차 SELECT로 채우기도 한다. 애너테이션의 fetch 값을 바꾸면 조회가 언제 나갈지가 달라지고, 조회 방식을 바꾸면 몇 번 나갈지가 달라진다. -## 규칙 +## 조회 Query가 연관 관계를 어떻게 가져오는지 실제 SQL로 확인한다 ### 1. EAGER는 로딩 시점 계약이지 JOIN 보장이 아니다 @@ -73,18 +73,18 @@ N+1이 생길 가능성은 fetch 계약이 만들지만, 실제로 몇 번 조 fetch 타입을 바꾸면 조회가 나가는 시점만 달라진다. 왕복 수를 줄이려면 fetch join, 배치 페치, 프로젝션처럼 조회 방식 자체를 바꾼다. 배치 페치는 N=1,000에서 총 PreparedStatement를 2,022개에서 23개로 줄였다. -## 적용 조건 +## ToOne과 Collection에서 추가 SELECT가 발생할 때 - 연관 매핑을 정하거나 바꿀 때 - N+1의 원인을 애너테이션에서 찾으려 할 때 - EAGER를 LAZY로 바꾸면 N+1이 풀린다고 판단하기 전에 -## 예외 +## 필드 접근 여부만으로 추가 조회 발생 시점을 설명할 수 없다 - 단건 조회에서는 구현체가 JOIN을 고르기도 한다. 그 동작에 기대려면 쓰는 구현체와 버전에서 직접 확인한 뒤 적는다. - 연관을 어디에서도 읽지 않는다면 LAZY로 바꾸는 것만으로 그 조회가 사라진다. 이때는 조회 방식을 손대지 않고 fetch 값만 바꾸면 된다. -## 예시 +## EAGER ToOne에서 필드 접근 전 발생한 추가 조회 - EAGER : 반환 시점까지 로딩. SQL 형태는 보장하지 않음 - LAZY : 접근 시점에 로딩 diff --git a/docs/n+1liner/tech-log-studio/jpa-feed-query-performance/reference/reference-keyset-pagination-design.md b/docs/n+1liner/tech-log-studio/jpa-feed-query-performance/reference/reference-keyset-pagination-design.md index 70cbc90..b07e9fe 100644 --- a/docs/n+1liner/tech-log-studio/jpa-feed-query-performance/reference/reference-keyset-pagination-design.md +++ b/docs/n+1liner/tech-log-studio/jpa-feed-query-performance/reference/reference-keyset-pagination-design.md @@ -18,22 +18,22 @@ source: OFFSET은 정렬 순서에서 앞의 offset행을 만든 뒤 버리기 때문에 페이지가 깊어질수록 훑는 행이 늘어난다. keyset은 이전 페이지의 마지막 행을 커서로 삼아 그 지점 이후만 읽으므로 깊이와 상관없이 페이지 크기만큼만 훑는다. 다만 커서와 같은 순서의 정렬키 인덱스가 없으면 keyset도 Seq Scan으로 전량을 훑는다. -## 관계 +## Keyset Pagination은 정렬키와 Cursor, Index가 함께 맞아야 한다 - **Visibility OR이 Keyset Index를 깨뜨린 문제** 가시성 조건을 같은 쿼리에 얹자 플래너가 정렬키 인덱스를 쓰지 못하고 BitmapOr로 떨어졌다. - **Feed Pagination은 Keyset을 사용한다** - 이 기준을 따라 부모 피드 페이징을 OFFSET에서 커서로 바꿨다. + 부모 Feed 조회는 OFFSET 대신 정렬 시각과 ID를 사용하는 Cursor 방식으로 바꿨다. - **PostgreSQL Query Plan 측정 기준** 깊이별로 훑은 행과 읽은 블록 수를 EXPLAIN으로 잴 때 그 기준을 따랐다. -## 목적 +## 깊은 OFFSET에서 버리는 행을 없앤다 무한 스크롤에서는 뒤쪽 페이지일수록 OFFSET이 커진다. 정렬키 인덱스가 있어도 건너뛸 튜플을 훑어야 하고, 깊어지면 아예 Seq Scan과 Sort로 전량을 훑는다. 페이지 깊이와 무관하게 읽는 행수를 페이지 크기에 고정하려면 이전 페이지의 마지막 행을 커서로 넘겨야 한다. -## 규칙 +## 정렬에 쓰는 모든 컬럼을 Cursor와 Index에 같은 순서로 둔다 ### 1. 커서에 정렬키를 모두 담는다 @@ -77,19 +77,19 @@ OFFSET은 offset에 페이지 크기를 더한 만큼 훑고 keyset은 페이지 피드의 first_highlighted_at은 아직 NOT NULL이 아니다. NOT NULL로 좁힐지 NULLS LAST 같은 null 정렬 위치를 정의할지는 keyset 페이징 단계 이전에 결론 내기로 하고 미결정으로 뒀다. -## 적용 조건 +## 앞뒤로 이어지는 Feed와 Infinite Scroll - 무한 스크롤이나 깊은 페이지를 지원할 때 - 정렬 순서가 고정돼 있고 인덱스를 만들 수 있을 때 - 전체 페이지 수가 필요하지 않을 때 -## 예외 +## Nullable 정렬키와 임의 페이지 이동은 별도 설계가 필요하다 - 임의 페이지 점프가 필요하면 커서만으로는 부족하다. OFFSET을 함께 두거나 다른 탐색을 설계한다. - 전체 건수를 화면에 표시해야 하면 count 쿼리를 따로 실행한다. 커서 결과에는 전체 건수가 없다. - 정렬 기준이 자주 바뀌면 기준마다 인덱스가 필요하다. 인덱스 수와 쓰기 비용을 함께 본다. -## 예시 +## first_highlighted_at과 id를 사용하는 Cursor - OFFSET 훑은 행 : offset + 페이지 크기 (offset 1980에서 2,000행) - keyset 훑은 행 : 페이지 크기 (offset 1980에서도 20행) diff --git a/docs/n+1liner/tech-log-studio/jpa-feed-query-performance/reference/reference-nplus1-quantitative-diagnosis.md b/docs/n+1liner/tech-log-studio/jpa-feed-query-performance/reference/reference-nplus1-quantitative-diagnosis.md index bf345ea..a607618 100644 --- a/docs/n+1liner/tech-log-studio/jpa-feed-query-performance/reference/reference-nplus1-quantitative-diagnosis.md +++ b/docs/n+1liner/tech-log-studio/jpa-feed-query-performance/reference/reference-nplus1-quantitative-diagnosis.md @@ -18,20 +18,20 @@ source: N+1은 쿼리 총계가 아니라 Hibernate Statistics의 지표를 나눠 읽어 확인한다. 세 지표는 세는 단위가 서로 달라서, 모두 SQL 실행 횟수로 바꿔 읽으면 Batch Fetch를 적용한 뒤 등식이 깨지고 결론이 어긋난다. -## 관계 +## N+1은 Query Count만으로 비용을 설명할 수 없다 - **Fetch 타입이 아니라 조회 방식이 만든 ToOne N+1** 엔티티별 fetch 통계를 직접 읽어 여기서 역산한 ToOne 조회 수를 확인했다. - **PostgreSQL Query Plan 측정 기준** 같은 측정에서 뽑은 실행계획을 어떻게 읽을지는 그 기록이 정한다. -## 목적 +## 왕복과 전송 행수, Hydration 비용을 분리해서 측정한다 쿼리가 몇 개 나갔는지만 세면 어느 연관이 문제인지 알 수 없다. 총계 하나에 목록 루트 쿼리, 페이지 count, ToOne 2차 SELECT, 컬렉션 초기화가 함께 들어 있기 때문이다. N=1,000에서 나온 총 PreparedStatement 2,022건도 이 네 가지가 섞인 값이다. 지표를 나눠 읽고 총계를 항등식으로 검산하면 어느 연관이 몇 번 조회됐는지 확정된다. -## 규칙 +## 데이터 규모를 바꾸며 Query Count와 Row Volume을 함께 기록한다 ### 1. 지표 이름이 뜻하는 것을 그대로 읽는다 @@ -87,18 +87,18 @@ N+1의 N은 전체 테이블 크기가 아니라 한 요청에서 조립하는 왕복은 fetch 전략으로, 행수는 SQL 형태와 인덱스로 푼다. -## 적용 조건 +## 연관 관계 조회가 데이터 수에 따라 느려질 때 - ORM 조회에서 쿼리 발생량이 N에 비례해 늘어나는지 확인할 때 - fetch 전략을 바꾸고 전후를 같은 지표로 비교할 때 - N+1 회귀를 테스트로 고정할 때 -## 예외 +## 편중된 데이터에서는 N과 전체 자식 행수가 비례하지 않을 수 있다 - SQL 형태별 정확한 실행 횟수가 필요하면 이 지표만으로 부족하다. SQL 로그, StatementInspector, datasource-proxy, p6spy, PostgreSQL statement logging 중 하나로 따로 수집한다. 그 단계는 Batch Fetch가 컬렉션 수와 SQL 수의 등식을 깨뜨리는 때로 미리 정해 두었다. - 운영 종단 지연이나 처리량, 커넥션 풀 상태가 필요하면 이 측정의 범위 밖이다. 부하 테스트와 APM(Application Performance Monitoring, 애플리케이션 성능 모니터링)으로 확인한다. -## 예시 +## FeedItem과 Highlight 수를 늘린 정량 비교 - 초기화 컬렉션 수 : 지연 로딩이 채운 컬렉션 개수. 실행된 SELECT 수가 아니다 - 총 PreparedStatement : JDBC에서 얻은 문장 객체 수. SQL 실행 수와 다를 수 있다 diff --git a/docs/n+1liner/tech-log-studio/jpa-feed-query-performance/reference/reference-postgresql-query-plan-measurement.md b/docs/n+1liner/tech-log-studio/jpa-feed-query-performance/reference/reference-postgresql-query-plan-measurement.md index 86fe413..49bed8c 100644 --- a/docs/n+1liner/tech-log-studio/jpa-feed-query-performance/reference/reference-postgresql-query-plan-measurement.md +++ b/docs/n+1liner/tech-log-studio/jpa-feed-query-performance/reference/reference-postgresql-query-plan-measurement.md @@ -20,22 +20,22 @@ source: 실행계획과 인덱스 동작을 재려면 운영과 같은 DB 엔진에서 재야 한다. 비용 모델, 통계, 저장 구조, 쓸 수 있는 인덱스 기능이 엔진마다 달라서, 인메모리 DB에서 잰 계획은 운영 엔진이 고를 계획이 아니다. -## 관계 +## 실행계획은 실제 PostgreSQL의 통계와 비용 모델에서 결정된다 - **Query Plan은 실제 PostgreSQL에서 측정한다** - 이 기준에서 나온 결정이다. + 실행계획 비교는 실제 PostgreSQL에서 수행한다. - **JPA N+1 정량 진단 기준** 같은 측정에서 쿼리 수를 다루는 기준이다. - **ANALYZE 이후 Cardinality Estimate는 어떻게 달라지는가** 통계를 갱신하면 추정 행수가 어떻게 달라지는지는 아직 재지 않았다. -## 목적 +## Query Strategy 변경을 Plan과 실제 행수로 확인한다 쿼리가 몇 개 나갔는지만 세면 그 한 쿼리가 무엇을 얼마나 읽는지는 보이지 않는다. 반복되는 하이라이트 조회를 EXPLAIN으로 열어 보니 feed_item_id를 Index Scan으로 찾아 들어가는데도 한 번에 rows=500을 읽고 있었고, 응답에 필요한 것은 그중 최신 3개뿐이었다. 한 쿼리가 실어 나르는 행수, 스캔과 정렬 방식, 인덱스를 탔는지, 읽은 블록 수는 엔진이 실제로 고른 계획에만 적혀 있다. -## 규칙 +## EXPLAIN ANALYZE와 BUFFERS를 같은 데이터 조건에서 비교한다 ### 1. 운영과 같은 엔진에서 측정한다 @@ -91,19 +91,19 @@ Execution Time은 PostgreSQL executor 안에서 쓴 시간에 가깝고 ORM 엔 측정을 시작할 때 엔진 버전과 주요 플래너 설정도 함께 기록한다. 이 측정은 Testcontainers로 띄운 PostgreSQL 16에서 했다. -## 적용 조건 +## Index 선택과 Join, Sort 비용을 판단할 때 - 인덱스 설계나 쿼리 형태를 바꾸고 효과를 확인할 때 - 스캔 방식이나 정렬 방식이 바뀌었는지 확인할 때 - 여러 SQL 표현의 비용을 비교할 때 -## 예외 +## 추정 행수와 실제 행수가 크게 다르면 통계를 먼저 확인한다 - 쿼리 발생 횟수만 확인하면 되는 단계에서는 실행계획까지 필요하지 않다. - 운영 종단 지연이나 처리량이 필요하면 이 측정의 범위 밖이다. 부하 테스트와 APM으로 확인한다. - p99 같은 안정적인 꼬리 지연이 필요하면 워밍업 뒤 100회 넘게 반복하는 독립 세트나 JMH로 따로 잰다. -## 예시 +## ANALYZE 전후 Cardinality Estimate 비교 - 엔진 : 운영과 같은 PostgreSQL, H2 같은 인메모리 DB로 대체하지 않는다 - 명령 : EXPLAIN (ANALYZE, BUFFERS) diff --git a/docs/n+1liner/tech-log-studio/jpa-feed-query-performance/reference/reference-top-n-per-group-selection.md b/docs/n+1liner/tech-log-studio/jpa-feed-query-performance/reference/reference-top-n-per-group-selection.md index c36caaf..810a3a8 100644 --- a/docs/n+1liner/tech-log-studio/jpa-feed-query-performance/reference/reference-top-n-per-group-selection.md +++ b/docs/n+1liner/tech-log-studio/jpa-feed-query-performance/reference/reference-top-n-per-group-selection.md @@ -18,22 +18,22 @@ source: 부모마다 상위 N개를 뽑는 일은 LIMIT으로 표현되지 않는다. 윈도우 함수, LATERAL, 애플리케이션 그룹핑이 부모 20개에서 똑같은 60행을 돌려줬지만, LATERAL은 인덱스에서 부모당 3개만 읽어 buffers가 204였고 나머지 둘은 1,509행을 모두 읽어 430이었다. -## 관계 +## 부모마다 상위 N개 자식을 고르는 방법은 여러 가지다 - **Projection 이후에도 1,509행을 읽은 Row Over-fetch** - 프로젝션으로 엔티티 로드는 0이 되었지만 페이지 부모 20개의 자식 1,509행은 줄지 않았다. 그 1,509행을 60행으로 깎으려고 이 기준을 만들었다. + Projection으로 엔티티 로드는 0이 되었지만 페이지 부모 20개의 자식 1,509행은 그대로 읽었다. 각 부모에서 필요한 상위 Highlight만 읽어 Row Volume을 줄이는 방법을 비교한다. - **PostgreSQL Query Plan 측정 기준** 세 방식의 EXPLAIN (ANALYZE, BUFFERS)를 어떤 조건에서 재고 어느 값을 읽을지는 그 기록이 정한다. - **Fetch Join · Batch · Projection 선택 기준** 왕복은 배치가 2,022개에서 23개로, 엔티티 적재는 프로젝션이 1,569개에서 0개로 앞 단계에서 풀었다. 여기서는 남은 자식 1,509행을 60행까지 깎는다. -## 목적 +## Window Function과 LATERAL의 읽기 범위를 비교한다 자식 조회 끝에 LIMIT 3을 붙이면 부모별 그룹이 아니라 최종 결과 집합 전체에 적용된다. 부모 20개를 조회했는데 반환은 3행이었고 하이라이트가 들어간 부모는 1개였다. 그룹당 상한은 다른 표현으로 써야 한다. 세 표현은 모두 부모 20개에서 60행을 돌려주므로 정확성만으로는 고를 수 없다. 갈리는 곳은 그 60행을 만들기까지 읽은 행수와 buffers인데, 윈도우와 2단계는 1,509행을 읽어 430이었고 LATERAL은 204였다. -## 규칙 +## 같은 결과 집합과 정렬 조건에서 Plan을 측정한다 ### 1. 자식 쿼리 끝에 붙인 LIMIT은 부모별로 적용되지 않는다 @@ -83,18 +83,18 @@ LATERAL 문법 자체가 빠른 것이 아니라, 부모 키와 정렬 컬럼을 이 랩에서는 윈도우와 LATERAL이 60행에 부모 20, 부모당 3으로 같았고, 2단계는 코드에서 자르기 전 1,509행에 부모당 전량이었으며, 순진한 LIMIT 3은 3행에 부모 1이었다. 셋의 결과를 맞춘 뒤 캐시 상태를 맞추려고 같은 테스트 실행 안에서 EXPLAIN (ANALYZE, BUFFERS)를 돌렸다. -## 적용 조건 +## 각 FeedItem에서 일부 Highlight만 필요할 때 - 목록 응답에 부모별 자식 상위 몇 개를 포함해야 할 때 - 부모의 자식을 전부 가져오는 조회가 전송 행수 때문에 문제가 될 때 - 그룹 크기가 크고 화면에 필요한 개수가 작을 때 -## 예외 +## 데이터 분포와 Index에 따라 더 유리한 Plan이 달라질 수 있다 - 그룹 크기가 작아 전량을 읽어도 부담이 없으면 애플리케이션 그룹핑이 단순하다. - 부모별 정렬 인덱스를 만들 수 없으면 LATERAL은 부모마다 Seq Scan을 돌고 buffers가 4,446까지 올라간다. 이때는 윈도우 함수와 buffers를 비교해 고른다. -## 예시 +## ROW_NUMBER와 LATERAL LIMIT 비교 - 순진 LIMIT 3 : 부모 20개 조회에 반환 3행, 채워진 부모 1개 - 윈도우 : 파티션 1,509행을 읽어 순번을 매긴 뒤 60행, buffers 430