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:
+37
-49
@@ -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`를 요구한다. 그 사이에 바뀐 자원에 대한 부분 갱신은 본 적 없는 버전에 변경을 적용한다.
|
||||
|
||||
Reference in New Issue
Block a user