PR 전 리뷰(계약·시험 렌즈, 구조 리뷰) 발견을 고친다. - 상태만 아는 503·429(Spring이 던진 ResponseStatusException 등)가 SERVER_BUSY· RATE_LIMIT_EXCEEDED로 나가면서 Retry-After를 싣지 않았다. error dispatch는 싣는데 handleExceptionInternal은 안 실었다. registry 값을 같은 advisor로 단다. - virtual thread admission filter가 보안 chain 앞이라 cross-origin 거절 503에 CORS 헤더가 없어 브라우저가 본문도 Retry-After도 못 읽었고, 인증 없는 요청도 permit을 썼다. chain 바로 뒤(-99)로 옮겼다. - permit을 한 번만 돌려주는 가드, onTimeout 뒤 onComplete, onStartAsync 재등록을 지키는 시험이 없었다. 둘을 더했다. - stream 위치 규칙이 writer와 WebStreamEvidence 두 곳에 있었다. 증거에 requireNext를 두고 writer가 쓰기 전에 부른다. - fileserver Retry-After가 좁히기 식을 복사했고 SERVER_BUSY 값을 두 번 적었다. ErrorResponseFactory.effectiveRetryable 하나를 같이 쓰고, 공용 이름의 code는 RetryAfterAdvisor 값을 읽는다. 재시도 불가 code 전부가 헤더를 싣지 않는지 본다. - batch 전체 성공의 results[]에 "error": null이 나갔다. 항목 record가 null을 생략한다. batch 시험은 envelope wire 규칙을 실은 mapper로 키 집합을 본다. - 알림 channel·locale 파싱이 두 controller에 있었다. NotificationVocabulary 하나로 모으고, detail은 web 검증 어휘(INVALID)를 쓴다. 예외 이름을 NotificationFieldRejectedException으로 바꿨다(THROWABLES_ARE_NAMED_EXCEPTION). template 게시의 거절 시험을 더했다. - patch 전체 검증 설명에서 상태 전이 예를 뺐다. 검증 대상은 web 표현 DTO이고 업무 규칙은 유스케이스의 것이다. - web README의 RetryAfterHint 예시, upgrade 안내 행 넷(bulk 문구·null 키, stream 역행 항목, 상태만 아는 503·429의 Retry-After, admission filter 순서)과 부분 실패의 part 짚기(index)를 적었다. Refs: RR9-03-01, RR9-03-02, RR9-03-06, RR9-03-13, RR9-03-15, RR9-03-23, RR9-03-24, RR9-03-25, RR9-03-27
4.8 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이 아닌 본문, 빈 문서, 한도 초과, 연산 모양 오류)는 모두 400 PATCH_REJECTED다.
허용 목록 밖의 경로만 403 PATCH_PATH_FORBIDDEN이고, 실패한 test는 409 PATCH_TEST_FAILED다. 너무 깊은 pointer는
권한 문제가 아니라 형식 문제라 400이다.
원자성
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가 유효하지 않은 객체를 만들 수 있다. 서로 맞아야 하는 두 필드가 그런 예다. 바뀐 것만 검증하면 그것을 보지 못한다.
- 두 applier는 서비스의 Bean Validation
Validator를 생성자로 받고, 결과 객체 전체를 검증한 뒤에 돌려준다. 위반은@Valid본문과 같은400 VALIDATION_FAILED와 필드별details다. - 결과가 자원 타입으로 읽히지 않으면(숫자 자리에 문자열)
400 PATCH_REJECTED다. - 검증하는 대상은 web 표현 DTO이고, 제약은 요청 문법이다(web AGENTS B4·C1). 상태 전이처럼 업무 규칙인 검증은 여기서 하지 않는다. 결과를 command로 바꿔 받은 유스케이스가 한다.
선행 조건
patch route는 If-Match를 요구한다. 그 사이에 바뀐 자원에 대한 부분 갱신은 본 적 없는 버전에 변경을 적용한다.