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 프레임워크 추천

변수 이름이 'type' 이어야 하는 경우가 생겼다.

Json 파싱 해야하는데 key 이름이 'type'이다. 난감..

스칼라는 대소문자를 구분하니 'type'의 t라도 대문자였으면 문제가 없는데...

알아보니 backticks(`) 를 쓰면 된다!

아래와 같이 사용하면 된다는 것!

var `type` = 10


case class Policy (
		Name:		String,
                `type`: 	String,
                Versions: 	Int )

이젠 내 맘대로 하는 주간 회고 ㅋㅋㅋㅋ

지난주 있던 일과 얼마 되지 않은 이번 주 있던 일 정리!

술을 정말 안마시는 나인데 지난주 월, 수, 금 술을 마시게 되었다 ㅋㅋㅋ 그래서 그런가 배탈로 아직도 고생 중이다...

그리고 그 와중에 클라이밍 못 잃어 평일 1회 주말 1회 다녀왔다. 이것이 클창의 길

술 먹은 기록

월요일 갑자기 피자가 땡겨 피자를 먹으러 갔다. 피자집에서 맥주 엄청 마시고 자리 옮겨서 소맥 말아먹더니 

집 가는 길에 공원에서 아이스크림도 먹고 턱걸이도 했다 ㅋㅋㅋㅋㅋㅋㅋㅋ이게 무슨 조합이야

나름 재밌었으며.. 울 책임님과,, 매니저님들과 친해지는 기회가 되었다. 그런데 너무 힘들긴 했다.

수요일 동기들이랑 팀 비 미리 긁어놓은 고오-급진 레스토랑에 가서 칼질 좀 해줬다. 와인도 마셔주고 저 아래 연탄같이 생긴 건 당근이다 ㅋㅋㅋㅋㅋㅋㅋ 당근을 먹었다.

팀 비로 간 곳이라 갔지 내 돈 내고는 잘 안 갈듯.. ㅎㅎ

그리고 2차로 간 '도연하다'라는 한식 술집(?) 맛있었다. 여러 전통주를 팔고 파전이 맛있다는 그곳!

다음날 오전 스터디만 아니었으면 더 마시는데 그러지 못해 정말 아쉬웠다...

금요일은 영어모임 대학생 president와 스캇이랑 만나서 저녁 먹고 평범한 펍을 가려고 했는데 ㅋㅋㅋㅋ 강남역에서 어떤 외국인이 완전 찰진 발음으로 쓰카앗? 하더니 갑자기 그 사람들을 따라 완전 힙한 펍을 가게 되었다.

그런 펍 오랜만이었다. 넘 정신없어서 사진도 못 찍고 마시다가 집에 갔는데 오랜만에 활기차게(?) 논 느낌이라 좋았다 ㅋㅋㅋㅋ 

주 3회였지만 나름 과음하지 않고 마셔서 적당히 재미있는 한 주였다.

갱얼쥐

언니 부부의 여행으로 우리 집에 오게 된 갱얼쥐,, 행복했다 갱얼쥐야,,

갱얼쥐 덕분에 오후에 산책도 하고 매일 알러지 약을 먹긴 했지만 정말 행복했다,,  존재 자체만으로 귀여운 갱얼쥐야,, 우리 집에 또 와줘,,,

소윤이

일요일에는 소윤이를 만났다. 1월에 힘든 일이 많았는데 아직 누구에게 공유하고 싶지는 않았다. 

이번에 소윤이에게 말해줬다. 소윤이는 채고다,,

독서토론 이야기도 하고 앞으로 무엇을 할지, 내 상황에서 내가 무엇을 해야 할 지, 요즘 이슈들을 얘기했다.

소윤이가 맛있는 것도 사줬다! 가볍게 먹고 싶어 찾아간 인계동 우주 샐러드! 소스가 맛있어서 괜찮았다 ㅎㅎ

집에 가는 길에 꽃도 봤다 ㅎㅎ

근데 샐러드 먹고 간 카페에서 마신 커피가 문제였는지 머리도 아프고 밤에 잠이 잘 안 왔다 흑흑,,

클창은 참지 않아

토요일 클라이밍 6시간 태워주고,, 못 푼 문제가 있었다. 아마 그래서 일요일까지 잠이 안 왔나 보다.

당장 월요일에 퇴근하고 바로 클밍하러 갔다.

처음 몇 시도에서 역시 또 실패하더니 결국에는 '내가 해냄!'

평일 치고 5 new 퍼랭이 + 2 원래 하던 퍼랭이 깨기 하고 왔으니 만족스러운 결과다.

요즘은 퍼랭이들을 깨고 있는데 이제 퍼랭이들은 2트 3트정도 하면 깨는 걸 봐서 진정한 파클러라고 할 수 있겠다. 

내일은 신발을 사러 갈 것이다. 신발이 내가 사러 가는 곳에 있을지는 모르겠지만 나도 새 신 신고 더 강려크 해질 것이야!!!

남은 목요일 금요일은 내가 좋아하는 언니들과 약속이 있다 ㅎㅅㅎ

언니들 만나면서 힐링하고 토요일에 또 클밍하러 가야지(기를 모아서 가야 함)

오늘은 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 없이 쓸 수 있다는 점을 알아차리지 못하고 있었는데 알아차리니 신기하군.. 

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

벌써 2주차는 시작되었고 1주차는 오늘 정리한다.

지난주 발목뽀각사태로 인해 내내 칩거 아닌 칩거를 했다.

회사는 내내 재택 때리고 집에서 열심히 업무 마무리 & 새로운 업무 사태(?) 파악 ㅋㅋㅋㅋ 을 하고 진짜 집 밖으로는 한 발자국도 나가지 않았다. (목요일 병원 진료 빼고..) 그 와중에 기계처럼 규칙적으로 생활했다.

7시 40분쯤에 일어나서 출근하고.. 일하다가 쉬다가.. 퇴근하고 밥도 먹고 아 옷장 한칸씩 정리하고(재택이라 가능한 것) 띵가띵가 놀다가 1시 조금 안돼서 잠이 든다.

그 와중에 몇 가지 하기도 했는데,

1. GGLTM 스피치

모임에 온 사람들이 더 많았으면 좋겠지만 몇 안 되는 멤버들이더라도 내가 준비한 연설을 했다. 제목은 "Toastmasters Spirit".

이제 Personal story + 토마 짱! 을 나름 잘 섞어 연설하는데 도가 튼 것 같다. 세계 여행하며 방문한 토마 이야기와 그래서 왜 Toastmasters Spirit이며 왜 주변 사람에게 토마를 추천해야 하는지에 대해 잘 녹여 연설을 했다.

언제나 우리 토마에 함께하고 싶다면 댓글로 남겨주세요 히힛 

2. 고랭 스터디

요즘 고랭 스터디를 하고 있다. 사실 업무에서 고랭을 사용하진 않지만 알아두면 좋다 + 고랭 대세(?) 라기에 ㅋㅋㅋ

그리고 단순히 언어를 배운다기보다 언어를 배우며 개발 아키텍처나 개발 방법, 알고리즘 등등 다양하게 커리어에 도움이 될 것 같았다. 어쩌다가 스터디 리더를 맡게 되어 스터디 그룹 신청 등 이것저것 맡아하게 되어 부담스럽기도 하지만 역시 난 리더형이라며 ㅋㅋㅋ 내가 하는 게 편하다며 나름 열심히 하고 있다.

최근에 다룬 개발 방법에는 TDD가 있었다. 그냥 TDD로 문제를 풀고 코드를 올린 게시물이긴 한데 조심스레 투척... https://haonly.tistory.com/76

지금 보니 넘 쉬워서 굳이...? 이긴 싶지만 ㅋㅋㅋ 다음에 기회가 된다면 TDD도 정리해야겠다. 

이 외에 고랭 TDD 테스트 코드 템플릿? 포멧? 도 스터디원들과 공유해서 좋은 코드를 가지고 있으니 공유해야지!!

3. 다리는 다쳤지만 클라이밍은 하고 싶어.

일주일 동안 돌을 안 잡고 벽을 안 탔더니 뭔가 답답.. + 살이 조금 찌는 느낌이 들었다. 실제로 몸무게가 1.5kg 정도 늘었다 ㅠㅠ

그래서 턱걸이라도 틈틈이 10개씩 (물론 밴드의 도움을 받아) 해 주었다.

토요일이 되니 다리도 크게 아프지 않고, 살살해볼 만할 것 같아 학교 선배 오빠와 언니 + 형부를(??) 꼬셨다. ㅋㅋㅋㅋ 이게 무슨 조합이야.

언니 + 형부가 삼계탕을 사주어서 몸보신을 하고 암장에 가 올랐다 내렸다 몇 번 해주었다. 

특전사 출신 형부는 첫날부터 엄청 잘해서 신기했고 운동 1도 안 하는 언니는 진짜로 1도 못해서 신기했다. 그래도 다들 재미있었다고 한다!!

근데 내가 클라이밍 했다고 하니 누가 이 사진을 보내줬다. 고통이 없어지더라도 회복이 다 된 것은 아니라는.. ㅋㅋㅋ 조심하겠습니다.

다음날(오늘) 일어나니 몸무게가 2kg가 빠졌고(ㅋㅋㅋㅋㅋㅋㅋㅋㅋㅋ) 살짝 근육통 + 피곤함이 있다. 

또 평일 한 주는 쉬다가 다음 주말에 살살해봐야지 낄낄 누가 말려~

사내 스터디에서 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
}

간단하네!?

끝!