Haonly's Blog

사내 스터디 세미나로 준비한 자료 정리

Go 언어를 활용한 마이크로서비스 개발

2장 좋은 API 디자인하기

api 규약 작성이 매우 중요하며 어려움

RESTful API

• REpresentational State Transfer(표현적 상태 전송)
  • 컴포넌트(서비스 단위) 간 상호작용의 확장성, 범용적인 인터페이스, 컴포넌트의 독립적인 배포를 강조하며 응답 지연시간 감소, 보안 강화, 레거시 시스템의 캡슐화를 위한 중간 컴포넌트 역시 강조한다.

URI, URN, URL

• RFC 3986

• 

• URI 형식 지정의 규칙
  • 슬래시(/)는 리소스 사이의 계층적 관계를 나타내는 데 사용
  • URI의 마지막에 슬래시가 포함되어서는 안된다.
  • 하이픈(-) 사용, _ 사용 x
  • 대소문자 구분하므로 소문자 사용 권장

URI 경로

표현설명비고

REST URI 디자인

• DELETE /cats/1234: 좋은 예
• GET /deleteCat/1234: 나쁜 예
• POST /cats/1234/delete: 나쁜 예
• HTTP 동사
  • GET / POST / PUT / DELETE / PATCH / HEAD / OPTIONS

응답코드

• 요청의 성공이나 실패를 클라이언트에게 알려주기 위한 HTTP 응답 코드
• 즉각적으로 요청의 상태를 알 수 있게 설계

나쁜 응답

POST /kittens RESPOSNE HTTP 200 OK { "status": 401, "statusMessage": "Bad Request" }

POST /kittens RESPOSNE HTTP 200 OK { "id": "123434jvjv4564", "name": "Fat Freddy's Cat" }

• 좋은 응답은 HTTP 상태 코드를 문자 그대로 사용하는 것

실패 응답의 좋은 예

POST /kittens RESPONSE HTTP 400 BAD REQUEST { "errorMessage": "Name should be between 1 and 256 characters...." }

성공한 응답의 좋은 예:

POST /kittens RESPONSE HTTP 201 CREATED { "id": "123434jvjv4564", "name": "Fat Freddy's Cat" }

• IBM HTTP 요청과 응답 예제

HTTP 상태 코드

• 구글에 더 자세하게 나와있지만 간략하게 정리
• 200 OK: 요청이 성공했음을 나타내는 일반적인 응답 코드
• 201 Created(생성): 요청이 성공하고 새 엔티티가 생성된 경우의 응답
• 204 No Content: 내용 없음. 클라이언트의 요청이 잘 처리되었지만 본문은 없음. DELETE 요청에 대한 응답이 될 수 있음
• 3xx: 경로 재지정.
• 4xx: 클라이언트 에러
  • 400 Bad Request / 401 Unauthorized / 404 Not Found / ...
• 5xx: 서버 오류

mozilla 상태코드 참고 사이트

HTTP 헤더

• 표준에 맞추면 모두에게 도움이 된다!
• 표준 요청 헤더
  • 요청에 대한 메타 데이터 개념
  • 요청 및 API 응답에 대한 추가 정보 제공
• Authorization - 문자열
  • 권한 부여: Authorization key 요청
  • 이런 표준 접근 방식을 따르면 클라이언트가 알아서 구현알 수 있다는데
  • 사실 이걸 어떻게 부여하는지는 잘 모르겠습니다!
• Date
  • 요청의 타임스탬프
• Accept - 콘텐츠 타입
  • application/xml
  • text/xml
  • application/json
• Accept-Encoding - gzip, release
  • REST 엔드 포인트는 가능한 경우 gzip과 deflate 인코딩을 항상 지원해야 한다.
  • gzip 지원은 간단함: 표준 라이브러리의 일부인 compress/gzip 패키지 사용
  • 뉴욕타임즈 오픈소스
  • 비손실 압축을 위한 인코딩,,
• 에러 리턴
  • API 사용자는 에러가 발생했을 때 여러 앤드 포인트에서 발생한 에러를 처리하는 하나의 코드를 작성할 수 있어야 하는데
  • 표준 에러 엔티티를 제공함으로써 클라이언트 또는 서버로 인한 에러가 발생할 때 클라이언트를 도와줄 수 있음
  • 마이크로소프트의 API 가이드라인 자료

API 버전 관리

• 초기부텉 고려해야하는 사항, 피할 수 있으면 피하는 것이 좋다!
• 버전 관리가 필요한 상황
  • 주요 변경 사항이 생기면 API 버전 번호를 증가시키는데 주요 변경사항은
    1. API나 API 매개 변수의 제거 또는 이름 변경
    2. API 매개 변수의 타입 변경(정수 -> 문자열)
    3. 응답 코드, 에러 코드 또는 실패 규약 변경
    4. 기존 API 의 동작 변경
• 시맨틱 버전 관리
  • 메이저 버전과 마이너 버전: 1.0 에서 1은 메이저, .0은 마이너
  • 마이너의 변경은 클라이언트가 API와 상호작용하는 데 영향을 주지 않음
• REST API의 버전 관리 형식
  • https://myserver.com/v1/helloworld :URI의 일부로 버전을 선택
  • https://myserver.com/hellowirld?api-version=1 : 쿼리 문자열의 매개 변수로 선택
  • GET https://myserver.com/helloworld api-version:2 : HTTP 헤더를 사용해 선택

객체 타입 표준화

• 클라이언트에서 객체를 쉽게 처리할 수 있도록 고려
• JSON을 사용하는 경우 기본 타입으로 날짜 개념이 없다! --> ISO 표준을 사용하는 것이 도움이 된다
• 예
  • {"date": "2021-07-08T04:52:57Z"}
  • {"date": {"kind": "U", "value": 1625719977221}

API 문서화

1. Swagger

• YAML로 작성
• 배책임님께서 이전에 소개해주신 API 문서 자동화 도구!

1. API Blueprint

• 마크다우능로 작성돼 중첩된 레이어를 다루는 것보다 좀 더 자연스럽게 문서 작성 가능

1. RAML

• RESTful API Modeling Language의 약자
• YAML로 작성

API 문서 자동화 오픈소스(https://github.com/swaggo/swag)

여러가지 참고 링크

• GO 오픈소스 참고 github
• Go REST API 프레임워크 추천

오늘은 2회차 고랭 강의!

자꾸 미뤄서 듣게 된다.. ㅎㅎ 5분도 안되는 영상들인데 뭔가 다른 일들에 밀려 듣게 됨.. ㅎㅎ

오늘은 Go syntax 재목의 강의를 요약해 보았다.

Go syntax

Case sensitive 함 => 대소문자 구별을 한다는 것

Function, 변수명, 타입이름 등의 Identifier 들은 모두 document에 나와있는 그대로 써야함 

변수와 package 이름들은 소문자거나 대소문자 합쳐져있음

그러나 public fields의 첫 글자는 대문자임

여기서 첫 글자가 대문자라는 것은 그 symbol은 exported 라는 것!

반대로 말하면 첫 글자가 소문자라는 것은 private이고 대문자면 public.

go는 타이핑을 줄임

; <- 와 같은 세미콜론 입력하지 않아도 됨

lexer라는 애가 필요하면 알아서 추가함

그러나 탭이나 띄어쓰기와 같은 whitespace에는 민감하니 조심!

Code bloc은 괄호나 대괄호와 같은 braces 로 묶임

코드에서 언제나 쓸 수있는 package가 있는데 이것을 builtin package라고 부름

자바에서는 import 해야했던 것을 그냥 쓸 수 있다는 말!

예를 들어 len(string), panic(error),  recover() 과 같은 것들

더 참고할 만한 builtin package 설명은 공식문서를 참고!

https://golang.org/pkg/builtin

자바나 다른 언어와 달리 builtin 을 import 없이 쓸 수 있다는 점을 알아차리지 못하고 있었는데 알아차리니 신기하군.. 

깊게 들어가면 어려우니 일단 쓸 수 있게만 써봐야지 ㅎㅎ

사내 스터디에서 TDD를 배워봤다. 

앞으로 고랭 문제나 모듈 개발할 때 TDD를 활용하면 좋겠다고 생각했다.

그래서 이번 주 스터디 문제를 TDD로 풀어보았다. 다행히 이번 주 스터디 리더가 쉬운 문제를 내서 TDD로 풀어볼 만했다.

문제는 아주 간단하다. 

문제링크

입출력 예만 간단히 보여주자면 아래와 같다. 

나는 이제 이 문제를 그냥 접근해 볼 수도 있었지만 TDD를 활용해 test 코드를 작성하고 풀어보았다.

import (
	"testing"
	"github.com/stretchr/testify/assert"
)

우선 위 두 라이브러리를 import 해서 test 코드를 작성할 수 있도록 해주었다.

그리고 아래와 같이 전체 테스트 코드를 작성해 보았다. 조건이 두 가지뿐이었고 예시 케이스로만 테스트해도 모두 통과하기 때문에 두 예시에 대한 테스트 코드만 작성했다. 

전체 코드

package study_0603_1

import (
	"testing"
	"github.com/stretchr/testify/assert"
)

func Test1(t *testing.T) {
	a := []int{1, 2, 3, 4}
	b := []int{-3, -1, 0, 2}
	assert.Equal(t, 3, solution(a, b))
}

func Test2(t *testing.T) {
	a := []int{-1,0,1}
	b := []int{1, 0, -1}
	assert.Equal(t, -2, solution(a, b))
}

이 테스트 코드에 맞게 main 코드를 작성했다.

solution 코드

package study_0603_1

func solution(a []int, b []int) int {
	ret := 0
	for idx, _ := range a{
		ret += a[idx] * b[idx]
	}
	return ret
}

간단하네!?

끝!

회사에서 링크드인러닝 수강권을 받아 이렇게 저렇게 활용해 보다가 관심있는 언어인 Go 를 배우며 정리해보기로 했다.

오늘 강의의 제목은 "Go's essential characteristics"

Compiled or Interpreted?

Go는 컴파일 언어이며 C, C++ 와 마찬가지이다.
파이썬과 같이 interpreter 언어는 컴파일러가 필요없다.

운영체제에 영향을 받는다.

external virtual machine이 필요하지 않다. (자바에서는 jvm이 필요)

Object Oriented인가? 

sort of.. 

Go 에서는 타입을 정할 수 있고 method가 있는데 이는 object oriented라는 것.

Go가 지원하지 않는것

상속(class가 없음)

오버로딩(overloading)이 없음 -> 같은 이름의 여러 method 작성 불가라는 것

try catch와 같은 exception handling이 없음

Go의 ancestor languages

C 언어, pascal, Oberon 등의 언어를 활용

간단하게 작성할 수 있도록 만들어진 언어라 배우기 쉬움.

Jetbrains의 Goland IDE 설치와 사용

www.jetbrains.com/go/

1. 먼저 위 사이트로 이동해 고랜드를 다운받는다.

2. 다운받은 고랜드를 실행하면 계정 인증(activate)을 하라는데 나는 회사계정으로 로그인했더니 아래와 같이 나왔다.

3. 'New Project' 누르고 프로젝트 이름 설정

4. new -> Go file -> main.go 생성

  이 때 환경에 golang이 설치되어 있지 않으면 'GOROOT is not defined' 라는 워닝이 나타난다. 

  homebrew로 golang을 설치해야한다.

5. 'main.go'에 예제 코드 작성

이러고 실행이 계속 안돼서 찾아보다가 main package 를 만들어야 한다는 에러를 보고 configuration 수정하여 프로젝트를 main 이라는 package 이름으로 refactor 해 주었고 그러고 나니 "Hello World!" 가 나왔다...!!

6. go_test(다른 테스트 하다가 test 로 새로 만든 환경임)를 refactor 통해 main package로 바꿔줌

  또는 아래와 같이 depth 추가하여 package 생성

주의: 프로젝트 생성 시에 GOROOT 설정