웹훅을 받는 쪽이 지켜야 할 규칙을 API 문서로 정리하고 있다. 참고하려고 연 외부 명세에 Clients SHOULD retry with exponential backoff.라는 문장이 있다. 한국어로 옮기면 "재시도해야 한다"일까, "재시도하면 좋다"일까. 대문자로 쓴 것을 보니 무언가 정해진 뜻이 있는 것 같다.
| 용어 | 뜻 |
|---|---|
| 동사 원형(base form) | to나 -s, -ed, -ing를 붙이지 않은 동사의 기본 꼴. 예문의 verify가 이 꼴이다. 예: The server MUST verify the signature. |
| 조동사(modal verb) | must, should, may, can처럼 동사 원형 앞에 붙어 의무·권유·허락·가능 같은 뜻을 더하는 말. 예: Every request must include a token. |
| 명령문(imperative sentence) | 주어(누가 하는지)를 빼고 동사 원형으로 시작해 상대에게 하라고 말하는 문장. 예: Run npm install before you start. |
명세의 Clients SHOULD retry with exponential backoff.를 읽은 구현자의 해석으로 맞는 것은?
규칙: 대문자 키워드는 요구 수준을 정의한다
인터넷 표준 문서(RFC)는 요구 사항의 강도를 몇 개의 영어 낱말로 정해 두었다. 이 낱말들을 이 책에서는 '요구 수준 키워드'라고 부른다. 정의는 RFC 2119에 있고, RFC를 내는 IETF 밖의 API 명세나 설계 문서도 이 정의를 빌려 쓴다.
A. MUST는 절대 요구, MUST NOT은 절대 금지다. REQUIRED와 SHALL은 MUST와, SHALL NOT은 MUST NOT과 같은 뜻이다. 지키지 않으면 명세를 어긴 구현이다.
Receivers MUST verify the signature before processing the payload.Servers MUST NOT include the access token in error responses.
B. SHOULD는 강한 권고, SHOULD NOT은 하지 말라는 강한 권고다. RECOMMENDED는 SHOULD와, NOT RECOMMENDED는 SHOULD NOT과 같은 뜻이다. 기본은 따르되, 정당한 이유가 있고 그 영향을 따져 봤을 때만 다르게 할 수 있다.
Clients SHOULD retry with exponential backoff.Clients SHOULD NOT poll the status endpoint more than once per second.
C. MAY는 정말로 선택이다. OPTIONAL과 같은 뜻이다. RFC 2119는 여기에 조건을 하나 더 붙인다. 그 선택 기능을 구현하지 않은 쪽도, 구현한 쪽도 서로 문제없이 맞물려 동작할 준비가 되어 있어야 한다.
Servers MAY include a Retry-After header in the response.The description field is OPTIONAL.
D. 대문자로 쓸 때만 이 뜻이다. RFC 8174는 이 낱말들이 모두 대문자일 때만 정의된 뜻을 갖고, 소문자일 때는 보통 영어의 뜻이라고 못 박았다. 그래서 이 키워드를 쓰는 문서는 첫머리에 아래 한 줄을 넣어 대문자 키워드의 뜻을 선언한다. RFC 8174가 제시하는 문구다.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in
BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all
capitals, as shown here.RFC 2119는 이 키워드를 조심해서, 아껴 쓰라고도 한다. 상호 운용에 정말 필요하거나 해를 끼칠 수 있는 동작을 제한할 때만 쓰고, 구현 방법을 강요하는 데 쓰지 말라는 것이다(RFC 2119 6절).
표현: 문서 종류마다 고르는 말
| 표현 | 언제 | 예 |
|---|---|---|
MUST / REQUIRED / SHALL | 명세에서 지키지 않으면 위반인 요구 | Clients MUST send the Idempotency-Key header. |
MUST NOT / SHALL NOT | 명세에서 어떤 경우에도 금지 | Servers MUST NOT log request bodies that contain card numbers. |
SHOULD / RECOMMENDED | 명세에서 이유가 있을 때만 벗어날 수 있는 권고 | Clients SHOULD cache the public keys for up to 24 hours. |
SHOULD NOT / NOT RECOMMENDED | 명세에서 이유가 있을 때만 해도 되는 동작 | Clients SHOULD NOT hard-code the endpoint URL. |
MAY / OPTIONAL | 명세에서 해도 되고 안 해도 되는 선택 | Servers MAY return results in any order. |
소문자 must | README·가이드에서 꼭 해야 하는 일 | You must have Node.js 22 or later installed. |
We recommend | README·가이드에서 권하는 일 | We recommend running the tests in watch mode. |
소문자 can | README·가이드에서 선택할 수 있는 일 | You can also pass a custom logger. |
README나 사용자 가이드는 명세가 아니라서 대문자 키워드를 쓰지 않는다. 일반 문서에서는 Google 개발자 문서 스타일 가이드의 방식이 참고가 된다. 필수 동작에는 must나 명령문(imperative sentence)을, 권하는 동작에는 We recommend …를, 선택 동작에는 can을 쓰라고 한다. 소문자 should는 필수인지 선택인지 흐려지니 되도록 피하라고 한다(Google 개발자 문서 스타일 가이드: Prescriptive documentation). 같은 가이드는 may를 공식 정책이나 법적 내용에만 쓰고, 가능성은 can이나 might로 쓰라고 한다(Google 개발자 문서 스타일 가이드: may). 리뷰 코멘트에서 might로 어조를 낮추는 법은 Unit 4에서 다룬다.
설계 결정 기록(ADR)이나 팀 내부 API 규약에 대문자 키워드를 쓰려면 문서 첫머리에 위의 선언 문구를 넣는다. 선언 없이 대문자만 섞으면 읽는 사람은 강조인지 정의된 키워드인지 알 수 없다. PR 템플릿 체크리스트의 모든 줄을 MUST로 쓰는 것도 피한다. 모든 줄이 절대 요구가 되면 정말 중요한 줄이 묻힌다.
MUST, SHOULD, MAY가 각각 정의된 강도를 가집니다. 대문자일 때만 그 뜻입니다.MUST로 옮기면 권고였던 것이 절대 요구가 됩니다. 반대로 '~하는 것이 좋다'를 소문자 should로 옮기면 README에서는 필수인지 선택인지 흐려집니다. 옮기기 전에 이 요구를 어기면 위반인지부터 정합니다.함정 찾기: AI가 쓴 웹훅 명세
웹훅 수신 규칙을 RFC 2119 키워드로 영어 명세로 써 줘.
- 서명 검증, 중복 처리: 필수
- 원본 payload 로그: 개인정보라 절대 금지
- 10초 안 응답: 권장
의심스러운 줄을 모두 눌러 표시한 뒤 “검토 끝”을 누르세요. 함정은 2개입니다.
연습
1. 액세스 토큰을 로그에 남기는 것은 어떤 경우에도 금지다. 명세 문장 "Servers ___ write access tokens to logs."의 빈칸은?
2. 응답에 Retry-After 헤더를 넣을지는 서버가 정한다(넣지 않아도 위반이 아니고, 넣으라고 권하지도 않는다).
"Servers ___ include a Retry-After header."의 빈칸은?
3. 키워드 선언 문구(RFC 2119·8174를 따른다는 문장)가 있는 문서의 README 절에 소문자로 "You must restart the server after changing this value."라고 적혀 있다. 이 must는?
4. (Google 개발자 문서 스타일 가이드를 따르는 README) 권하지도 않는 순수한 선택 기능을 안내하는 문장은?