프론트엔드 스터디 대면 8주차: API와 통신 — 프론트엔드와 백엔드의 계약

사용자
  -> 브라우저에서 버튼 클릭
  -> 프론트엔드가 서버에 요청
  -> 백엔드가 데이터베이스와 비즈니스 규칙 확인
  -> 백엔드가 응답
  -> 프론트엔드가 응답을 화면으로 변환

const studies = await getStudies();

1. 요청 URL 만들기
2. HTTP 메서드 결정하기
3. 헤더와 body 구성하기
4. 브라우저가 요청 보내기
5. 서버가 응답하기
6. 브라우저가 CORS 등 보안 규칙 확인하기
7. JSON 파싱하기
8. 성공/실패에 따라 UI 상태 바꾸기

GET /api/studies?page=1&size=20 HTTP/1.1
Host: example.com
Accept: application/json

HTTP/1.1 200 OK
Content-Type: application/json

{
  "items": [],
  "page": 1,
  "totalCount": 0
}

GET /api/me HTTP/1.1
Authorization: Bearer access-token

GET /api/studies?page=1&size=20

{
  "items": [
    {
      "id": 1,
      "title": "프론트엔드 스터디",
      "status": "OPEN",
      "currentMemberCount": 12,
      "maxMemberCount": 20
    }
  ],
  "page": 1,
  "size": 20,
  "totalCount": 42
}

{
  "title": "프론트엔드 스터디",
  "description": "API와 통신을 공부합니다.",
  "maxMemberCount": 20
}

{
  "code": "STUDY_ALREADY_CLOSED",
  "message": "이미 마감된 스터디입니다.",
  "fieldErrors": []
}

{
  "code": "VALIDATION_ERROR",
  "message": "입력값을 확인해주세요.",
  "fieldErrors": [
    {
      "field": "title",
      "message": "제목은 필수입니다."
    }
  ]
}

검색 결과 없음        -> 200 OK + items: []
아직 작성한 글 없음   -> 200 OK + items: []
존재하지 않는 글       -> 404 Not Found
권한이 없어 볼 수 없음 -> 403 Forbidden
로그인이 필요함       -> 401 Unauthorized

GET /api/posts?page=3&size=20

GET /api/posts?offset=40&limit=20

처음 요청 시점
[100, 99, 98, ... 81]  -> 1페이지에서 봄
[80, 79, 78, ... 61]   -> 다음에 볼 예정

그 사이 새 글 3개 추가
[103, 102, 101, 100, 99, 98, ...]

offset=20으로 다음 요청
원래 기대: 80부터
실제 결과: 83부터 시작할 수 있음

GET /api/posts?cursor=81&limit=20

{
  "items": [],
  "nextCursor": "eyJpZCI6MTAwfQ==",
  "hasNext": true
}

https://example.com:443/posts/1?tab=comment
└────┬────┘ └────┬────┘ └┬┘
  protocol      host    port

Origin = https://example.com:443

https://example.com/posts
https://example.com/api/studies

http://localhost:5173
http://localhost:8080

https://example.com
https://api.example.com

http://example.com
https://example.com

프론트 코드: fetch("http://localhost:8080/api/studies")
브라우저: 요청은 보냄
서버: 응답은 보냄
브라우저: 응답 헤더 확인
브라우저: 허용되지 않은 Origin이면 JS 코드에 응답을 넘기지 않음

Origin: http://localhost:5173
Access-Control-Allow-Origin: http://localhost:5173

서버 관점: 요청 받음 -> 응답 보냄 -> 200 OK
브라우저 관점: 응답 받음 -> CORS 헤더 확인 실패 -> JS에 응답 전달 차단
프론트 관점: fetch 실패처럼 보임

OPTIONS /api/studies HTTP/1.1
Origin: http://localhost:5173
Access-Control-Request-Method: POST
Access-Control-Request-Headers: content-type, authorization

HTTP/1.1 204 No Content
Access-Control-Allow-Origin: http://localhost:5173
Access-Control-Allow-Methods: GET, POST, PATCH, DELETE
Access-Control-Allow-Headers: Content-Type, Authorization
Access-Control-Max-Age: 600

await fetch("https://api.example.com/me", {
  credentials: "include",
});

Access-Control-Allow-Origin: https://www.example.com
Access-Control-Allow-Credentials: true

Access-Control-Allow-Origin: https://www.example.com
Access-Control-Allow-Methods: GET, POST, PATCH, DELETE
Access-Control-Allow-Headers: Content-Type, Authorization
Access-Control-Allow-Credentials: true

// NestJS 예시
app.enableCors({
  origin: ["http://localhost:5173", "https://www.example.com"],
  credentials: true,
});

// vite.config.ts
export default defineConfig({
  server: {
    proxy: {
      "/api": {
        target: "http://localhost:8080",
        changeOrigin: true,
      },
    },
  },
});

// 브라우저에서는 같은 출처로 요청하는 것처럼 보인다.
await fetch("/api/studies");

브라우저
  -> https://www.example.com/api/studies
  -> Nginx 또는 API Gateway
  -> 내부 백엔드 서버

1. 브라우저 Network 탭에서 실패한 요청을 연다.
2. Request Headers의 Origin을 확인한다.
3. Response Headers의 Access-Control-Allow-Origin을 확인한다.
4. OPTIONS 요청이 있는지 확인한다.
5. OPTIONS 응답에 Allow-Methods, Allow-Headers가 있는지 확인한다.
6. 쿠키 요청이면 credentials와 Allow-Credentials를 확인한다.
7. 서버 로그에는 성공인데 브라우저만 막는 상황인지 확인한다.

AJAX 이전: 요청 -> 새 HTML 전체 다운로드 -> 페이지 전체 교체
AJAX 이후: 요청 -> JSON 데이터 다운로드 -> 필요한 UI만 갱신

getUser(userId, function (user) {
  getOrders(user.id, function (orders) {
    getOrderDetail(orders[0].id, function (orderDetail) {
      // 계속 중첩됨
    });
  });
});

async function loadUserOrderInfo(userId: number) {
  try {
    const user = await getUser(userId);
    const orders = await getOrders(user.id);
    const orderDetail = await getOrderDetail(orders[0].id);
    return orderDetail;
  } catch (error) {
    console.error("요청 실패", error);
  }
}

const response = await fetch("/api/users");
const data = await response.json();

const response = await fetch("/api/users");

if (!response.ok) {
  throw new Error("HTTP error");
}

const data = await response.json();

const response = await axios.get("/api/users");
const data = response.data;

try {
  const response = await axios.get("/api/users");
  console.log(response.data);
} catch (error) {
  if (axios.isAxiosError(error) && error.response) {
    console.log(error.response.status);
    console.log(error.response.data);
  }
}

const apiClient = axios.create({
  baseURL: "/api",
  timeout: 10000,
  withCredentials: true,
});

export async function getStudies(params: GetStudiesParams) {
  const response = await apiClient.get<StudyListResponse>("/studies", {
    params,
  });

  return response.data;
}

apiClient.interceptors.request.use((config) => {
  // 학습을 위한 단순 예시입니다.
  // localStorage에 토큰을 저장하면 XSS 공격에 노출될 수 있습니다.
  const token = localStorage.getItem("accessToken");

  if (token) {
    config.headers.Authorization = `Bearer ${token}`;
  }

  return config;
});

로그인 성공
  -> Access Token 발급: 짧은 수명, API 요청에 사용
  -> Refresh Token 발급: 긴 수명, Access Token 재발급에 사용

Authorization: Bearer {accessToken}

요청 A, B, C가 동시에 401을 받음
  -> refresh 요청을 세 번 보내면 위험
  -> 하나의 refresh만 진행하고 나머지는 그 결과를 기다리게 설계

await fetch("https://api.example.com/me", {
  credentials: "include",
});

Access-Control-Allow-Origin: https://www.example.com
Access-Control-Allow-Credentials: true
Set-Cookie: refreshToken=...; HttpOnly; Secure; SameSite=None

const [users, setUsers] = useState([]);
const [loading, setLoading] = useState(false);
const [error, setError] = useState(null);

useEffect(() => {
  setLoading(true);
  axios
    .get("/api/users")
    .then((response) => setUsers(response.data))
    .catch((error) => setError(error))
    .finally(() => setLoading(false));
}, []);

const { data, isLoading, error } = useQuery({
  queryKey: ["users"],
  queryFn: () => apiClient.get("/users").then((res) => res.data),
  staleTime: 5 * 60 * 1000,
});

const queryClient = useQueryClient();

const createStudy = useMutation({
  mutationFn: (newStudy) => studyApi.createStudy(newStudy),
  onSuccess: () => {
    queryClient.invalidateQueries({ queryKey: ["studies"] });
  },
});

["studies", "list", { status: "OPEN", page: 1 }][("studies", "detail", 123)];

export const studyQueries = {
  all: ["studies"] as const,
  lists: () => [...studyQueries.all, "list"] as const,
  list: (params: GetStudiesParams) =>
    [...studyQueries.lists(), params] as const,
  detail: (studyId: number) =>
    [...studyQueries.all, "detail", studyId] as const,
};

src/
  api/
    client.ts
    studies.ts
  pages/
    StudyListPage.tsx
  components/
    StudyCard.tsx

// api/studies.ts
export async function getStudies(params: GetStudiesParams) {
  const response = await apiClient.get<StudyListResponse>("/studies", {
    params,
  });

  return response.data;
}

src/
  shared/
    api/
      httpClient.ts
      apiError.ts
  features/
    studies/
      api/
        studyApi.ts
        studyQueries.ts
      model/
        studyTypes.ts
        studyPolicy.ts
      ui/
        StudyCard.tsx
        StudyList.tsx

스터디 목록 화면에서 모집 중/마감 상태에 따라 버튼이 달라집니다.
응답에 status 필드를 OPEN/CLOSED 형태로 받을 수 있을까요?
빈 목록일 때는 items: []와 totalCount: 0으로 내려오는지 확인 부탁드립니다.