개요
내가 개발한 기능을 쓰는 사람이 Admin 관리자였는데, 개발 과정/구현 내용을 모르다보니 이걸 쓰다가 문제가 생겼다.
- 이 문제의 핵심은 API의 멱등성을 고려하지 않아서 발생한 것
- 또한, 사용자 관점에서 테스트를 진행해야 한다는 깨달음을 얻었다.
API 멱등성이라는 것에 대해 전혀 몰랐고,, 코드 리뷰를 통해 알게 되었다. 따라서 이 포스팅에서는 API의 멱등성에 대해 다루어 앞으로 의식하고 적용할 수 있도록 해볼 것이다!
멱등성(Idempotency)
멱등성은 수학 용어로, 여러 번 연산을 적용해도 결과는 달라지지 않는 성질을 말한다.
한자도 덮을 멱, 무리 등인데 무리(swarm)의 효과를 덮어버린다! 라는 뜻이다.
- 절댓값 함수
- 1을 계속 곱하는 것
HTTP의 멱등성
기본적으로 HTTP 메소드의 GET, PUT, DELETE 와 같은 메서드는 멱등하다.
- 예를 들어, 여러 번 호출해도 GET 은 항상 같은 결과를 보여준다.
- PUT 또한 여러 번의 요청에도, 매번 같은 리소스로 업데이트 한다.
반면, 서버의 데이터를 변경하는 POST, PATCH 와 같은 메서드는 호출을 할 때 마다 요청 데이터, 응답이 달라지기 때문에 멱등하지 않다.
- 이 HTTP Method 요청-응답이 멱등하기 위한 추가 구현이 필요하다.
나의 경우도 POST를 통한 요청이었고, 직접 멱등함을 구현하지 않아서 요청 시마다 값이 달라졌기에, 요구사항에 정확하게 맞지 않는 기능이 개발되었다!
멱등한 POST 요청 API 직접 구현하는 방법들
1) 멱등키 헤더를 사용한다.
간단하게 멱등키를 API 요청 헤더에 포함하면 된다. 서버는 이 멱등키를 통해 같은 멱등키가 2 번 이상 요청되면 중복으로 판단한 뒤, 실제로 처리하지 않는 방식으로 동작한다.
IETF에서 표준으로 제안하는 요청 헤더의 멱등키 는 다음과 같다.
Idempotency-Key: {IDEMPOTENCY_KEY}
결제 취소 API의 멱등성을 구현한 토스 페이먼츠 예시 에서는 결제 취소와 같은 API에 이 멱등성을 제공한다.
결제취소는 POST 요청으로 진행되며, 취소 요청마다 헤더에 멱등키를 담아준다.
- API 서버는 취소 요청마다 헤더에 멱등키가 있는지 확인한다. (이 확인을 통해 키의 중복을 판별하고, 멱등함을 구현하기 위해서다.)
- 멱등키 저장을 위한 DB가 있다. 만약 요청1의 헤더에서 DB에 저장된 멱등키가 발견된다면, 이에 대한 멱등성 보장을 위해 실제 요청을 진행하지 않고 저장된 응답 데이터를 돌려준다. 없으면 새로운 요청이니까 그대로 로직을 수행한다!
const idempotencyResponses = new Map();
let cancelReq = {
orderId: req.body.orderId
amount: req.body.amount,
};
let idempotencyKey = req.headers.idempotencyKey || null // 요청 헤더에서 멱등키를 가져옵니다.
// 멱등키가 있고 멱등 응답도 저장되어 있다면 실제 처리하지 않고 저장된 응답을 내보냅니다.
if (idempotencyKey != null && idempotencyResponses.has(idempotencyKey)) {
const response = idempotencyResponses.get(idempotencyKey);
return res.status(response.status).json(response);
};
const result = cancelProcessor.cancel(cancelReq); // 실제로 취소를 처리합니다.
// 멱등키가 있으면 멱등응답을 저장합니다.
if (idempotencyKey != null) {
idempotencyResponses.set(idempotencyKey, result);
}
const responseBody = {
message: `결제 취소 성공`,
};
return res.status(200).json(responseBody);
서버에서는 위와 같이 요청에 대해서 멱등키를 가져오고, DB에서 확인한 다음, 케이스 분기를 통해 응답을 한다. 깔끔하고 직관적인 구현이라 학습에 많은 도움이 되었다!
2) Entity Tag 사용하기
MDN에서 본 방법인데, 이도 키 헤더를 사용하는 방식과 거의 비슷하다! 특정 URL의 리소스가 변경되면 새로운 Etag를 생성하고, 이들의 비교를 통해 자원이 동일한지 여부를 확인한다.
요청
GET /users/123
응답
HTTP/1.1 200 OK
Etag: "33a64df551425fcc55e4d42a148795d9f25f89d4"
{
"name": "cobinding",
"email": "cobinding@abc.com"
}
If-Match를 통한 Etag 확인
POST /users/123
If-Match: "33a64df551425fcc55e4d42a148795d9f25f89d4"
{
"name": "cobinding123"
}
3) Spring 프로젝트로 간단하게 구현해보기
- Entity 정의
public class Resource {
private Long id;
private String title;
private String content;
private String etag;
public String getEtag() {
return DigestUtils.md5Hex(title + content + lastModified.getTime());
}
}
- POST 수정 요청이 왔을 때 If-Match 헤더와 Etag 비교
@PostMapping("/resource")
public ResponseEntity<Resource> updateResource(@RequestBody Resource resource,@RequestHeader(value = "If-Match", required = false) String ifMatch,
HttpServletRequest request) {
String currentEtag = "\"" + resource.getEtag() + "\"";
if (ifMatch != null && !ifMatch.equals(currentEtag)) {
return ResponseEntity.status(HttpStatus.PRECONDITION_FAILED).build();
}
Resource updatedResource = resourceService.updateResource(resource);
String newEtag = "\"" + updatedResource.getEtag() + "\"";
return ResponseEntity.ok()
.eTag(newEtag)
.body(updatedResource);
}
API를 개발하면서 새로운 개념에 대해 접할 수 있어서 재밌었다. 네트워크를 수강하고 HTTP를 따로 공부도 했지만, 직접적으로 개발하면서 배우는 지식은 훨씬 깊이있고 그 깨달음의 깊이도 다르다고 느껴진다. 앞으로도 개발 프로젝트에 도전하면서 더 깊이있는 학습과 그의 적용을 위해 노력해야겠다.
'Dev > Backend' 카테고리의 다른 글
[BackEnd] 커뮤니티 게시물 목록 조회 API 쿼리를 QueryDsl로 구현해보기 (0) | 2024.10.23 |
---|---|
[Backend] yaml 파일 작성법 (1) | 2024.01.11 |
[BackEnd] 메일 전송 시 CSS 적용(inline 자동 변환기) (0) | 2023.12.21 |
[BackEnd] API 명세서 작성 가이드 라인 | 작성 예시 (0) | 2023.05.05 |
[Backend] RESTful API란, API와 Interface (0) | 2023.03.29 |