문제: 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 등 주석).
4.0 KiB
Web patch: client 계약
patch 형식은 둘이고, 서로 바꿔 쓸 수 없다. 두 applier 모두 adapter:inbound:web-advanced(골라 쓰는 leaf)의 라이브러리
코드다. 서비스가 그 leaf를 더하고 자기 controller에서 JsonMergePatchApplier나 JsonPatchApplier를 부른다.
하나 고르기
route는 정확히 하나만 받고, 다른 것을 보내면 최선의 짐작 대신 415다. 어긋남이 가장 나쁜 방향으로 조용하기 때문이다.
{"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 |
| 모양 | 부분 문서 | 순서 있는 연산 배열 |
| 삭제 | "field": null |
{"op":"remove","path":"/field"} |
| 배열 | 통째로 바꾼다 | index마다 가리킬 수 있다 |
| 선행 조건 | If-Match만 |
If-Match, 그리고 필드별 test |
「이 필드들을 바꿔라」에는 merge patch를 쓴다. 배열 원소를 고치거나, If-Match로 표현할 수 없는 필드 하나의 선행
조건이 필요하면 JSON Patch를 쓴다.
거부하는 것
허용 목록 밖의 필드. 서버가 merge patch가 바꿀 수 있는 필드와 JSON Patch가 가리킬 수 있는 pointer를 선언한다. 그 밖의 것은 거부하고, 거부한 경로는 모두 이름을 댄다. 왕복 한 번에 하나씩 알게 되지 않는다.
허용 목록은 무엇이든 적용하기 전에 검사한다. 거부는 지금 값에 대해 아무것도 알려 주지 않는다. 일부러 그렇다. 거부한 필드가 「실제로 무언가를 바꿨는지」를 나중에 따지면 읽어서는 안 되는 데이터에 대한 질문에 답하게 된다.
pointer 권한은 위로 올라가지 않는다. /profile에 대한 권한은 /profile/displayName을 덮는다.
/profile/displayName에 대한 권한은 /profile을 덮지 않는다. 부모를 바꾸면 모든 형제가 지워지기 때문이다.
move는 양쪽 끝의 권한이 필요하다. 목적지만 검사하면 건드릴 수 없는 필드의 데이터를 옮겨 낼 수 있다.
한도. 연산은 최대 100개, pointer 깊이는 최대 16, merge patch 중첩 깊이는 최대 32. 앞의 둘은 곱해진다. 연산마다 서버가 먼저 깊이 복사한 문서 위로 pointer를 따라 걷는다.
원자성
JSON Patch 문서는 전부 적용되거나 하나도 적용되지 않는다. 모든 연산은 작업 사본에서 돈다. 모든 연산이 성공하고 결과가 전체 검증을 통과하기 전에는 자원을 건드리지 않는다.
그래서 test가 쓸모 있다. test를 맨 앞에 둔 client는 test가 실패하면 그 뒤의 어떤 것도 일어나지 않았다고 믿고,
그 믿음은 지켜진다.
[
{"op": "test", "path": "/version", "value": 4},
{"op": "replace", "path": "/displayName", "value": "new"}
]
실패한 test는 400이 아니라 409다. 문서는 형식이 맞고 허락됐지만, 자원이 기대한 상태가 아니었을 뿐이다. 다시
읽고 재시도한다. 응답은 실패한 pointer의 이름을 대고 서버의 값은 돌려주지 않는다. 돌려주면 test가 읽어서는 안 되는
필드를 읽는 도구가 된다.
검증
patch를 적용한 결과는 필드 하나씩이 아니라 문서 전체로 검증한다. 필드 하나하나는 모두 유효한 patch가 유효하지 않은 객체를 만들 수 있다. 서로 맞아야 하는 두 필드, 허락되지 않은 상태 전이 같은 것이다. 바뀐 것만 검증하면 그중 아무것도 보지 못한다.
선행 조건
patch route는 If-Match를 요구한다. 그 사이에 바뀐 자원에 대한 부분 갱신은 본 적 없는 버전에 변경을 적용한다.