Underdogs Coding Convention - woowacourse-teams/2020-devbie GitHub Wiki

Work Flow - Git & Github

---

1. 브랜치명

1.1. 브랜치 명은 이슈 라벨과 이슈 번호를 조합하여 만든다.

• Branch: feature/#issueNumber-branchName

---

2. PR 및 커밋 단위

2.1. PR과 커밋은 최대한 작은 단위로 쪼갠다.

- 1개의 커밋에는 1개의 행위만 들어 있도록 한다.
- 1개의 PR에는 1개의 작업만 들어 있도록 한다.

2.2. PR은 Issue(feature) 단위로, commit은 의미있는 작업 단위로 한다.

---

3. git flow 예시

Branches
- develop (기능 구현이 완료된 브랜치가 머지되는 브랜치)
- feature/2-login_layout (로그인 레이아웃 작업 branch) // '이슈라벨/이슈번호+이슈제목'

0. 로컬 작업의 시작은 develop 브랜치에서 한다.

1. develop 브랜치에서 origin/develop 브랜치를 pull 한다. (원격 저장소와 동기화)

   git pull origin develop
   

2. develop 브랜치에서 이슈번호와 제목으로 작업 브랜치(feature/2-login_layout)를 생성한다.

   git checkout -b feature/2-login_layout
   

   • 작업 브랜치의 첫번째 키워드는 해당 이슈에 해당하는 키워드로 한다.
     • feature : 기능 개발
     • refactor : 리팩토링
     • bugfix : 버그 수정
     • docs : 문서 작업

3. 작업 브랜치에서 소스코드를 수정한다.

4. 작업 브랜치에서 변경사항을 commit한다.

5. 만약 커밋이 불필요하게 어려 개로 나뉘어져 있다면 squash를 한다. (커밋 2개를 합쳐야 한다면)

6. 작업 브랜치를 origin에 push한다.

   git push origin feature/2-login_layout
   

7. Github에서 feature/2-login_layout 브랜치를 develop에 merge하는 Pull Request를 생성한다.

   • 만약 충돌이 나서 PR을 보낼 수 없다면 로컬의 작업 브랜치로 돌아와 1번에서 했던 작업을 해준다.
   • 원격 저장소와 동기화

   git pull origin develop // 충돌 나면 해결 후 add,commit
   

8. 같은 feature를 개발하는 동료에게 리뷰 승인을 받은 후 자신의 Pull Request를 merge한다.

9. merge된 브랜치는 삭제한다. (local, upstream)

   git branch -D feature/2-login_layout
   

10. 1번 부터 다시 반복

---

4. 커밋 컨벤션

• docs: 문서 작성 및 수정
• feat: 새로운 기능 추가 (테스트 코드 포함)
• fix: 버그 수정
• perf: 성능 개선
• refactor: 리팩토링 → feat(새로운 기능 추가), fix(버그 수정) 제외
• style: 코드 포맷, 디자인 변경 (white-space, formatting, missing semi-colons, etc)
• test: 기존 테스트 코드 수정 또는 빼먹은 테스트 추가 (Adding missing tests or correcting existing tests)
• build: Changes that affect the build system or external dependencies (example scopes: gulp, broccoli, npm)
• ci: Changes to our CI configuration files and scripts (example scopes: Circle, BrowserStack, SauceLabs)

참고 - Angular Commit Format

---

AWS 배포 서버

• EC2
• master : 보스독 계정
• develop : 소니 계정

코딩 스타일

1. Frontend

1.1. ESLint

• eslint-config-vue 패키지가 제공하는 기본 컨벤션을 따름 vue style guide

1.2. Prettier

• arrowParens : avoid

1.3. 추가 플러그인

• "no-loops" : 반복문 사용 시, 경고를 띄운다.

1.4. 커스텀 스타일 규칙

• vue hook 과 연관된 함수들은, es5 버전을 적용한다. funtion() { ... }
• Lambda의 경우는 arrow function을 사용한다.

2. Backend

• 네이버 핵데이 코딩 컨벤션 스타일을 따른다.
• 단, tab character는 사용하지 않는다.

---

Backend - 자바/Spring

1. configuration

• 서버 포트는 9000으로한다.
• 서버를 거치는 api url은 prefix로 /api/~ 를 붙인다.

---

2. 인증/인가

2.1. Oauth 앱은 Github으로 한다.

2.2. client_id와 client_secret는 application-admin.yml에 놓고 원격 저장소에는 올리지 않는다.

2.3. JwtToken의 Payload에는 user의 id 값만 사용한다.

2.4. 인증 프로세스는 다음 순서를 따른다.

인증 프로세스

1. server로 Github Login url을 요청한다. (https://github.com/login/oauth/authorize?client_id=client_id")
2. Github에서 인증 받은 후, redirect url로 이동한다. (http://localhost:8080/login)
3. code값을 포함하여 server로 로그인 요청(post)을 보낸다. (http://localhost:8080/api/oauth/login)
4. 전달받은 code값과 client_id, cliendt_secret을 포함하여 server단에서 Github로 비동기 요청을 보낸다. (https://github.com/login/oauth/access_token)
5. Github으로부터 access_token을 전달받고, 토큰을 사용해서 userInfo를 조회한다. (https://api.github.com/user)

---

3. 예외처리

3.1. 최상위 커스텀 예외 클래스는 RuntimeException을 상속받는다.

3.2. Error Message는 클래스 안에 정의한다.

public class UnderdogsCustomException() extends RuntimeException {
    
    public UnderdogsCustomException() {
        super("예외가 발생했습니다.");
    }
}

---

4. Lombok

4.1. 어노테이션은 중요도 순으로 작성한다. 중요도 순서는 다음과 같다.

• spring annotaion
• jpa annotation
  • entity
  • embeddable
  • table
  • 중요도 스스로 판단
• lombok annotaion
  • contstructor(no -> required -> all)
  • builder
  • getter
  • setter
  • toString
  • EqualsAndHashCode
• controller, service: RequiredArgsConstructor
• request_dto
  • NoArgsConstructor(access = PROTECTED)
  • AllArgsConstructor(access = PRIVATE)
  • static factory method
  • 매개변수가 2개 이상일 경우는 builder 사용
• response_dto
  • NoArgsConstructor(access = PROTECTED)
  • AllArgsConstructor(access = PRIVATE)
  • static factory method
  • 매개변수가 2개 이상일 경우는 builder 사용

@Entity
@NoArgsConstructor(access = ACCESSOR.PROTECTED)
@Builder
@Getter
@ToString
public class AbcEntity {
    ...
}

---

5. 매개변수

5.1. 메소드 매개변수는 3개를 넘기지 않는다. (3개까지 허용)

5.2. 매개 변수의 길 경우 다음 예시처럼 줄을 바꿔 포매팅해준다.

@GetMapping("/{id}")
public ResponseEntity<RoomResponse> getFilterdRoom(
    @PathVariable("id") Long id,
    @RequestBody RoomRequest request
) {
    ...
    
}

---

6. 클래스 패키지

6.1. 최대한 도메인 주도 설계 방식을 따른다.

  underdogs.devbie
   |
   |
   |-auth
   |   |--controller
   |   |--service
   |   |--oauth
   |
   |-user
   |   |--controller
   |   |--service
   |   |--domain
  
    ...

6.2. exception, dto 패키지는 각 aggregate 별로 하위에 위치한다.

  underdogs.devbie
   |
   | ...
   |
   |-user
   |   |--controller
   |   |--service
   |   |--domain
   |   |--exception   **
   |   |--dto         ** 
  
     ...

6.3. config 패키지는 root 디렉토리에 위치한다.

---

7. 디미터의 법칙 (.)

7.1. 객체간 get 메서드를 연쇄적으로 사용하지 않는다.

7.2. 각 객체가 스스로 일할 수 있도록 메시지를 던지는 방식으로 해결한다.

  (x) Station station = line.getLineStations().getStation();
      station.updateName("abcd");
    
  (o) lineStation.updateStationName("abcd");

---

8. 람다식 표현

8.1. 리턴하는 변수명과 람다식에 사용하는 변수명이 겹칠 거나, 큰 의미가 없는 변수일 경우 한 글자를 허용한다.

  User user = userRepository.findByOAuthId(userInfoResponse.getId())
                .map(u -> u.updateOAuthInfo(userInfoResponse))
                .orElse(userInfoResponse.toEntity());

---

9. JPA

9.1. 레파지토리는 JpaRepository를 사용한다.

9.2. @repository 어노테이션은 붙이지 않는다.

9.3. spring data jpa의 name function을 쓰기 위해서는 Entity의 field명을 반드시 camel case로 작성한다.

(x) private String oAuthId;

(o) private String oauthId;

---

10. 로깅

10.1. 모든 컨트롤러와 서비스 메서드가 수행될 때 로깅한다.

• 각각은 다음 내용을 포함한다.
• controller : className, methodName, httpMethod parameters, logTime, requestUri
• service : className, methodName, parameters, logTime

[INFO ] 2020-07-29 20:38:52.092 [http-nio-auto-1-exec-8] ServiceLoggingAspect - params : {method=saveWithoutOAuthId, service=UserService, params=[UserCreateRequest([email protected])], log_time=2020-07-29T20:38:52.092+0900}
[INFO ] 2020-07-29 20:38:52.095 [http-nio-auto-1-exec-8] ControllerLoggingAspect - params : {controller=UserController, http_method=POST, method=saveUser, params={}, log_time=2020-07-29T20:38:52.095+0900, request_uri=/api/users}

---

11. API 문서

11.1. **Spring REST Docs**를 사용한다.

11.2. API에 포함되는 내용은 다음과 같다.

---

테스트

1. DisplayName

1.1. DiplayName은 서술형이 아닌 개괄식으로 적는다.

x - @DisplayName("jwt 토큰 생성한다.")  

o - @DisplayName("jwt 토큰 생성")

1.2. DisplayName 어노테이션은 가독성을 고려하여 가장 상단에 위치한다. (나머지 어노테이션은 위에서 부터 중요도 순으로 나열한다.)

@DisplayName("abc 테스트")
@Test
void abcTest() {
...
}

---

2. Annotation

2.1. Controller Test는 @WebMvcTest를 통해서 한다.

2.2. Service는 MockitoExtension을 사용하여 Mock Test를 적용한다.

---

3. Mockito

3.1. BDD mockito style을 따른다.

@DisplayName("abc 테스트")
@Test
void abcTest() {
    given(~~).willReturn(~~)
}

3.2. any()를 사용할 경우 타입이 명시된 것을 사용한다.

• anyString(), anyLong() ...

3.3. @MockBean vs @Mock

• controller에서 service를 Mock으로 사용할 때는 @MockBean을 사용한다.
• service 혹은 다른 클래스에서 Mock 객체를 사용할 때는 @Mock을 사용한다.

---

4. 패키지 테스트

4.1. 외부 라이브러리는 테스트하지 않는다.

4.2. Domain 영역은 TDD로 구현하되 Instruction coverage가 80%이상이 되도록 한다. (Jacoco 설정)

• 추후 수정

---

5. 테스트 픽스처

5.1. 테스트 픽스처는 되도록 해당 메서드 안에 작성한다.

• 중복되는 픽스처가 과하게 많아질 경우에만, @BeforeEach로 추출한다.

---

6. AssertJ

6.1. 하나의 테스트는 하나의 속성만 테스트한다.

• 관련된 여러 속성을 한번에 검증할 경우 assertAll()을 사용한다.

@DisplayName("abc 테스트")
@Test
void abcTest() {
    assertAll(
            () -> assertEquals(1L, user.getId()),
            () -> assertEquals(TEST_OAUTH_ID, user.getOauthId()),
            () -> assertEquals(TEST_USER_EMAIL, user.getEmail())
        );
}