mute_bear #_#

[Develop] RESTful API

mute_bear :) — Sat, 8 Jun 2024 16:40:10 +0900

웹서버를 만들면서, 클라이언트와 데이터를 주고받는 API를 작업했다. 클라이언트에서 요구하는대로 API를 작업하고 테스트를 하면서, 웹 API의 베스트 프랙티스를 찾아보았다. 아래 링크에서 도움을 많이 받고 내용을 정리하려한다.

Refrence

https://learn.microsoft.com/ko-kr/azure/architecture/best-practices/api-design

웹 API 디자인 모범 사례 - Azure Architecture Center

플랫폼 독립성과 서비스 발전을 지원하는 웹 API를 디자인하기 위한 모범 사례를 알아봅니다.

learn.microsoft.com

https://www.redhat.com/ko/topics/api/what-is-a-rest-api

REST API, RESTful API, 레스트풀 API란? 개념과 특징 탐색

REST API란 분산된 하이퍼미디어 시스템을 위한 소프트웨어 아키텍처이며, 리소스를 고유한 URI로 표현하고 정형화된 HTTP 메서드를 사용한 수행 방식으로 동작합니다.

www.redhat.com

1. API 설계 원칙

1. API의 명확한 목적을 정의한다.

설계하려는 API의 목적, 가치를 명확하게 정의하고, 설계해야한다.

2. 일관성을 유지한다.

설계하려는 모든 API에서 일관된 스타일, 형식, 규칙을 적용해야한다.

3. 표준화된 프로토콜을 사용한다.

HTTP, HTTPS 등 표준 프로토콜을 사용하여, 상호 운용성을 보장해야한다.

4. RESTful API 설계

RESTful 설계를 따르고, 리소스 기반의 접근 방식을 사용해야한다.
URI를 통해 리소스를 명확하게 표현하고, HTTP 메서드를 이용하여 작업을 수행해야한다.

*HTTP Method : GET, POST, PUT, DELETE 등

REST는 Representational State Transfer의 약자로, 웹 아키텍처 스타일을 말한다. RESTful API는 REST 스타일로 제약 조건을 준수하고 서비스와 상호작용할 수 있도록 하는 API다.

2. API 설계 모범 사례

1. 명확한 URI 설계

리소스를 식별할 수 있는 명확하고 직관적인 URI를 설계합니다.
예: /users/{userId}/orders/{orderId}

2. HTTP 메서드의 올바른 사용

GET: 리소스 조회
POST: 새로운 리소스 생성
PUT: 기존 리소스 업데이트
DELETE: 리소스 삭제

3. 상태 코드 사용

적절한 HTTP 상태 코드를 사용하여 클라이언트가 요청의 결과를 쉽게 이해할 수 있도록 합니다.
예: 200 (성공), 201 (생성됨), 400 (잘못된 요청), 404 (찾을 수 없음), 500 (서버 오류)

4. API 버전 관리

API의 변경 사항을 관리하기 위해 버전 관리를 도입합니다.
URI 경로에 버전을 포함하는 방식(예: /v1/)을 권장합니다.

5. 페이징, 필터링, 정렬

많은 데이터를 반환하는 경우 페이징을 지원하여 응답 크기를 줄입니다.
필터링과 정렬 기능을 제공하여 클라이언트가 원하는 데이터를 효율적으로 검색할 수 있도록 합니다.

6. 보안

HTTPS를 사용하여 데이터 전송을 암호화합니다.
OAuth2와 같은 인증 및 권한 부여 메커니즘을 사용하여 API 접근을 제어합니다.

7. 문서화

API 문서를 작성하여 개발자가 API를 쉽게 이해하고 사용할 수 있도록 합니다.
Swagger(OpenAPI)와 같은 도구를 사용하여 인터랙티브한 문서를 제공할 수 있습니다.

8. 테스트와 모니터링

API 테스트를 자동화하여 안정성을 높이고, 문제 발생 시 빠르게 대응할 수 있도록 합니다.
API의 사용량과 성능을 모니터링하여 지속적으로 개선합니다.

[Develop] Spring initializr 사용하기

mute_bear :) — Thu, 23 May 2024 17:15:27 +0900

https://start.spring.io

신규 프로젝트 백엔드 구성을 위해 스프링부트 프레임워크를 선택했다. 새로운 프로젝트 디렉토리를 구성해야 했는데, 스프링 공식 홈페이지에 "spring initializr"라는 좋은 툴이 있었다. 새로운 프로젝트 디렉토리를 구성할 때, 선택할 수 있는 빌드 도구, 개발 언어, boot 버전, 메타데이터를 기입하여 자동으로 만들어주는 툴이다. 스프링부트를 이용한 신규 프로젝트를 진행할 때, 다시 사용할 수 있도록 기록을 남겨놓는다.

1. Project 섹션

현재 Project 섹션에 선택할 수 있는 항목은 세가지다. Gradle-Groovy, Gradle-Kotlin, Maven.
구성하려는 프로젝트의 빌드 툴을 고를 수 있다. gradle이냐 maven이냐 선택함에 따라 프로젝트 하위에 구성되는 파일이 달라진다.

나는 gradle을 주로 사용했기에, gradle-kotlin을 골랐다.

2. Language 섹션

Language 섹션은 개발 언어를 선택하게끔 되어있다. 개발 언어는 Java, Kotlin, Groovy 세가지 항목으로 구성되어있다.
나는 Kotlin으로 주로 개발을 진행하고 있기에, Kotlin 항목을 고른다. 1번 항목에서 고른 항목을 개발 언어에 맞추어서 변경해준다.

Groovy는 사용해보지 않았기에, Gradle 구성이 어떻게 다른지는 나중에 찾아봐야겠다.

3. SpringBoot 섹션

SpringBoot 섹션은 사용하려는 SpringBoot의 버전을 고를 수 있다. 현재 보이는 항목으로는 3.x ~ 이상 버전들이 많이 보인다. SNAPSHOT과 RC1으로 괄호로 감싸져있는 버전들도 있다.
RC1은 Release Candidate1으로, 정식 릴리즈 전에 배포되는 예비 버전이다.(기능 구현은 완료, 테스트 및 버그 수정을 거치고 있는 단계)
SNAPSHOT은 정식 릴리즈 버전이 아니라 개발 중인 미완성 버전을 말한다.(새로운 기능 추가 및 버그 수정이 실시간으로 반영됨)

프로젝트의 dependency 문제 및 안정성 때문에 stable한 버전으로 사용하는 것을 나는 선호한다.

stable 버전인 3.1.11로 선택했다.(괄호 없는 것)

4. Project Metadata 섹션

프로젝트 메타데이터를 기입하는 섹션에는 아래와 같은 내용을 기입할 수 있다.

4-1. Group

4-2. Artifact

4-3. Name

4-4. Description

4-5. Package name

4-6. Packaging Type (Jar, War)

4-7. Java Version (22, 21, 17)

Project Metadata 기입

위와 같이 메타데이터를 기입하고 하단의 GENERATE를 누르면 zip 파일이 다운로드 된다.

우측의 Dependencies 섹션에서는 사용할 의존성을 검색하여 추가할 수 있다. boot devTools 같은건 넣어주고, 의존성은 추후 추가할 수 있으니 패스.

zip파일

간단한 project 디렉토리가 완성되었다. 선택한 옵션대로 잘 만들어주는 spring initializr 정말 유용하다. gitignore 등을 추가하고 신규 프로젝트를 시작할 수 있겠다.

[Develop] javascript jquery 데이터테이블 플러그인 DataTables - table plugin

mute_bear :) — Mon, 11 Dec 2023 19:20:24 +0900

DataTables는 jquery 라이브러리로, 웹 개발에서 흔히 만들게되는 테이블을 간단하게 만들어주는 녀석이다. 최근 진행한 프로젝트에서 게시판 형태의 테이블이 주된 요소가 되는 화면을 여럿 개발하면서 배운 점을 정리하려고 한다. 통계 및 목록화면을 구성할 때, 가져와야하는 데이터 양이 많지 않다면, 사용하는 것도 좋겠다.

1. DataTables

https://datatables.net/

DataTables | Table plug-in for jQuery

DataTables Table plug-in for jQuery Advanced tables, instantly DataTables is a plug-in for the jQuery Javascript library. It is a highly flexible tool, built upon the foundations of progressive enhancement, that adds all of these advanced features to any H

datatables.net

공홈 링크다. 매뉴얼 및 공식 문서와, 검색 기능을 제공한다. "Save Time, do more" 공홈에 적힌 소개 문구이다. 정말 마음에 든다. 테이블을 만들어내려면 html, css, js를 모두 손봐줘야하고, 테이블만 만들면 끝이냐? 그것도 아니다. 서버단에서 목록 데이터를 어떻게 넘겨주는지도 정해야하고, 페이지네이션, 각 필드별 정렬기능, 전체 데이터 개수, 데이터 검색 기능, 데이터 렌더링 시에 텍스트 변환... 벌써 머리가 아프다.

하지만 DataTables를 이용하면, 모두 간편하게 해결 가능하다. 차근차근 사용법을 알아보자.

2. 파일 추가

<head>
    <link rel="stylesheet" type="text/css" href="https://cdn.datatables.net/v/bs5/dt-1.13.2/datatables.min.css"/>
</head>

현재 프로젝트의 HTML 파일에 데이터테이블즈 사용을 위한 css 파일을 <head>에 추가해준다.

<script>
    <script type="text/javascript" src="https://code.jquery.com/jquery-3.6.3.min.js"></script>
    <script type="text/javascript" src="https://cdn.datatables.net/v/bs5/dt-1.13.2/datatables.min.js"></script>
</script>

현재 프로젝트의 HTML 파일에 데이터테이블즈 사용을 위한 js 파일을 <script>에 추가해준다.

<table style="width: 100%;" class="test_table">
    <thead>
        <tr class="test_table_thead">
            <th>No</th>
            <th>이름</th>
            <th>전화번호</th>
            <th>주소</th>
        </tr>
    </thead>
    <tbody></tbody>
</table>

HTML 파일에 간단한 형태의 테이블을 만들어준다.

$(function () {
    $(".test_table").DataTable({
        info: false, // 테이블 데이터 정보 표시 여부
        paging: true, // 페이지네이션 기능 사용 여부
        lengthChange: false, // 한 페이지에 노출할 데이터 개수 설정 버튼 노출 여부
        pageLength: 40, // 한 페이지에 노출할 데이터 개수 설정
        searching: false, // 데이터 검색 기능 사용 여부
        scroller: true, // 테이블 스크롤 사용여부
        scrollY: "70vh", // 테이블 스크롤 Y축 길이 설정
        processing: true, // 커스텀 로딩중(?) 사용
        stateSave: true, // 상태 값 저장 여부
        order: [0, 'desc'], // 데이터 정렬 (index, direction)
        columns: [
          { data: "index" },
          { data: "name" },
          { data: "phone" },
          { data: "address" },
        ],
        language: { // 언어 설정
            paginate: { previous: "이전", next: "다음" },
            emptyTable: "데이터가 없습니다.",
            processing: '<div class="spinner"></div>',
        },
        ajax: {
          url: "/api/users",
          type: "GET",
        },
        rowCallback: function (row, data, index) { // 렌더링 후 사용할 콜백함수
        },
    });
});

HTML에 적용될 javascript 파일을 작성해준다. 주석에 적혀있는 내용을 참고하여 입맛대로 테이블 옵션들을 설정해준다. 데이터는 jquery ajax call로 서버단에서 데이터를 가져온다.

* 주의사항은 columns에 사용하려고 선언된 필드와 HTML에서 작성한 <th> 태그 개수가 일치해야한다. 또한, 서버단에서 데이터를 넘겨줄 시, 키 값으로 data를 사용해야한다. ex) { data: [] }

3. 잡기술

테이블 새로고침이 필요할 시,

$(".test_table").DataTable().ajax.reload();

반응형 필요 시, 데이터 테이블 옵션에 아래 옵션 추가

responsive: true,

테이블 필드 width 설정

columns: [
    { width: "70px", data: "name" },
],

[Develop] AWS 시작하기 - 회원가입부터 EC2 인스턴스 생성

mute_bear :) — Fri, 1 Dec 2023 20:01:11 +0900

최근, 개발용 서버가 필요하여 aws계정 회원가입 및 EC2 인스턴스를 생성하였다. aws 회원가입부터 EC2 인스턴스 생성 및 프리티어로 사용하는 법을 작성해 보겠다.

1. 회원가입

https://aws.amazon.com/ko/console/

AWS Management Console

AWS Support 플랜은 AWS로 성공하는 데 도움이 되는 다양한 도구, 프로그램 및 전문 지식에 대한 액세스의 조합을 제공합니다.

aws.amazon.com

위의 링크를 타고 들어가면 로그인 화면이 나올 텐데 AWS 계정 새로 만들기를 눌러 회원가입 화면으로 진입한다.

첫 회원가입 화면에서는 이메일 인증을 진행하면 된다. 이메일은 인증 가능한 유효한 이메일을 기입하도록 하자.
이메일 인증을 마치면, 비밀번호를 설정하고 2번째 스텝으로 넘어간다.

2번째 스텝에서는 전화번호, 국가, 주소 등을 기입한다. 국가코드 선택 등 "ko"만 검색해도 나오니 찾지 말고 ko입력하면 된다.

3번째 스텝에서는 결제 정보 기입으로 카드가 필요하다. 카드는 visa, master 등 해외 겸용카드로 준비하자.

카드 정보 기입 후, 카드 비밀번호로 인증까지 마치면 확인 차 100원이 결제되고 취소된다.

4번째 스텝에서는 핸드폰 번호 문자인증이다. 핸드폰 번호 입력 후 문자가 수신되면, 해당 코드를 입력해 주면 된다.

문자 인증까지 마치면, 서비스플랜을 선택하라는 화면이 보일 것이다. 우리는 무료 서비스를 이용하길 원하니! Basic support - free를 선택하고 회원가입을 마치자. 회원가입을 마치고 콘솔로 이동버튼을 누르면, 다시 로그인하라는 화면이 나온다.

루트 사용자 선택(default)된 것 확인하고, 회원가입한 계정정보로 로그인해 보자.

무언가 어려워 보이는 콘솔 홈이 등장했다. 우측 상단을 보니, 리전 설정이 서울로 잘 되어있다. (ap-northeast-2)

여기까지 절반 왔다.

2. EC2 인스턴스 생성

aws는 엄청 많은 서비스를 제공하고 있다. 나는 그중에서도 관리 및 거버넌스의 CloudWatch, 데이터베이스의 RDS와 컴퓨팅의 EC2 항목을 주로 사용한다. 물론, 클라우드 재무관리의 결제 및 비용 관리도 중요하다!

- 공식문서의 EC2 how to get started 링크
https://docs.aws.amazon.com/ko_kr/AWSEC2/latest/UserGuide/concepts.html#how-to-get-started

Amazon EC2란 무엇인가요? - Amazon Elastic Compute Cloud

이 페이지에 작업이 필요하다는 점을 알려 주셔서 감사합니다. 실망시켜 드려 죄송합니다. 잠깐 시간을 내어 설명서를 향상시킬 수 있는 방법에 대해 말씀해 주십시오.

docs.aws.amazon.com

EC2는 Elastic Compute Cloud로 aws의 클라우드 컴퓨팅 서비스를 말한다. 쉽게 말해 나는 전기세를 먹지 않고(?) 내 방 공간을 차지하지도 않는 컴퓨터를 빌리는 개념이다. 전기세 대신 사용 요금이 부과되겠지만.. 나는 가상 컴퓨터를 빌려 원격으로 해당 컴퓨터에 구성하고자 하는 환경을 구축하고, 애플리케이션을 구동할 수 있다. 컴퓨터를 켜고 끄는 것, 시스템 모니터링, 비정상 동작 체크 등등 원격으로 컨트롤할 수 있는 요소들이 많이 있다.

콘솔 홈 화면에서 보이는 주황색 EC2를 선택하자. 리소스 항목에서 아시아 태평양(서울) 리전을 다시 한번 확인하자..

실행 중인 인스턴스는 0이라고 나온다. 주황색 인스턴스 시작을 눌러보자.

태그는 인스턴스가 많아질 경우, 검색 용도로 용이하게 사용된다. 내가 무슨 인스턴스인지 바로 알아볼 수 있는 값을 넣어주자.

하단의 AMI 항목은 내가 빌리려는 가상 컴퓨터의 os를 선택할 수 있다. 나는 default인 Amazon Linux 선택! ("프리 티어 사용 가능"이라고 적힌 항목을 선택해야 한다..)

AMI 선택 후, 하단에는 인스턴스 유형을 선택하라고 한다. 무료로 사용할 것이기 때문에 "t2.micro"로 선택. (선택되어 있음)

키 페어는 인스턴스 vm 접속을 위한 인증서다. 키 페어 없이 계속 진행을 선택하여도 console로 root 접속하여 설정 바꾸고 유저 추가하고 진행하는 방법이 있는데, 권장되지 않는 방법이니 진행하지 말자. 추천하는 방식대로 인증서를 만들어보자.

나는 ssh를 사용하므로, pem 파일을 많이 사용한다. 키 페어 생성 버튼을 누르면 바로 highgw.pem 파일이 다운로드 받아진다.

해당 파일은 잃어버리면 안 되니 잘 보관해 놓자!!!! (★★★★★★★★)

키 페어 생성 후, 하단에는 네트워크 설정 및 스토리지 구성 항목이 있다. 나처럼 테스트 및 간단한 개인 개발 용도로 사용한다면, 위의 설정을 따라가도 크게 문제없을 것이다. 고급 세부 설정은 건너뛰고 인스턴스를 시작하면 인스턴스가 생성되었다.

이후에 인스턴스 설정 항목에서 고정 IP 할당 및 종료, 중지 방지 및 복구 설정 등을 진행해야 하지만, 건너뛰고 인스턴스 항목 우클릭 후 연결 버튼을 누르면 vm 접속이 가능하다. EC2 인스턴스 연결을 진행해도 되고, 직접 terminal에서 ssh로 접속도 가능하다.

EC2 인스턴스 연결 선택

ssh로 접속하는 방법은 terminal에서..

ssh -i ${다운로드된 .pem 파일} ${user}@${ip}

yes 입력 후, 요 에러가 발생하면 인증서 파일 권한 변경해줘야 합니다.

chmod 400 highgw.pem

입력 후, 위의 ssh 명령어 다시 시도하면

첫 접속 성공!!! 스토리지는 20퍼 정도 먹고 있네요.

t2.micro 유형이니 간단한 웹서버 하나 띄워볼 수 있겠습니다.

- 공식문서의 EC2 자습서 링크

https://docs.aws.amazon.com/ko_kr/AWSEC2/latest/UserGuide/EC2_GetStarted.html

자습서: Amazon EC2 Linux 인스턴스 시작 - Amazon Elastic Compute Cloud

키 페어 없이 진행(권장하지 않음)(Proceed without a key pair (Not recommended))을 선택하지 마세요. 키 페어 없이 인스턴스를 시작하면 인스턴스에 연결할 수 없습니다.

docs.aws.amazon.com

[Develop] 네이밍(Naming) 문법 정리

mute_bear :) — Thu, 30 Nov 2023 13:25:05 +0900

Style Guide(Naming Convention)

개발을 진행하면서 어려운 일 중 하나인 네이밍에 관해 정리해보고 싶었다.

진행한 여러 프로젝트를 찬찬히 살펴보니, 똑같은 js 코드를 작성하는데 네이밍이 일정하지 않고, 뒤죽박죽인 것이 보인다..

여러 명이 함께 협업하는 프로젝트일수록, 일관된 네이밍 규칙을 가져가는 것이 코드 가독성이나, 커뮤니케이션을 위하여 필수적이라고 생각한다.

style guide 요소 중 하나인 네이밍은 말 그대로 이름을 짓는 것이다. 개발을 진행하면서 변수, 상수, 함수 등등 수많은 친구들의 이름을 지어주어야 한다. 흔히 사용할 것 같은 변수인 "유저리스트"를 이용하여 예시를 써보자.

var userlist;
var userList;
var Userlist;
var UserList;
var user_list;
var user-list;

한눈에 보이듯, 같은 의미지만 단어를 표기하는 방법은 다양하다.

개발에서 이름을 지어주는 대표적인 방법은 카멜식, 스네이크식, 케밥식, 파스칼식 등이 있다.

1. camel case

카멜식(camel case)은 낙타를 떠올리면 쉽다. 낙타의 등 모양에서 따왔다고 하며 표현식은 다음과 같다.

var userList;

첫 시작은 소문자, 뒤로 구분되는 단어는 대문자로 시작한다. lowerCamelCase라고도 한다.

2. snake case

스네이크식(snake case)은 뱀을 떠올리면 쉽다. 언더바를 이용하며 표현식은 다음과 같다.

var user_list;

소문자로만 작성하며, 구분되는 단어 사이에 _(언더바)를 사용하며 작성한다.

3. kebab case

케밥식(kebab case)은 케밥에 꼬챙이를 끼운 모양이라고 한다. 표현식은 다음과 같다.

var user-list;

소문자로만 작성하며, 구분되는 단어 사이에 -(하이픈)을 사용하며 작성한다.

4. pascal case

파스칼식(pascal case)은 카멜식과 비슷하지만, 첫 단어를 대문자로 시작한다. (UpperCamelCase라고도 한다.)

var UserList;

style guide의 예시로 링크를 남긴다. Google Javascript Style Guide

Google JavaScript Style Guide

google.github.io

위와 같이 네이밍 문법을 정리해보며 알았으니, 새로운 언어를 습득할 때, 해당 언어의 style guide를 먼저 살펴봐야겠다.