D.CAMP 리뉴얼

h2. DCAMP FRONTEND API 개발 가이드

<pre>

[공통] gitlab-ci.yml before_script 에 encoding UTF-8 설정해줘야 한글 안깨짐!! 

before_script:

- export LANG=en_US.UTF-8

</pre>

1. SecurityConfig 설정(security/config/SecurityConfig.java)

*  securityFilterChain 메소드 - 개발 진행할 URL 에 대한 hasAuthority 룰 추가

<pre><code class="java">

http.csrf().disable()

     .authorizeHttpRequests((authorize) ->

           authorize

               // hasAuthority 사용: db에 ROLE_ 안붙여도 됨

              .requestMatchers("/projects/**").hasAuthority("ADMIN") // 관리자 : ADMIN | 작업자&검수자 : USER

              .requestMatchers("/comCds/**").hasAnyAuthority("ADMIN", "USER") ("ADMIN" or "USER" 둘중 하나만 있어도 될 때 hasAnyAuthority)

              .anyRequest().authenticated()

</code></pre>

2. Swagger 사용

* 설정 파일 위치 : common/config/SwaggerConfig.java (이미 설정되어 있으므로 따로 추가사항 없음)

* 접속 URL : http://localhost:18080/swagger-ui/index.html

login-controller 에서 로그인 후, 응답 토큰을 우상단 Authorized 버튼 클릭해서 입력하면 인증 가능

3. Request URL Naming Rule

* RESTful API 기반 : https://restfulapi.net/resource-naming/

* 1 Depth : 대메뉴(ex, project, user 등등)

<pre>http://api.example.com/user-management/users

http://api.example.com/user-management/users/{id}</pre>

4. DTO 폴더

* 정의 : API 통신용 Request, Response 정의

* Naming Rule : HttpMethod + 대메뉴(복수 or 단수) or 주 사용 테이블 + Req/Res

<pre>

예시)

- GetProjectsReq : 프로젝트 목록 조회 요청

- GetProjectsRes : 프로젝트 목록 조회 응답

- PostProjectReq : 프로젝트 생성 요청

- 애매한 경우는 적당히 클래스명만 보고 가늠할 수 있게 지정해주세요

</pre>

* 공통 DTO 클래스

** CommonRes : 공통 응답필드(result, message) 정의, 상황에 따른 payload 세팅 가능

<pre><code class="java">

@PostMapping

public ResponseEntity<CommonRes> save(@AuthenticationPrincipal UserDetails userDetails, @RequestBody PostProjectReq req) throws Exception {

    Project project = projectService.createProject(req, userDetails);

    CommonRes response = project != null ? new CommonRes() : CommonRes.builder().result(false).message("오류가 발생했습니다.").build();

    return new ResponseEntity<>(response, HttpStatus.OK);

}

</code></pre>

** CommonListRes : 페이징 목록 조회 시 Response 객체로 사용

<pre><code class="java">

@GetMapping

public ResponseEntity<CommonListRes<GetProjectsRes>> list(GetProjectsReq req) throws Exception {

    CommonListRes<GetProjectsRes> response = projectService.list(req);

    return new ResponseEntity<>(response, HttpStatus.OK);

}

</code></pre>

** CommonSearch : 페이징 목록의 검색 시 Request 객체가 상속 받아 사용(페이징 정보 담김)

<pre><code class="java">

@AllArgsConstructor

@NoArgsConstructor

@Setter

@Getter

@EqualsAndHashCode(callSuper = false)

public class GetProjectsReq extends CommonSearch {

    private String projectStatusCcd;

    private String searchType;

    private String searchWord;

}

</code></pre>

** CommonPagination : 페이징 처리를 위해 CommonListRes에서 사용(따로 건드릴 일 없음)

5. Entity 폴더

* 정의 : JPA 에서 사용할 Entity 정의

6. DTO 객체와 Entity 객체 분리 사용

* 이유 : https://wildeveloperetrain.tistory.com/101

* DTO <-> Entity 는 BeanUtils.copyProperties 사용(필드명 일치시켜야함)

<pre><code class="java">

public Project createProject(PostProjectReq req, UserDetails userDetails) {

     Project saveProject = new Project();

     String userId = userDetails.getUsername();

     saveProject.setRegId(userId);

     // DTO <-> Entity 변환

     BeanUtils.copyProperties(req, saveProject);

     saveProject = projectRepository.save(saveProject);

     return saveProject;

}

</code></pre>

7. 현재 로그인한 아이디 가져오기(regId 에 주로 사용)

* Spring security 에서 제공하는 @AuthenticationPrincipal 사용해 CustomUserDetails 객체 가져옴

* userDetails.getUsername() 으로 로그인ID 사용

* customUserDetails.getUserSeq() 으로 로그인한 유저의 seq 값 사용

<pre><code class="java">

@PostMapping

public ResponseEntity<CommonRes> save(@AuthenticationPrincipal UserDetails userDetails, @RequestBody PostProjectReq req) throws Exception {

    // String userId = userDetails.getUsername();

    Project project = projectService.createProject(req, userDetails);

    CommonRes response = project != null ? new CommonRes() : CommonRes.builder().result(false).message("오류가 발생했습니다.").build();

    return new ResponseEntity<>(response, HttpStatus.OK);

}

</code></pre>

8. 검색 조건에 따른 목록 화면

* 일반적인 case : JPA 에서 제공하는 Pageable 활용 (자세한 내용은 Notice(공지사항) 관련 코드를 참고해주세요.)

* 프론트에서 넘겨줘야할 파라미터 목록: pageNumber(현재 페이지 번호, 0 부터 시작), pageSize(페이지 당 행의 개수, default = 10)

<pre><code class="java">

// === controller ===

@GetMapping(produces = MediaType.APPLICATION_JSON_VALUE)

public ResponseEntity<CommonListRes<GetNoticeRes>> list(GetNoticeReq request, Pageable pageable) {

    CommonListRes<GetNoticeRes> response = noticeService.list(request, pageable);

    return new ResponseEntity<>(response, HttpStatus.OK);

}

// === service ===

public CommonListRes<GetNoticeRes> list(GetNoticeReq req, Pageable pageable) {

    Page<Notice> noticePage = noticeRepository.findAllBySearchTypeAndSearchword(req, pageable);

    List<GetNoticeRes> getNoticeResList = entityToDto(noticePage.getContent());

    Long totCnt = noticePage.getTotalElements();

    CommonPagination pagination = req.makePaginationInfo(totCnt != null ? totCnt : 0L);

    return new CommonListRes<>(getNoticeResList, pagination);

}

// JpaRepository를 상속받은 인터페이스에서는 querydsl 코드를 작성할 수 없기 때문에

// querydsl용 custom repository 생성 -> 해당 인터페이스를 구현하는 레포지토리 클래스 추가

// querydsl용 custom repository는 엔티티 레포지토리에서 상속받아 엔티티 레포지토리로 querydsl 메소드에 접근

// === repository ===

@Repository

public interface NoticeRepository extends JpaRepository<Notice, Integer>, NoticeCustomRepository {}

// === customRepository ===

public interface NoticeCustomRepository {

    Page<Notice> findAllBySearchTypeAndSearchword(GetNoticeReq req, Pageable pageable);

}

// === customRepositoryImpl ===

@Repository

public class NoticeCustomRepositoryImpl implements NoticeCustomRepository {

    private final JPAQueryFactory queryFactory;

    public NoticeCustomRepositoryImpl(JPAQueryFactory queryFactory) {

        this.queryFactory = queryFactory;

    }

    @Override

    public Page<Notice> findAllBySearchTypeAndSearchword(GetNoticeReq req, Pageable pageable) {

        List<Notice> notices = queryFactory

                .selectFrom(notice)

                .where(searchWordEq(req.getSearchType(), req.getSearchWord()),

                       notice.delYn.eq("N"))

                .orderBy(notice.regDt.desc())

                .offset(pageable.getOffset())

                .limit(pageable.getPageSize())

                .fetch();

        Long totCnt = queryFactory

                .select(notice.count())

                .from(notice)

                .where(searchWordEq(req.getSearchType(), req.getSearchWord()),

                       notice.delYn.eq("N"))

                .fetchOne();

        return new PageImpl<>(notices, pageable, totCnt);

    }

</code></pre>

* 성능 이슈가 있는 case : Querydsl + 속도 개선을 위한 커버링 인덱스 활용

* 8번 참고 : https://velog.io/@youngerjesus/%EC%9A%B0%EC%95%84%ED%95%9C-%ED%98%95%EC%A0%9C%EB%93%A4%EC%9D%98-Querydsl-%ED%99%9C%EC%9A%A9%EB%B2%95

<pre><code class="java">

public CommonListRes<GetProjectsRes> list(GetProjectsReq req) {

        // 1. Querydsl 동적인 조건 검색을 위한 BooleanBuilder & PathBuilder 사용

        BooleanBuilder builder = new BooleanBuilder();

        builder.and(project.useYn.equalsIgnoreCase("Y"));

        PathBuilder<Project> pathBuilder = new PathBuilderFactory().create(Project.class);

        StringPath path;

        // 2. 검색 조건이 담긴 요청 객체의 필드를 순회 하면서 값이 있으면 조건 추가

        BeanWrapper beanWrapper = new BeanWrapperImpl(req);

        Field[] fields = GetProjectsReq.class.getDeclaredFields();

        for(Field field : fields){

            if("searchWord".equals(field.getName())) {

                continue;

            }

            if(StringUtils.isNotBlank((String) beanWrapper.getPropertyValue(field.getName()))){

                if("searchType".equals(field.getName())){

                    if(StringUtils.isNotBlank(req.getSearchWord())){

                        path = pathBuilder.getString(req.getSearchType());

                        builder.and(path.contains(req.getSearchWord()));

                    }

                } else {

                    path = pathBuilder.getString(field.getName());

                    builder.and(path.equalsIgnoreCase((String) beanWrapper.getPropertyValue(field.getName())));

                }

            }

        }

        // 3. 총 건수 카운트

        Long totCnt = jpaQueryFactory

                .select(pathBuilder.count())

                .from(project)

                .where(builder)

                .fetchOne();

        // 4. 검색 조건이 반영된 ID 리스트 조회

        List<Integer> projectIds = jpaQueryFactory

                .select(project.projectId)

                .from(project)

                .where(builder)

                .orderBy(project.regDt.desc())

                .limit(req.getPageSize())

                .offset(req.getOffset())

                .fetch();

        // 5. 검색된 ID 기반 전체 필드 조회 (속도 개선을 위한 커버링 인덱스 기법)

        List<Project> projects = projectIds.isEmpty()

                ? new ArrayList<>()

                : jpaQueryFactory

                .select(project)

                .from(project)

                .where(project.projectId.in(projectIds))

                .orderBy(project.regDt.desc())

                .fetch();

        // 6. Entity -> DTO

        List<GetProjectsRes> resultList = new ArrayList<>();

        projects.forEach(value -> resultList.add(GetProjectsRes.convertToDTO(value)));

        CommonPagination pagination = req.makePaginationInfo(totCnt != null ? totCnt : 0L);

        return new CommonListRes<>(resultList, pagination);

    }

</code></pre>