GraphQL— 나는 그동안 URL이 /graphql인 REST를 만들고 있었다

1type Post { ... }
2type PostWithCommentsOutput { ... }       # 같은 도메인인데 다른 타입?
3type Article { ... }
4type ArticleWithTagsOutput { ... }         # 또?
5
6type Query {
7  commentsByPost(...): [CommentOutput!]!  # Post.comments로 이미 도달 가능한데?
8}
9
10type DeleteCommentOutput {
11  success: Boolean!     # 항상 true
12  message: String!      # 한국어로 박혀있음
13}
14
15type PostOutput {
16  tags: [Tag!]               # 어떤 건 Entity 직노출
17  comments: [CommentOutput!]! # 어떤 건 Output 접미사
18  cover: CoverOutput          # 일관성 없음
19}

1// ❌ REST 사고 — 화면 단위 응답
2@Query(() => DashboardOutput)
3async getDashboard(@Args('userId') userId: string) {
4  const user = await this.userService.findOne(userId);
5  const posts = await this.postService.findByUser(userId);
6  const comments = await this.commentService.findByPosts(posts.map(p => p.id));
7  return { user, posts, comments };  // 화면 전용 응답
8}
9
10// ✅ GraphQL 사고 — 도메인 모델 그대로 노출
11@Resolver(() => User)
12class UserResolver {
13  @ResolveField(() => [Post])
14  posts(@Parent() user: User) {
15    return this.postLoader.load(user.id);
16  }
17}
18
19@Resolver(() => Post)
20class PostResolver {
21  @ResolveField(() => [Comment])
22  comments(@Parent() post: Post) {
23    return this.commentLoader.load(post.id);
24  }
25}

1┌────────────────────────────────────────────────────────────┐
2│  Layer 1: 런타임 JavaScript 객체 (= PostEntity 인스턴스)      │
3│  → DB에서 SELECT한 결과. 모든 컬럼 + 관계가 다 채워질 수 있음   │
4│  → 메모리에 떠다니는 "그 데이터 그 자체"                        │
5└────────────────────────────────────────────────────────────┘
6                          ↓ 변환 없음, 그대로 전달
7┌────────────────────────────────────────────────────────────┐
8│  Layer 2: TypeScript 타입 (= 코드에서 보는 클래스)             │
9│  → @Parent() post: PostEntity                               │
10│  → 개발자가 IDE에서 자동완성, 컴파일 체크 받는 용도              │
11└────────────────────────────────────────────────────────────┘
12                          ↓ 클라이언트에 노출할 때만 변환
13┌────────────────────────────────────────────────────────────┐
14│  Layer 3: GraphQL Schema 타입 (= schema.gql의 type)         │
15│  → type PostOutput { ... }                                  │
16│  → 클라이언트가 보는 계약. JS 객체 중 일부 필드만 보여줌         │
17└────────────────────────────────────────────────────────────┘

1// 1. Service: DB에서 Entity를 끌어온다
2async findByAuthor(authorId: string): Promise<PostEntity[]> {
3  return this.repo.findBy({ authorId });
4  // → PostEntity 인스턴스 배열. 메모리에 실재.
5}
6
7// 2. Resolver: Entity를 그대로 반환. 단지 "선언"만 Output으로
8@Query(() => [PostOutput])
9async postsByAuthor(...): Promise<PostOutput[]> {
10  return this.postService.findByAuthor(...);
11  // → 실제로는 PostEntity[]를 반환.
12  // → TS는 OK (PostOutput extends OmitType(PostEntity))
13}
14
15// 3. NestJS GraphQL: Entity 인스턴스를 받아서 schema의 PostOutput에 따라 직렬화
16//    → schema에 선언된 필드만 골라서 응답에 넣는다
17//    → ResolveField가 있는 필드는 메서드 호출해서 채운다

1@ObjectType()
2export class PostOutput extends OmitType(PostEntity, ['id'], ObjectType) {}

1@Resolver(() => PostOutput)  // ← 이 인자가 어떤 의미를 갖는가?
2export class PostResolver {
3
4  @Query(() => [PostOutput])
5  postsByAuthor(...) { ... }            // (A) 그래프 진입점
6
7  @Mutation(() => PostOutput)
8  publishPost(...) { ... }              // (A) 그래프 진입점
9
10  @ResolveField(() => CoverOutput)
11  cover(@Parent() post) { ... }         // (B) PostOutput 타입의 한 필드
12}

1# 결과적으로 schema는 이렇게 된다
2type PostOutput {
3  postId: ID!
4  title: String!
5  ...                    # Entity의 정적 필드
6  cover: CoverOutput      # ← PostResolver.cover() 메서드가 채움
7  comments: [Comment!]!   # ← PostResolver.comments() 메서드가 채움
8}

1// modules/post/post.resolver.ts
2@Resolver(() => PostOutput)
3export class PostResolver {
4  @ResolveField(() => CoverOutput)
5  cover(@Parent() post) { ... }            // Post → Cover 모서리
6}
7
8// modules/cover/cover.resolver.ts
9@Resolver(() => CoverOutput)
10export class CoverResolver {
11  @ResolveField(() => PostOutput, { nullable: true })
12  post(@Parent() cover) { ... }            // Cover → Post 역방향 모서리
13
14  @ResolveField(() => UserOutput)
15  uploadedBy(@Parent() cover) { ... }
16}

1┌─────────────────────────────────────────────────────────┐
2│  schema.gql (그래프의 지도 — 모든 도메인이 모여 그려짐)        │
3│                                                          │
4│   type Post {                                            │
5│     postId: ID!                                          │
6│     cover: Cover           ◄──┐ PostResolver가          │
7│     comments: [Comment!]!  ◄──┤ ResolveField로 추가      │
8│   }                                                      │
9│                                                          │
10│   type Cover {                                           │
11│     coverId: ID!                                         │
12│     uploadedBy: User       ◄──┐ CoverResolver가         │
13│     post: Post             ◄──┤ ResolveField로 추가      │
14│   }                                                      │
15└─────────────────────────────────────────────────────────┘
16
17modules/post/                        modules/cover/
18├── post.entity.ts                    ├── cover.entity.ts
19├── post.output.ts                    ├── cover.output.ts  ◄── 여기!
20├── post.resolver.ts                  ├── cover.resolver.ts
21│   @Resolver(() => PostOutput)       │   @Resolver(() => CoverOutput)
22│     @ResolveField cover()           │     @ResolveField uploadedBy()
23│     @ResolveField comments()        │     @ResolveField post()
24└── post.service.ts                   └── cover.service.ts
25        ↓                                     ↓
26   CoverOutput을 import해서            PostOutput을 import해서
27   ResolveField의 반환 타입으로 선언    ResolveField의 반환 타입으로 선언

1도메인 노드      ↔   GraphQL 타입       ↔   Output 클래스
2───────────────────────────────────────────────────────
3User            ↔   type User            ↔   UserOutput
4Post            ↔   type Post            ↔   PostOutput
5Comment         ↔   type Comment         ↔   CommentOutput
6Tag             ↔   type Tag             ↔   TagOutput
7Cover           ↔   type Cover           ↔   CoverOutput

1type Post {
2  postId, title, status
3}
4
5type PostWithCommentsOutput {   # ← 화면 전용 타입
6  postId, title, status
7  comments: [Comment!]!
8}
9
10type Article {
11  articleId, headline, ...
12}
13
14type ArticleWithTagsOutput {   # ← 또 화면 전용 타입
15  articleId, headline, ...
16  tags: [Tag!]!
17  author: UserOutput!
18}

1type Post {
2  postId, title, status
3  comments: [Comment!]!  # ResolveField
4  myReaction: Reaction   # ResolveField
5}
6
7type Query {
8  post(input: PostInput!): Post!         # 한 타입
9  myPosts(input: MyPostsInput!): [Post!]! # 같은 타입
10}

1@ObjectType()
2export class PostOutput extends OmitType(PostEntity, ['id'], ObjectType) {}
3
4@ObjectType()
5export class PostWithStatsOutput extends PostOutput {
6  @Field(() => Int)
7  commentCount!: number;
8}

1type PostWithStatsOutput {
2  postId: ID!             # ✅ 상속됨
3  title: String!          # ✅ 상속됨
4  commentCount: Int!      # ✅ 새 필드
5  # ❌ cover 없음 (ResolveField는 자동 상속 안 됨)
6  # ❌ comments 없음
7}

1function createPostFieldsResolver<T>(typeRef: Type<T>) {
2  @Resolver(() => typeRef, { isAbstract: true })
3  abstract class PostFieldsResolverHost {
4    @ResolveField(() => CoverOutput, { nullable: true })
5    cover(@Parent() post, @Loaders() loaders) {
6      return loaders.postCover.load(post.id);
7    }
8    @ResolveField(() => [CommentOutput])
9    comments(@Parent() post, @Loaders() loaders) {
10      return loaders.postComments.load(post.id);
11    }
12  }
13  return PostFieldsResolverHost;
14}
15
16@Resolver(() => PostOutput)
17export class PostResolver extends createPostFieldsResolver(PostOutput) {}
18
19@Resolver(() => PostWithStatsOutput)
20export class PostWithStatsResolver extends createPostFieldsResolver(PostWithStatsOutput) {
21  @ResolveField(() => Int)
22  commentCount(@Parent() post) { ... }
23}

1// ✅ 더 좋은 답
2@Resolver(() => PostOutput)
3export class PostResolver {
4  // 기존 ResolveField들...
5
6  // 새 필드는 그냥 ResolveField 추가
7  @ResolveField(() => Int)
8  commentCount(@Parent() post) {
9    return loaders.postCommentCount.load(post.id);
10  }
11
12  @ResolveField(() => Boolean)
13  isMine(@Parent() post, @User() user) {
14    return post.authorId === user.userId;
15  }
16}

1type PostOutput {
2  postId: ID!
3  title: String!
4  commentCount: Int!         # ← 새 필드, 한 타입에 그냥 추가
5  isMine: Boolean!           # ← 새 필드
6}

1# 가벼운 화면
2query { postsByAuthor { postId title } }
3
4# 통계가 필요한 화면
5query { postsByAuthor { postId title commentCount } }

1@Resolver(() => Post)
2class PostResolver {
3  // 정적 필드는 entity의 컬럼에서 자동
4  // 모든 파생/관계/계산은 ResolveField로 한 타입에 모인다
5
6  @ResolveField(() => CoverOutput, { nullable: true })
7  cover(...) { ... }                     // ← 1:1 관계
8
9  @ResolveField(() => [CommentOutput])
10  comments(...) { ... }                   // ← 1:N 관계
11
12  @ResolveField(() => UserOutput)
13  author(...) { ... }                     // ← N:1 관계
14
15  @ResolveField(() => Int)
16  commentCount(...) { ... }               // ← 집계 파생
17
18  @ResolveField(() => Boolean)
19  isMine(...) { ... }                     // ← 권한 파생
20
21  @ResolveField(() => Boolean)
22  canEdit(...) { ... }                    // ← 권한 파생
23
24  @ResolveField(() => PostStats)
25  stats(...) { ... }                      // ← 통계 묶음 (또 다른 노드)
26}

1새 데이터 요구사항
2       │
3       ▼
4어느 도메인 노드의 무엇인가?
5       │
6   ┌───┴───┐
7  속성?    완전히 새 도메인?
8   │           │
9   ▼           ▼
10ResolveField  새 Output + 새 Query
11추가          (드물어야 함)
12   │
13   ▼
14끝.

1# ❌ REST 사고방식 — 새 entry point 추가
2type Query {
3  postsByAuthor(input: ...): [PostOutput!]!
4  commentCount(postId: ID!): Int!              # ← 새 query
5  postAuthor(postId: ID!): UserOutput!         # ← 또 새 query
6  postCommentList(postId: ID!): [Comment!]!    # ← 또 새 query
7}
8
9# ✅ GraphQL 사고방식 — 기존 노드에 모서리 추가
10type Query {
11  postsByAuthor(input: ...): [PostOutput!]!  # 진입점은 그대로
12}
13
14type PostOutput {
15  postId: ID!
16  title: String!
17  commentCount: Int!         # ← ResolveField로 추가
18  author: UserOutput!        # ← ResolveField
19  comments: [CommentOutput!]! # ← ResolveField
20}

1# ResolveField일 때 — 한 번의 query
2query {
3  postsByAuthor(input: ...) {
4    postId
5    title
6    commentCount     # 같이 가져옴
7  }
8}
9
10# 별도 Query일 때 — N+1 라운드트립
11query Step1 { postsByAuthor { postId } }
12# 그 다음 클라이언트가 ID마다 따로:
13query Step2($id: ID!) { commentCount(postId: $id) }
14# 100개 post면 101번의 네트워크 호출

1# 카운트 필요 없는 화면
2query { postsByAuthor { postId title } }
3# → SQL: posts WHERE ... 만 실행. count 쿼리 0회.
4
5# 카운트 필요한 화면
6query { postsByAuthor { postId title commentCount } }
7# → SQL: posts + COUNT batch. 정확히 필요한 만큼.

1@ObjectType()
2class PostOutput {
3  @Field()
4  title: string;        // ← DB 컬럼. 함수 없음. 인자 받을 수가 없음.
5
6  @Field()
7  status: PostStatus;   // ← 같음. 그냥 데이터.
8}
9
10// vs
11
12@Resolver(() => PostOutput)
13class PostResolver {
14  @ResolveField(() => [CommentOutput])
15  comments(
16    @Parent() post,
17    @Args('limit', { nullable: true }) limit?: number,  // ← 함수가 있으니 인자 받음
18  ) { ... }
19}

1type User {
2  userId: ID!
3  name: String!
4  posts(status: PostStatus, orderBy: PostOrder): [Post!]!  # ResolveField에 자기 인자
5  followers(limit: Int): [User!]!                           # 자기만의 인자
6}

1query {
2  user(input: { userId: "U1" }) {       # ← Query 진입점에 인자 1번
3    name                                # ← 정적 필드 (인자 없음)
4
5    publishedPosts: posts(status: PUBLISHED) {   # ← 모서리에 인자 + alias
6      postId
7      title
8    }
9
10    drafts: posts(status: DRAFT) {                # ← 같은 모서리 다른 인자
11      postId
12      title
13    }
14
15    followers(limit: 10) {                        # ← 또 다른 모서리에 또 다른 인자
16      userId
17      name
18    }
19  }
20}

1{
2  "user": {
3    "publishedPosts": [...],
4    "drafts": [...],
5    "followers": [...]
6  }
7}

1query {
2  user(input: { userId: "U1" }) {     # ← 이 인자는 user에만
3    name                                # ← 인자 못 받음 (정적 필드)
4
5    posts(status: PUBLISHED) {          # ← 이 인자는 posts에만
6      postId                             # ← 인자 못 받음 (정적 필드)
7      title                              # ← 인자 못 받음 (정적 필드)
8
9      comments(limit: 10) {              # ← 이 인자는 comments에만
10        content                           # ← 인자 못 받음
11      }
12    }
13  }
14}

1// ❌ REST식 — 진입점이 Input마다 늘어남
2type Query {
3  userById(id: ID!): User
4  userByEmail(email: String!): User
5  userByPhone(phone: String!): User
6  userByGoogleId(googleId: String!): User
7}
8
9// ✅ GraphQL식 — 한 진입점에 유연한 Input
10type Query {
11  user(input: UserInput!): User      # 진입점 1개
12}
13
14input UserInput {
15  userId: ID
16  email: String
17  phone: String
18  googleId: String
19}
20# 4개 중 하나만 채우면 됨 (서비스에서 분기)

1// ❌
2@Mutation()
3updateUser(input: UpdateUserInput) { ... }   // input에 password, email 등 다 들어있음

1// ✅ — 의도별로 분리
2@Mutation() changeEmail(...)
3@Mutation() changePassword(...)
4@Mutation() updateProfile(...)   // name, avatar 등 비민감 필드만

1// ❌
2@Mutation(() => DeleteCommentOutput)   // { success, message }
3async deleteComment(...) { ... }
4
5// ✅
6@Mutation(() => Post)                  // 영향받은 부모 반환
7async deleteComment(...) {
8  await this.commentService.deleteComment(...);
9  return this.postService.findById(commentPostId);  // 갱신된 post
10}

1mutation {
2  deleteComment(input: { commentId: "C1" }) {
3    postId
4    comments {        # ← 갱신된 comment 리스트가 한 번에 옴
5      commentId
6      content
7    }
8  }
9}

1// ❌ 호출 측에서 두 개를 묶는다
2mutation {
3  createUser(...) { ... }
4  createOrganization(...) { ... }
5}
6// → 첫 번째가 성공하고 두 번째가 실패하면? 부분 성공의 지옥
7
8// ✅ 백엔드에서 한 트랜잭션으로 묶어 새 mutation 제공
9mutation {
10  signUpWithOrganization(input: ...) { user { ... } organization { ... } }
11}

1// ❌ 중복 호출 시 2번 결제됨
2@Mutation()
3async chargePayment(input: { amount: Money }) { ... }
4
5// ✅ 클라이언트 idempotency key
6@Mutation()
7async chargePayment(input: {
8  amount: Money,
9  idempotencyKey: ID!     // 같은 키로 재호출 시 같은 결과 반환
10}) { ... }

1// ❌
2@Mutation() validatePost(...) { ... }     // 1단계
3@Mutation() changeStatus(...) { ... }      // 2단계
4@Mutation() sendNotification(...) { ... }  // 3단계
5// → 클라이언트가 3번 라운드트립. 부분 실패 위험.
6
7// ✅
8@Mutation() publishPost(...) {
9  // 검증 + 상태변경 + 알림을 한 트랜잭션으로
10}

1// ❌ — REST PATCH 방식
2@Mutation()
3updateUser(input: UpdateUserInput) {
4  // input에 email, password, profile, settings, role 다 받음
5  // 안에서 if/else로 분기
6}
7
8// ✅ — 의도별로 분리
9@Mutation() changeEmail(...)
10@Mutation() changePassword(...)
11@Mutation() updateProfile(...)
12@Mutation() updateSettings(...)
13@Mutation() changeRole(...)        // 권한 다름

1// modules/post/loaders/post-comments.loader.ts
2@Injectable()
3export class PostCommentsLoader {
4  create(): DataLoader<number, CommentEntity[]> {
5    return new DataLoader<number, CommentEntity[]>(async (postIds: readonly number[]) => {
6      const comments = await this.commentRepository.find({
7        where: { postId: In(postIds) },
8        order: { createdAt: 'ASC' },
9      });
10      const byPost = new Map<number, CommentEntity[]>();
11      for (const comment of comments) {
12        const list = byPost.get(comment.postId) ?? [];
13        list.push(comment);
14        byPost.set(comment.postId, list);
15      }
16      return postIds.map((postId) => byPost.get(postId) ?? []);
17      //                                                   ^^^^^
18      //                                   빈 배열은 여기서 만들어진다
19    });
20  }
21}

1[1] 클라이언트
2    query { postsByAuthor(...) { postId comments { content } } }
3        │
4        ▼
5[2] PostResolver.postsByAuthor()
6    → PostEntity[] 10개 반환 (예: id 1~10)
7        │
8        ▼
9[3] NestJS가 각 Post에 대해 PostResolver.comments()를 10번 호출
10    comments(post: Post#1)  → loaders.postComments.load(1)
11    comments(post: Post#2)  → loaders.postComments.load(2)
12    ...
13    comments(post: Post#10) → loaders.postComments.load(10)
14        │
15        ▼ DataLoader가 같은 tick의 .load() 호출들을 배치로 묶음
16[4] DataLoader batch 함수가 1번 호출됨
17    keys = [1, 2, 3, ..., 10]
18        │
19        ▼
20[5] SQL: SELECT * FROM comments WHERE post_id IN (1,2,...,10)
21        │
22        ▼
23[6] Map에 그룹화: byPost = { 1: [c1,c2,c3], 3: [c4] }
24        │
25        ▼
26[7] return postIds.map((id) => byPost.get(id) ?? [])
27    → [
28        [c1,c2,c3],   // post 1
29        [],           // post 2 ← 빈 배열! (Map에 없으니 ??가 발동)
30        [c4],         // post 3
31        [],           // post 4 ← 빈 배열
32        ...
33      ]

1return postIds.map((postId) => byPost.get(postId) ?? []);
2//                                                  ^^^^^
3//                          ← 여기. 댓글 없는 post는 빈 배열

1// To-one loader
2return ids.map((id) => byId.get(id) ?? null);
3//                                   ^^^^^^^
4//                       ← 여기는 null (1:1 관계니까)

1query PostsByAuthor($input: PostsByAuthorInput!) {
2  postsByAuthor(input: $input) {
3    postId
4    ...
5  }
6}

1query PostsByAuthor($input: ...) { ... }
2#     ^^^^^^^^^^^^^
3#     이건 그냥 라벨. 자유롭게 바꿔도 됨.

1query MyAwesomeQuery($input: ...) {       # ← 이름만 바꿔도 OK
2  postsByAuthor(input: $input) { ... }     # ← 이건 schema의 실제 필드라 못 바꿈
3}

1{ postsByAuthor(input: $input) { ... } }
2#  ^^^^^^^^^^^^^
3#  schema.gql의 type Query 안에 정의된 진짜 필드. 백엔드의 @Query() 메서드명과 매칭.

1query PostsByAuthor($input: PostsByAuthorInput!) {
2#     "이번 요청의 별명"          "이번 요청의 입력 변수"
3  postsByAuthor(input: $input) {
4# "서버의 어떤 함수를 부르는가"  "그 함수의 인자"
5    ...
6  }
7}

1type PostOutput {
2  postId: ID!
3  title: String!
4  content: String
5  status: PostStatus!
6  publishedAt: DateTime
7  createdAt: DateTime!
8  updatedAt: DateTime!
9
10  # 관계 — ResolveField, 모두 XxxOutput으로 통일
11  author: UserOutput!
12  cover: CoverOutput
13  tags: [TagOutput!]!
14  comments: [CommentOutput!]!
15}

1@ObjectType('Tag')   // ← Entity를 GraphQL 타입으로 직접 등록
2@Entity('tags')
3export class TagEntity {
4  // ...
5}

1@ObjectType()
2export class TagOutput extends OmitType(
3  TagEntity,
4  ['id', 'deletedAt', 'searchVector'] as const,  // 숨길 필드만 명시
5  ObjectType
6) {}

1새 데이터 요구사항
2       │
3       ▼
4어느 도메인 노드의 무엇인가?
5       │
6   ┌───┴───┐
7  속성?    완전히 새 도메인?
8   │           │
9   ▼           ▼
10ResolveField  새 Output + 새 Query
11추가          (드물어야 함)
12   │
13   ▼
14끝.

1새 타입을 만들고 싶다
2       │
3       ▼
4정말 새 도메인 개념인가?
5       │
6   ┌───┴───┐
7  YES        NO (같은 도메인의 다른 표현)
8   │          │
9   ▼          ▼
10새 Output    원래 Output에 ResolveField 추가
11+ 모서리    + 클라이언트가 select로 모양 결정
12선언          (여기서 90% 해결)

1새 Query를 만들고 싶다
2       │
3       ▼
4이게 진입점인가, 기존 노드의 속성인가?
5       │
6   ┌───┴───┐
7  진입점     기존 노드 속성
8   │          │
9   ▼          ▼
10새 Query     ResolveField로 추가
11추가          (Query에 추가하지 않음)
12   │
13   ▼
14같은 도메인의 여러 lookup이면
15하나의 Query + 유연한 Input으로 통합

1type Query {
2  commentsByPost(input: CommentsByPostInput!): [CommentOutput!]!
3}
4
5type PostOutput {
6  comments: [CommentOutput!]!   # ← 같은 데이터에 도달하는 다른 길
7}

1@ObjectType()
2export class DeleteCommentOutput {
3  @Field() success!: boolean;   // 항상 true
4  @Field() message!: string;    // 안내 문구
5}

1@Mutation(() => PublishDraftsOutput)   // { publishedCount }
2async publishMyDrafts(...) { ... }