안녕하세요, 여러분 
저는 Discourse를 헤드리스 백엔드로 사용하여 Next.js 기반 아키텍처로 커스텀 프론트엔드를 구축하고 있습니다. 실제 통합 관점에서 현재 API 설계에서 발견한 실용적인 결점 몇 가지를 공유하고자 합니다.
이것은 Discourse 자체에 대한 비판(강력하고 유연한 도구입니다)이 아니라, 현대적인 프론트엔드 + API 주도 아키텍처의 DX(개발자 경험)를 개선하기 위한 피드백입니다.
1. 페이지네이션 및 토픽 게시물 구조
현재 문제:
-
페이지네이션이 엔드포인트 간에 항상 일관되지 않습니다
-
토픽 게시물(
/t/{id}.json)에는 다음이 혼합되어 있습니다:-
원본 게시물
-
답변
-
내부 메타데이터
-
-
이로 인해 깔끔한 무한 스크롤/규격화된 상태(Redux/Zustand/React Query) 구축이 어려워집니다
제안:
-
더 명확한 분리 또는 다음과 같은 선택적 쿼리 플래그 제공:
-
?include_first_post=true|false -
?posts_only=replies -
커서 기반 페이지네이션 지원(페이지 기반만 허용하는 대신)
-
2. 답변과 토픽 구조
현재 상태:
-
답변은 토픽 응답 안에 임베드되어 있습니다
-
다음 사이의 명확한 분리가 없습니다:
-
“토픽 메타데이터”
-
“게시물 스트림”
-
이로 인해 발생하는 문제:
-
프론트엔드에서 추가적인 파싱 로직 필요
-
상태 규격화 시 중복 발생
제안:
-
전용 엔드포인트 제공:
-
/t/{id}/posts -
/t/{id}/replies -
또는
/t/{id}.json내부에서 필터링 지원
-
3. API 응답의 필드 수준 문서화 부재
예를 들어 토픽 응답에서:
-
created_at -
bumped_at -
last_posted_at -
updated_at
이들은 항상 명확하게 구별되지 않습니다.
문제점:
-
개발자들이 자주 오해하는 부분:
-
bumped_at과updated_at의 차이 -
"토픽 활동"을 트리거하는 조건
-
제안:
-
인라인 스키마 문서화 또는 OpenAPI 스타일 메타데이터 추가:
-
각 필드의 의미
-
라이프사이클 설명
-
4. 통계 및 캐싱 불일치
문제점:
-
posts_count,reply_count,participants_count가 때때로 실시간 데이터보다 지연됩니다 -
캐시된 카운터에 대한 과도한 의존성
영향:
-
부정확한 UI(특히 대시보드/분석 페이지에서)
-
상태 검증을 위한 추가 API 호출 필요
제안:
-
“실시간 대 캐시” 표시자 또는 엔드포인트 변형 추가
-
또는 카운트에 대한 웹훅/이벤트 기반 업데이트 제공
5. 사이트맵 + SEO + 프레임워크 통합 결함
현대 프레임워크(Next.js, Nuxt 등)와 통합할 때:
문제점:
-
다음을 위한 통합된 API가 없습니다:
-
사이트맵 생성을 위한 업데이트된 토픽
-
카테고리 수준의 마지막 변경 추적
-
전체 게시물 색인화 지원
-
개발자들이 결국 수행하는 작업:
-
카테고리당 여러 API 호출
-
updated_at에 대한 수동 차이 비교(diffing) -
업데이트 감지를 위한 페이지네이션 크롤링
제안:
-
전용 엔드포인트 추가:
-
/categories/updated -
/topics/changes?since=timestamp -
/sitemap.json(API 기반 사이트맵 피드)
-
6. 사용자 메트릭 및 집계 부재
일반적으로 필요한 데이터:
-
사용자별 총 좋아요 수(받은)
-
총 좋아요 수(준)
-
게시물/사용자별 반응 세부 정보
-
카테고리별 참여도 통계
현재 문제:
- 여러 엔드포인트 + 프론트엔드에서의 집계 필요
제안:
-
다음과 같은 집계 엔드포인트 추가:
-
/users/{id}/stats -
/topics/{id}/stats
-
7. 사용자 아바타 유연성
현재 제한 사항:
- 아바타가 Discourse 업로드 시스템과 강하게 결합되어 있습니다
요청 사항:
-
외부 아바타 URL 허용(S3 / CDN / 외부 인증 제공업체)
-
지원:
external_avatar_url
이것은 다음에 도움이 됩니다:
-
SSO 시스템
-
헤드리스 ID 제공업체
8. API 키: 관리자 대 사용자 키
문서에서 명확히 할 필요가 있습니다:
차이점:
-
관리자 API 키
-
사용자 API 키(
/admin/api/keys또는 사용자 API 엔드포인트를 통해 생성)
질문 사항:
-
라이프사이클 및 만료 규칙
-
사용자별 대 전역 폐기 규칙
-
유형별 보안 범위 제한
이것은 프로덕션급 통합을 구축할 때 매우 중요합니다.
마무리
Discourse API는 이미 강력하지만, "헤드리스/프론트엔드 주도 아키텍처"보다는 "서버 렌더링된 포럼 사용"에 최적화된 것처럼 느껴집니다.
현대 프레임워크(Next.js, Remix 등)는 다음에서 많은 이점을 얻습니다:
-
라운드 트립 감소
-
명확한 데이터 경계
-
예측 가능한 캐싱 규칙
-
더 나은 집계 엔드포인트
헤드리스 Discourse 설정을 구축하는 유지보수자나 다른 개발자들의 피드백을 듣고 싶습니다.
감사합니다 