Backend Convention

1. Template Convention

• Java : Google Java Style Guide
• Python : PEP 8

2. Package Convention

패키지에 대한 컨벤션입니다. 패키지 구조, 패키지 네이밍 컨벤션 등을 결정합니다.

3. HTTP Spec Convention

• HTTP Header, Body 구조 컨벤션입니다.
• 기본적으로 REST API 원칙을 준수합니다.

REST API 설계/문서화

마이크로소프트 RESTful web API design 참고

슬랙이 됐든, 아탈라시안.. 등등 제공하는 오픈 api 문서 참고하면 도움됨(적당한 모방 필요)

https://stripe.com/docs/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/
    • 테스트 코드 기반해서 문서가 자동 생성
    • 강제 테스트 코드 작성 하도록
    • 테스트는 필수적임
    • 단위 테스트 코드를 만드는 연습을 하자
• 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 공격이 올 수도 있음

4. Test Convention

Test_Naming

• 7-popular-unit-test-naming 을 따릅니다.
• MethodName_StateUnderTest_ExpectedBehavior 방식을 따릅니다.
• 예시 : login_unmatchedPassword_fail()

Test Body

마틴 파울러가 제안한 given-when-then 패턴을 채택. 문서 링크

// given

// when

// then

5. Tech Stack

5.1 Language

• JAVA 17
• Python 3.11.1

5.2 DataBase

• postgreSQL 14.6
  • docker image: docker pull postgres:14.6-alpine
• redis 7.0.7
  • docker image: docker pull redis:7.0.7

5.3 Framework

• SpringBoot 3.0
• Django 4.1.5

5.4 Test

• jUnit5, AssertJ
• unittest, coverage.py

5.5 Logging

• Logback
• AWS CloudWatch

5.6 Documentation

• Swagger
• Micro Service 들을 통합할 수 있는 방법을 찾아봐야함. -> API Gateway에서 통합?

5.7 Infra

• Nginx
• docker
• AWS EC2

5.8 ETC

5.9 추후 고려

• Log 분석 (ELK Stack)