프로젝트 전역 통신 규약 정의

[manamana32321]

Describe the feature

해당 프로젝트의 담당자는 동아리 홈페이지라는 그 특성 상 담당자 교체가 잦을 것으로 예상됩니다. 따라서 코드의 유지 보수성을 충분히 고려해야 합니다. 그래서 먼저 프로젝트 전역적으로 사용될 서버와 클라이언트 간의 통신 규약을 정의하고 문서화 하는 것을 제안합니다. 여러분들도 이에 관련한 자료 찾아보시고 좋은 제안 있으시면 코멘트 부탁드립니다.

서버 - 클라이언트 간의 데이터 구조 정의

아래는 현재 백업 서버에서 사용 중인 데이터 통신 인터페이스 입니다.(#104 에서 추가됨) 지금까지 사용해본 결과 count, statusText를 제외한 모든 속성들이 유용했습니다.

export interface ServerResponse {
  error: ServerError | null
  data: any
  count: number | null
  status: HttpStatusCode
  statusText: string
}

ServerError 타입은 아래에 정의되어 있습니다.

서버 - 클라이언트 간의 에러 정의

현재는 아래와 같은 에러 객체를 사용하고 있습니다.

export interface ServerError {
  errorType: string // 에러를 분류하기 위한 URI 식별자
  status: HttpStatusCode // HTTP 응답 코드
  title?: string // 사람이 읽을 수 있는 간단한 에러에 대한 메세지
  detail?: string // 사람이 읽을 수 있는 에러에 대한 설명
  instance?: string // 에러가 발생한 URI
}

errorType은 정해진 상수 string으로 타입을 변경하여 각 언어(Typescript, Java)에 맞게 정의해서 사용하는 것을 제안합니다. 물론 status(HTTP 상태 코드)도 응답의 상태를 표현할 수는 있지만 구체적인 상황을 대변하는 것은 어렵습니다. 예를 들어 스터디 참여 신청을 했을 때 400(Bad Request) 상태 코드가 반환되었다면 신청 동기 글자 수 제한을 초과했는지, 신청 동기를 누락했는지 알 방법이 없습니다. 하지만 title, detail, instance는 입지가 애매한 상황이라 이에 대한 논의가 필요합니다.

서버에서 수신한 데이터 처리 과정 정의

클라이언트 측은 서버에서 받은 데이터를 처리하는 과정에 대한 패턴을 정하는 것을 제안합니다.

const res = await fetchData(API_ENDPOINTS.STUDY.SIGNUP(study.id))  // JSON 변환 까지 포함

if (res.error) {
  switch (res.error.errorType) {
    case ServerErrorType.StudySignup.Enrollment.AlreadySignedup:
      // 에러 처리
      break
    default:
      throw new UnhandledError(res.error)
      break
  }
}
return res.data

Additional context

[manamana32321]

회의 내용 반영

ServerResponse 구조 변경

중복되는 속성(status, statusText) 제거

fetchData 및 ServerResponse 문서화

JDocs 또는 README.md 추가

추가 고려 사항

fetchData의 JSON 변환 과정 캡슐화에서 제외

이유

• await res.json()도 비동기 작업으로서 처리 시간이 꽤 걸릴 수 있음
• 반드시 res의 형태가 application/json이 아닐 수 있음, 파일의 경우에 멀티파트데이터 형식 일 수 있음