docs(web): web 운영 문서를 한국어로 옮기고 코드와 맞춘다

문제: docs/web 아래 살아 있는 문서 7개가 영어였다(language 예외). http-contract.md는
짝 프론트 repo의 문서를 이 repo 경로처럼 인라인 코드로 적었다(reference 예외).
repository-adaptation.md는 번역하며 보니 지금 코드와 여러 곳이 달랐다.
- 1절 표: 설계 모듈 대부분을 「planned」로 적었지만 `core`·`mvc`는 web leaf에,
  `contract`·`versioning`·`admin`·`openapi`·`idempotency`는 web-advanced leaf에 이미 있다.
  `fileserver.*`·`notification.*`는 web leaf가 아니라 web-fileserver·web-notification leaf다.
- Advanced 절: Advanced가 「이 leaf」의 package이고 `WebArchitectureRules.stableDoesNotDependOnAdvanced()`
  (`WEB-ARCH-ADV`)가 방향을 막는다고 했다. 그런 규칙은 없고, Advanced는 따로 된 leaf
  `adapter:inbound:web-advanced`이며 registry가 web-advanced → web 방향만 허락한다.
- 4절: Spring Boot 기준을 4.0.8로 옮겨 적고 없는 `.vscode/settings.json`을 근거로 들었다.
- 6절: 다시 보내기 JSON 인코딩이 web leaf에 남는다고 했지만 web-advanced에 있다.
- 7절: web leaf가 의존할 수 있는 leaf에서 `adapter-outbound-support`가 빠졌다.

고친 방법: 뜻을 그대로 옮기고 식별자·명령·경로·설정 key·오류 코드·표 구조는 원문으로
둔다. 위 불일치는 registry와 트리에 맞춰 고쳤다. 다른 repo 문서는 경로 대신 repo 이름과
문서 이름을 문장으로 쓴다. 버전은 src/gradle/libs.versions.toml을 가리킨다.

버린 대안: 1절 표를 지우고 registry만 가리키기. 설계와 트리를 대조하는 사람에게 필요한
대응이 사라진다.

위험·한계: 내용 감사는 하지 않았다. 번역하며 본 불일치만 고쳤다.

검증: python3 scripts/check-docs.py에서 이 폴더 예외 줄 0. docs/web을 읽는 테스트는
주석뿐이다(`grep -rn 'docs/web' src --include=*.java`: EnvelopeWireShapeTest 등 주석).
This commit is contained in:
DongHyeonka
2026-11-07 17:29:57 +09:00
parent e38c949c2f
commit 9d6c67c14e
9 changed files with 448 additions and 531 deletions
+37 -49
View File
@@ -1,60 +1,50 @@
# Web patch: the client contract
# Web patch: client 계약
Two patch formats, and they are not interchangeable. Both appliers are library code in
`adapter:inbound:web-advanced` (opt-in): a service adds the leaf and calls `JsonMergePatchApplier`
or `JsonPatchApplier` from its controller.
patch 형식은 둘이고, 서로 바꿔 쓸 수 없다. 두 applier 모두 `adapter:inbound:web-advanced`(골라 쓰는 leaf)의 라이브러리
코드다. 서비스가 그 leaf를 더하고 자기 controller에서 `JsonMergePatchApplier`나 `JsonPatchApplier`를 부른다.
## Choosing one
## 하나 고르기
A route accepts exactly one, and sending the other is a 415 rather than a best-effort guess. The
reason is that a mismatch is silent in the worst direction:
route는 정확히 하나만 받고, 다른 것을 보내면 최선의 짐작 대신 415다. 어긋남이 가장 나쁜 방향으로 조용하기 때문이다.
- `{"a": null}` as a **merge patch** deletes `a`. As a **JSON Patch** it is not a patch at all — it
is an object where an array was required.
- A JSON Patch array read as a merge patch is a document whose fields are array indices. It merges
nothing and reports success.
- `{"a": null}`은 **merge patch**로는 `a`를 지운다. **JSON Patch**로는 patch가 아예 아니다. 배열이 필요한 곳의 객체다.
- JSON Patch 배열을 merge patch로 읽으면 필드가 배열 index인 문서다. 아무것도 합치지 않고 성공을 보고한다.
| | Merge patch | JSON Patch |
| --- | --- | --- |
| Media type | `application/merge-patch+json` | `application/json-patch+json` |
| RFC | 7396 | 6902 |
| Shape | A partial document | An ordered array of operations |
| Delete | `"field": null` | `{"op":"remove","path":"/field"}` |
| Arrays | Replaced whole | Addressable per index |
| Preconditions | `If-Match` only | `If-Match`, plus per-field `test` |
| 모양 | 부분 문서 | 순서 있는 연산 배열 |
| 삭제 | `"field": null` | `{"op":"remove","path":"/field"}` |
| 배열 | 통째로 바꾼다 | index마다 가리킬 수 있다 |
| 선행 조건 | `If-Match`만 | `If-Match`, 그리고 필드별 `test` |
Use merge patch for "change these fields". Use JSON Patch when you need array element edits or a
precondition on one field that `If-Match` cannot express.
「이 필드들을 바꿔라」에는 merge patch를 쓴다. 배열 원소를 고치거나, `If-Match`로 표현할 수 없는 필드 하나의 선행
조건이 필요하면 JSON Patch를 쓴다.
## What is refused
## 거부하는 것
**Fields outside the allowlist.** The server declares which fields a merge patch may modify and
which pointers a JSON Patch may address. Anything else is refused, and *every* refused path is
named — you will not discover them one round trip at a time.
**허용 목록 밖의 필드.** 서버가 merge patch가 바꿀 수 있는 필드와 JSON Patch가 가리킬 수 있는 pointer를 선언한다.
그 밖의 것은 거부하고, 거부한 경로는 *모두* 이름을 댄다. 왕복 한 번에 하나씩 알게 되지 않는다.
The allowlist is checked **before** anything is applied. A refusal tells you nothing about the
current values, which is deliberate: deciding afterwards whether a refused field "actually changed
anything" would answer a question about data you may not read.
허용 목록은 무엇이든 적용하기 **전에** 검사한다. 거부는 지금 값에 대해 아무것도 알려 주지 않는다. 일부러 그렇다.
거부한 필드가 「실제로 무언가를 바꿨는지」를 나중에 따지면 읽어서는 안 되는 데이터에 대한 질문에 답하게 된다.
**Pointer permission does not travel upwards.** Permission on `/profile` covers
`/profile/displayName`; permission on `/profile/displayName` does not cover `/profile`, because
replacing the parent deletes every sibling.
**pointer 권한은 위로 올라가지 않는다.** `/profile`에 대한 권한은 `/profile/displayName`을 덮는다.
`/profile/displayName`에 대한 권한은 `/profile`을 덮지 않는다. 부모를 바꾸면 모든 형제가 지워지기 때문이다.
**A `move` needs permission on both ends.** Checking only the destination would let you relocate
data out of a field you may not touch.
**`move`는 양쪽 끝의 권한이 필요하다.** 목적지만 검사하면 건드릴 수 없는 필드의 데이터를 옮겨 낼 수 있다.
**Limits.** At most 100 operations, pointer depth at most 16, merge-patch nesting depth at most 32.
The first two multiply — each operation walks its pointer over a document the server deep-copied
first.
**한도.** 연산은 최대 100개, pointer 깊이는 최대 16, merge patch 중첩 깊이는 최대 32. 앞의 둘은 곱해진다. 연산마다
서버가 먼저 깊이 복사한 문서 위로 pointer를 따라 걷는다.
## Atomicity
## 원자성
A JSON Patch document applies entirely or not at all. Every operation runs against a working copy;
the resource is not touched until all of them have succeeded and the result has passed full
validation.
JSON Patch 문서는 전부 적용되거나 하나도 적용되지 않는다. 모든 연산은 작업 사본에서 돈다. 모든 연산이 성공하고
결과가 전체 검증을 통과하기 전에는 자원을 건드리지 않는다.
This is what makes `test` useful. A client putting a `test` first is relying on nothing after it
having happened when the test fails, and that reliance holds:
그래서 `test`가 쓸모 있다. `test`를 맨 앞에 둔 client는 test가 실패하면 그 뒤의 어떤 것도 일어나지 않았다고 믿고,
그 믿음은 지켜진다.
```json
[
@@ -63,18 +53,16 @@ having happened when the test fails, and that reliance holds:
]
```
A failed `test` is **409**, not 400: the document was well-formed and permitted, and the resource
simply was not in the state you expected. Re-read and retry. The response names the pointer that
failed and does not return the server's value — returning it would make `test` a read primitive for
fields you may not read.
실패한 `test`는 400이 아니라 **409**다. 문서는 형식이 맞고 허락됐지만, 자원이 기대한 상태가 아니었을 뿐이다. 다시
읽고 재시도한다. 응답은 실패한 pointer의 이름을 대고 서버의 값은 돌려주지 않는다. 돌려주면 `test`가 읽어서는 안 되는
필드를 읽는 도구가 된다.
## Validation
## 검증
The patched result is validated as a whole document, not field by field. A patch whose individual
fields are all valid can produce an object that is not — two fields that must agree, a state
transition that is not allowed — and validating only what changed sees none of it.
patch를 적용한 결과는 필드 하나씩이 아니라 문서 전체로 검증한다. 필드 하나하나는 모두 유효한 patch가 유효하지 않은
객체를 만들 수 있다. 서로 맞아야 하는 두 필드, 허락되지 않은 상태 전이 같은 것이다. 바뀐 것만 검증하면 그중 아무것도
보지 못한다.
## Preconditions
## 선행 조건
Patch routes require `If-Match`. A partial update against a resource that moved underneath you
applies your changes to a version you never saw.
patch route는 `If-Match`를 요구한다. 그 사이에 바뀐 자원에 대한 부분 갱신은 본 적 없는 버전에 변경을 적용한다.