API 개발 및 배포 개선안

bluesky·2024년 3월 21일
0

coding

목록 보기
6/6

API 개발 및 배포 개선안

  • 이 글은 제가 팀의 개발 문화를 바꾸기 위해 작성한 글중 일부를 수정한 글입니다.
  • 재밌게 봐주세요!, 혹시 팀에 적용하신다면 참고하셔도 좋을거 같아요.
  • 예시 코드 같은것은 전부 지웠습니다!

목적

  • API 코드 품질 개선
    • 확장하기 용이한 기능 개발과 기능 에러 비율 낮추기위해.

대상

  • 개발 팀

요약

  1. 개발프로세스 : 구현 ->자기 검토 ->PR -> 동료 개발자검토 → 검토사항 반영 으로 개발 진행.(급하게 처리해야하는 이슈 예외.)
  2. 구현시에는 API 구현 가이드를 참고할것. 검토 시에는 개발 체크리스트를 참고하여 코멘트 및 개선을 할것.
  3. branch 관리를 master, develop, feature, hotfix로 관리
  4. 배포 및 gitlab 푸쉬정책을 개선.
  5. 1~4번에 해당하는 내용을 점진적으로 1달 동안 적용. (1회 내용 구두 설명)
  6. 1달 후에는 4가지 사항을 지키면서 개발 작업 진행.

API 개발 환경 설정

API 개발 절차.

  • 요구사항 분석
  • 설계
  • 구현.
    • hotFix : 긴급한 수정건.
    • None hotFix : hotFix가 아닌 건.
      • 아래의 branch 관리 전략을 활용하여 작업을 진행한다.
  • 자기 검토
    • 아래 체크리스트로 자기 검토 및 수정.
  • commit 방법.
    • git commit convention
      • git commit convention은 앞으로 이렇게 관리합니다.
        • 양식 : [type] subject
          • type의 종류
            • feat: A new feature
            • fix: A bug fix
            • docs: Changes to documentation
            • style: Formatting, missing semi colons, etc; no code change
            • refactor: Refactoring production code
            • test: Adding tests, refactoring test; no production code change
            • chore: Updating build tasks, package manager configs, etc; no production code change
        • 참고
          • 두가지 이상 수정시 &로 표시
            • ex) [fix&feat] 내용내용
  • 검토 요청 및 머지.
    • 시급성에 따라
      • hotFix
        • 바로 merge
        • 단 최대한 리뷰를 받는 방향으로 조성
      • None hotFix
        • merge request 요청
          • 아래 참조.
        • 머지는 항상 리뷰인 1명을 선정
  • 정리
    • 작업을 위해 생성한 branch 삭제.
  • 브랜치 관리
  • 참고자료

배포

  • 개발배포
    • develop 브랜치 기준으로 배포를 함.
  • 운영배포
    • main master 기준으로 배포를 함.

Gitlab 푸쉬 정책

  • gitlab 프로젝트 설정을 master랑 develop에 푸쉬하는 권한을 막는것.
    • 코드 및 품질 관리를 위해 필요.

Merge Request 요청 방법

개발 체크리스트.

Clean Code & Quaility

  • 코딩 컨벤션을 지켰는가?(추후 필요시 정의. ex) https://google.github.io/styleguide/javaguide.html )
  • commit 전 확인 되는 코드 issue를(sonarlint나 intellij의 커밋전 warning 참고) 최대한 제거하였는가?(확실한 것만 수정)
  • 주석을 최대한 제거할것.(필요한 설명만 넣을 것)
  • public 및 protected method 구현시 구현 내용이 복잡하거나, deprecated 되었으면 java doc으로 표시하였는가?
  • 요청의 유효성(validation)을 적절히 체크하였는가?
    • path
    • requestParam(queryString)
    • requestBody
  • swagger 설명을 적절히 추가하였는가?
    • summary, description
    • requestDto (설명 및 예시)
    • responseDto (설명 및 예시)
  • API 개발 형식을 지켰는가?
    • 아래 구현 가이드 참고.
  • 하드코딩 된 부분은 없는가? 당장 개선이 불가능 하다면 FIXME 처리를 하였는가?
  • 예외 처리
    • 객체의 역할과 책임의 관점에서 자신이 처리해야 할 예외만 적절히 처리한다.
    • 무분별한 예외처리 금지.

Test code.

  • 필요한 경우 테스트 코드를 추가하였는가?
  • 예시.

Security

  • 보안 위반 사항은 없는가?

Operation Logging

  • 운영시 필요한 정보 확인을 위해 적절히 로깅을 하였는가?
    • (아래 내용 요약)
      • 로깅 레벨을 적절히 사용하자.
        • Error : 서비스 동작에 이상이 있을경우 기록.
          • 반드시 스택트레이스와 콘텍스트가 기록되도록 조치.
        • Warning : 추후 장애로 이어질수 있는 경우 기록.
        • Info : 시스템 동작 상에 특정 작업이 정상적으로 수행되었음을 알려주는 경우
          • 단위작업 완료 후 요약 내용을 기록.
        • Debug : Info 로그에서 기록된 단위 작업의 상세한 단계를 기록합니다. 주로 개발 및 통합 테스트 단계에서 디버깅 용도로 사용
    • https://netmarble.engineering/observability-logging-b/ :
    • 참고 코드

Database schema change

  • DB스키마 변경사항이 있는가? 필요에 따라 개발 및 운영 스키마를 변경하였는가?
    • 해당 페이지에 수정 사항 기록

API 구현 가이드

  • 아래 내용은 권장사항이다.

API 개발 형식

endpoint path 형식

  • endpoint path 형식
    • CSAP 작업 여파로 모든 API를 POST 요청으로 작업해야 함으로 아래 룰을 적용합니다.
    • CRUD각각의 경우 아래와 같이 path 규칙을 정합니다.
      • (적절한 rest api path)/(CRUD에 해당하는 동사)
        • (CRUD에 해당하는 동사) 설명
          • GET 역할하는 api → path/get 형태
          • PUT 역할하는 api → path/put 형태
          • PATCH 역할하는 api → path/patch 형태
          • DELETE 역할하는 api → path/delete형태
          • 기타 특별한 역할하는 api → path/(해당행위를 가장 잘표현하는 동사형태)
    • 참고자료(https://meetup.nhncloud.com/posts/92 )

식

    • HTTP 요청 형식
      • A(가안)
        • 아래에서 설명하는 get, patch, put, delete는 HTTP 메서드보다는 역할 관점을 포괄하여 봐야함.
          • ex)
            • GET 역할 :
            • 1.실제로 HTTP METHOD가 get인 요청.
              1. HTTP METHOD가 POST 요청인데 requestPath/get 형식으로 보내는 요청. 데이터 조회 목적의 요청.
            • POST, PUT, PATCH, DELETE 역할 : 이하 생략.
        • Path variable : 특정한 리소스를 식별할때 쓰자.
          • ex)
            • get, patch, put, delete: 특정 postNo를 대상으로 한 행위일경우 path../{postNo}
            • post : 데이터 생성시는 쓸 일이 거의 없음.
        • request Param(Query parameter) :
          • get 요청시 정렬이나 필터링 조건을 줄때 사용하자.
          • 단 이런 요청시 request Body와 혼용해서 사용할 필요 없음.
            • 예외가 있나 확인 필요.
        • request Body
          • post, put, patch 할경우 수정내역을 전달할때 사용.
        • FAQ
          • projectCd랑 siteId는 뭐로 보내나?
            • Get 또는 delete 요청시는 request Param이용. path variable로는 부적절해 보임.
            • post, patch, put 요청시는 :; request Body로 전달.

요청 바디 처리 CLASS

예외처리

  • business exception (비즈니스상 나타난 예외.) 은 아래의 기준으로 처리한다.
    - 비즈니스 로직에 사용할 예외를 미리 지정하여 사용.

응답 바디 처리 CLASS

  • 응답부 ResultCode<Dto명>의 형태를 이용한다. Map사용 금지.
  • 이것의 예로 이것을 확인한다.

주의

  • 주의
    • map의 사용을 지양한다.
    • 최대한 dto를 생성하여 작업 진행.
    • 사유
      • map사용시 어떠한 value가 사용되는지 추적이 어려움.

참고자료

  • (실제 코드 예시)
    • layered Architecture로 구분된 예시.
    • ResultCode를 사용한 예시.

이슈 처리 원칙.

  • 이슈는 문제를 해결하면서, 예방하기 위한 조치를 같이 진행한다.
    • ex) 특정 파라미터가 빠진 API 호출 시 500에러와 함께 “에러가 발생했습니다.”라고 떴다고 가정해보자.
      • 우선 해당 500에러가 왜 떴을까?
        • 해당 파라미터를 map에서 key로 찾는데 없어서 nullpointerException이였다.
        • 만약 그것이 필수라면requestDto에서 Validation 어노테이션으로 제한을 걸어야하고, 해당 필수를 만족시키지 못했다면, 4XX 번대 클라이언트 대 에러와, 무엇이 빠졌는 지도 같이 나오도록 조치해야 한다.
      • 이렇게 처리한다면 미래에 동일한 현상이 재현되었을때, 사용자가 빠진 파라미터를 인지하고 적절히 수정하여 재호출 할 수 있다.
  • 또한 필요한 경우 팀 내에 문서로 공유할것.

적용 방식.

  • (2/26~3/25)1달동안 적용 시도 및 이슈 처리.
    • 하다가 적절하지 않은 방식은 문서 수정 및 룰 수정.
  • (3/25)~
    • 정식 적용. 추후 API 개발자 올경우 해당 내용 안내.

참고자료

  • 다양한 지침을 확인하는 문서 링크
  • 이슈를 공유할때 볼 문서 링크
profile
bluesky
SMART https://github.com/dongseoki?tab=repositories
이전 포스트

배포 태그의 버전 설정 가이드

0개의 댓글