성능 및 확장성
개요
성능은 예산이 있는 기능입니다. 측정하고, 한계를 정하고, 오늘의 동작이 내일의 계약이 된다는 점을 존중하세요. 시스템은 설계한 처리량에서 무너지는 경우가 드뭅니다. 인덱싱하지 않은 쿼리와 페이지네이션하지 않은 목록에서 무너집니다.
원칙
- 예산을 설정하고 이에 대해 측정하세요. 대기 시간 목표(
관찰 가능성 및 SLO의 SLO와 연결됨)와 클라이언트 예산(예: 번들 크기)을 설정합니다. 예산을 초과한 회귀는 버그입니다. - 최적화하기 전에 측정하세요. 코드를 변경하기 전에 프로파일, 쿼리 계획, 추적을 통해 실제 병목 지점을 찾으세요. 추측에 의한 최적화는 하지 마세요.
- 기본적으로 페이지네이션하세요. 커질 수 있는 모든 목록은 최대 페이지 크기가 정해진 페이지네이션을 적용합니다. 무제한 결과 집합은 대기 시간 및 서비스 거부 위험입니다.
- N+1 액세스 패턴을 주의하세요. 루프에서 데이터를 가져오는 것이 가장 흔한 확장성 실패입니다. 대신 배치(batch)나 조인(join)을 사용하세요. (이 스택에서는: 행별 해결 대신 GraphQL 계층의 look-ahead/DataLoader를 사용하세요.)
- 하이럼의 법칙은 현실입니다: 인터페이스의 관찰 가능한 모든 동작은 충분한 소비자가 생기면 누군가가 의존하는 계약이 됩니다. 여기에는 의도치 않은 동작(순서, null 허용 여부, 오류 형태, 타이밍)도 포함됩니다. 공개 인터페이스(특히 API/스키마)를 계약으로 취급하세요: 조용히 변경하지 말고 추가하고 폐기(deprecate)하세요.
graphql-contract-testing의 계약 테스트는 여러분이 선택한 동작을 고정합니다. 규율은 선택하지 않은 동작을 보호합니다.
빠른 참조
| 문제 상황 | 해결 방법 |
|---|---|
| 루프 안의 쿼리 | 배치 또는 조인; look-ahead 사용 |
| 제한 없는 목록 엔드포인트 | 최대 크기가 정해진 페이지네이션 추가 |
| 측정 없이 "최적화해 보겠습니다" | 먼저 프로파일; 실제 병목 지점 찾기 |
| 필드의 타입/nullability/순서 변경 | 계약 변경입니다 — 새로 추가하고, 이전 것은 폐기 |
| 대기 시간 또는 번들 목표 없음 | 예산 설정; 회귀를 버그로 처리 |
시행: 기계화 가능한 부분(번들 크기 제한, 쿼리 비용 제한)은 CI에서 예산을 확인합니다. 페이지네이션 및 N+1 회피는 부하 테스트와 쿼리 계획 검토를 기반으로 한 리뷰어의 판단에 맡깁니다.
전체 근거: engineering-constitution/references/engineering-constitution.md에 번들된 헌법 제11조.