-
Notifications
You must be signed in to change notification settings - Fork 0
Backend Convention
박동진 edited this page Jan 22, 2023
·
13 revisions
- Java : Google Java Style Guide
- Python : PEP 8
패키지에 대한 컨벤션입니다. 패키지 구조, 패키지 네이밍 컨벤션 등을 결정합니다.
- HTTP Header, Body 구조 컨벤션입니다.
- 기본적으로
REST API
원칙을 준수합니다.
마이크로소프트 RESTful web API design 참고
슬랙이 됐든, 아탈라시안.. 등등 제공하는 오픈 api 문서 참고하면 도움됨(적당한 모방 필요)
https://www.twilio.com/docs/usage/api/address
https://api.slack.com/methods/admin.apps.requests.list
https://shopify.dev/api/admin-rest/2023-01/resources/discountcode
https://developer.atlassian.com/cloud/trello/rest/api-group-cards/
- REST API 설계의 정답은 없음
- 회사와 조직의 설계 정책을 잘 따라서 설계 해야 함
-
일관 된 설계 정책이 중요
- MSA 에서 API 설계는 일관성이 있어야 클라이언트 입장에서 혼란스럽지 않음
- 글로벌 서비스의 REST API 문서를 참조하는 것은 좋은 습관
HTTP Header의 활용
- Access Token과 같은 전역적인 메타 데이터는 Header 활용 가능
- 데이터를 주고 받을 때는 parameter 활용
- 모든 api에서 사용(access token 같은 것) → header 활용
- Custom Header 활용
이름
- uri, request param, response field 등에서 사용하는 이름 또는 포맷은 일관성 있게 작성
- PascalCase, camelCase, snake_case 모두 사용 가능
- 보통 snake_case 사용
- 파라미터, uri 등에서 사용하는 명사와 동사의 일관성 있는 사용 필요
API 기본 설명(효율적인 협업을 위해)
- 해당 API가 어떤 동작을 하고 무엇을 위해 사용 되는 지 정리
- notion
- 그냥 문서 작성하듯이
- swagger
- 코드에 부가 정보를 넣음
- 자동 문서 생성
- spring Rest Docs(spring)
- https://techblog.woowahan.com/2597/
- 테스트 코드 기반해서 문서가 자동 생성
- 강제 테스트 코드 작성 하도록
- 테스트는 필수적임
- 단위 테스트 코드를 만드는 연습을 하자
- notion
- API 별로 할 때도 있고, 서브 도메인(Customers) 별로 할 때도 있음
Request 파라미터
- 필수 파라미터와 선택 파라미터를 구분한다
- 타입 및 간단한 설명을 추가한다 (Optional)
- 이름이 명확하다면 설명이 필요 없을 수 있음
- 예시 데이터를 제공한다
URL 설계는 다양할 수 있음
- 일관성, 동사가 들어가도 됨, Resource 먼저
다양항 HTTP Verb(Method)를 활용
- GET, POST 말고도 다른 것 사용해도 됨
- 보안 어쩌고 저쩌고 이슈? → 보안팀이 알아서 할 문제
사용법에 대한 부연 설명
- API가 특정 복잡한 비즈니스 도메인에 대한 경우 (optional)
- Usage info(사용 설명서)
HTTP Status Code에 대한 명확한 설명
- 전체 시스템에 공통적인 정책이 설계 되어야 함(API 별이 아님)
- 에러 처리 등..
- 클라이언트는 Status code 먼저 봄
- 대체로 클라이언트 오류 - 400대, 서버 오류 - 500대
Error Code에 대한 명확한 설명
- HTTP Status Code랑은 다름
- 하나의 API에 대해서 시스템이 보내는 메세지
- 잘 적으면 커뮤니케이션 비용을 낮출 수 있음
Response Body의 상세 설명
- 응답 값의 field에 대한 상세 설명 및 예시(Optional)
- 굉장히 긴 경우들이 많음
- 이름으로 표현 가능
- 클라이언트 입장에서 헷갈릴 수 있는 것만 추가적으로 정보를 달아주는 것을 추천
Versioning
- 파라미터나 응답 값이 변경 되는 경우 API 버전을 올림
- 필수 파라미터/응답 값 변경 → 메이저 버전 업(v2)
- 선택 파라미터/응답 값 변경 → 마이너 버전 업(v1.1)
- 대다수는 버전이 존재함
- API Key 발급하는 회사도 존재
- API를 몇 번 호출하는 지 알 수 있음
- API를 누가 호출하는 지 알 수 있음
- 만일 API를 수정할 때, 전 개발팀에 메일을 보내야 됨
- 특정 팀에만 메일을 보낼 수 있음
- Rate limiting
- 클라이언트 별로 API 호출 횟수를 걸어 놓음
- DDOS 공격이 올 수도 있음
- 7-popular-unit-test-naming 을 따릅니다.
-
MethodName_StateUnderTest_ExpectedBehavior
방식을 따릅니다. - 예시 :
login_unmatchedPassword_fail()
마틴 파울러가 제안한 given-when-then 패턴을 채택. 문서 링크
// given
// when
// then
- JAVA 17
- Python 3.11.1
- postgreSQL 14.6
- docker image:
docker pull postgres:14.6-alpine
- docker image:
- redis 7.0.7
- docker image:
docker pull redis:7.0.7
- docker image:
- SpringBoot 3.0
- Django 4.1.5
- jUnit5, AssertJ
- unittest, coverage.py
- Logback
- AWS CloudWatch
- Swagger
- Micro Service 들을 통합할 수 있는 방법을 찾아봐야함. -> API Gateway에서 통합?
- Nginx
- docker
- AWS EC2
- Log 분석 (ELK Stack)