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

type Post { ... }
type PostWithCommentsOutput { ... }       # 같은 도메인인데 다른 타입?
type Article { ... }
type ArticleWithTagsOutput { ... }         # 또?

type Query {
  commentsByPost(...): [CommentOutput!]!  # Post.comments로 이미 도달 가능한데?
}

type DeleteCommentOutput {
  success: Boolean!     # 항상 true
  message: String!      # 한국어로 박혀있음
}

type PostOutput {
  tags: [Tag!]               # 어떤 건 Entity 직노출
  comments: [CommentOutput!]! # 어떤 건 Output 접미사
  cover: CoverOutput          # 일관성 없음
}

// ❌ REST 사고 — 화면 단위 응답
@Query(() => DashboardOutput)
async getDashboard(@Args('userId') userId: string) {
  const user = await this.userService.findOne(userId);
  const posts = await this.postService.findByUser(userId);
  const comments = await this.commentService.findByPosts(posts.map(p => p.id));
  return { user, posts, comments };  // 화면 전용 응답
}

// ✅ GraphQL 사고 — 도메인 모델 그대로 노출
@Resolver(() => User)
class UserResolver {
  @ResolveField(() => [Post])
  posts(@Parent() user: User) {
    return this.postLoader.load(user.id);
  }
}

@Resolver(() => Post)
class PostResolver {
  @ResolveField(() => [Comment])
  comments(@Parent() post: Post) {
    return this.commentLoader.load(post.id);
  }
}

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

// 1. Service: DB에서 Entity를 끌어온다
async findByAuthor(authorId: string): Promise<PostEntity[]> {
  return this.repo.findBy({ authorId });
  // → PostEntity 인스턴스 배열. 메모리에 실재.
}

// 2. Resolver: Entity를 그대로 반환. 단지 "선언"만 Output으로
@Query(() => [PostOutput])
async postsByAuthor(...): Promise<PostOutput[]> {
  return this.postService.findByAuthor(...);
  // → 실제로는 PostEntity[]를 반환.
  // → TS는 OK (PostOutput extends OmitType(PostEntity))
}

// 3. NestJS GraphQL: Entity 인스턴스를 받아서 schema의 PostOutput에 따라 직렬화
//    → schema에 선언된 필드만 골라서 응답에 넣는다
//    → ResolveField가 있는 필드는 메서드 호출해서 채운다

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

@Resolver(() => PostOutput)  // ← 이 인자가 어떤 의미를 갖는가?
export class PostResolver {

  @Query(() => [PostOutput])
  postsByAuthor(...) { ... }            // (A) 그래프 진입점

  @Mutation(() => PostOutput)
  publishPost(...) { ... }              // (A) 그래프 진입점

  @ResolveField(() => CoverOutput)
  cover(@Parent() post) { ... }         // (B) PostOutput 타입의 한 필드
}

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

// modules/post/post.resolver.ts
@Resolver(() => PostOutput)
export class PostResolver {
  @ResolveField(() => CoverOutput)
  cover(@Parent() post) { ... }            // Post → Cover 모서리
}

// modules/cover/cover.resolver.ts
@Resolver(() => CoverOutput)
export class CoverResolver {
  @ResolveField(() => PostOutput, { nullable: true })
  post(@Parent() cover) { ... }            // Cover → Post 역방향 모서리

  @ResolveField(() => UserOutput)
  uploadedBy(@Parent() cover) { ... }
}

┌─────────────────────────────────────────────────────────┐
│  schema.gql (그래프의 지도 — 모든 도메인이 모여 그려짐)        │
│                                                          │
│   type Post {                                            │
│     postId: ID!                                          │
│     cover: Cover           ◄──┐ PostResolver가          │
│     comments: [Comment!]!  ◄──┤ ResolveField로 추가      │
│   }                                                      │
│                                                          │
│   type Cover {                                           │
│     coverId: ID!                                         │
│     uploadedBy: User       ◄──┐ CoverResolver가         │
│     post: Post             ◄──┤ ResolveField로 추가      │
│   }                                                      │
└─────────────────────────────────────────────────────────┘

modules/post/                        modules/cover/
├── post.entity.ts                    ├── cover.entity.ts
├── post.output.ts                    ├── cover.output.ts  ◄── 여기!
├── post.resolver.ts                  ├── cover.resolver.ts
│   @Resolver(() => PostOutput)       │   @Resolver(() => CoverOutput)
│     @ResolveField cover()           │     @ResolveField uploadedBy()
│     @ResolveField comments()        │     @ResolveField post()
└── post.service.ts                   └── cover.service.ts
        ↓                                     ↓
   CoverOutput을 import해서            PostOutput을 import해서
   ResolveField의 반환 타입으로 선언    ResolveField의 반환 타입으로 선언

도메인 노드      ↔   GraphQL 타입       ↔   Output 클래스
───────────────────────────────────────────────────────
User            ↔   type User            ↔   UserOutput
Post            ↔   type Post            ↔   PostOutput
Comment         ↔   type Comment         ↔   CommentOutput
Tag             ↔   type Tag             ↔   TagOutput
Cover           ↔   type Cover           ↔   CoverOutput

type Post {
  postId, title, status
}

type PostWithCommentsOutput {   # ← 화면 전용 타입
  postId, title, status
  comments: [Comment!]!
}

type Article {
  articleId, headline, ...
}

type ArticleWithTagsOutput {   # ← 또 화면 전용 타입
  articleId, headline, ...
  tags: [Tag!]!
  author: UserOutput!
}

type Post {
  postId, title, status
  comments: [Comment!]!  # ResolveField
  myReaction: Reaction   # ResolveField
}

type Query {
  post(input: PostInput!): Post!         # 한 타입
  myPosts(input: MyPostsInput!): [Post!]! # 같은 타입
}

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

@ObjectType()
export class PostWithStatsOutput extends PostOutput {
  @Field(() => Int)
  commentCount!: number;
}

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

function createPostFieldsResolver<T>(typeRef: Type<T>) {
  @Resolver(() => typeRef, { isAbstract: true })
  abstract class PostFieldsResolverHost {
    @ResolveField(() => CoverOutput, { nullable: true })
    cover(@Parent() post, @Loaders() loaders) {
      return loaders.postCover.load(post.id);
    }
    @ResolveField(() => [CommentOutput])
    comments(@Parent() post, @Loaders() loaders) {
      return loaders.postComments.load(post.id);
    }
  }
  return PostFieldsResolverHost;
}

@Resolver(() => PostOutput)
export class PostResolver extends createPostFieldsResolver(PostOutput) {}

@Resolver(() => PostWithStatsOutput)
export class PostWithStatsResolver extends createPostFieldsResolver(PostWithStatsOutput) {
  @ResolveField(() => Int)
  commentCount(@Parent() post) { ... }
}

// ✅ 더 좋은 답
@Resolver(() => PostOutput)
export class PostResolver {
  // 기존 ResolveField들...

  // 새 필드는 그냥 ResolveField 추가
  @ResolveField(() => Int)
  commentCount(@Parent() post) {
    return loaders.postCommentCount.load(post.id);
  }

  @ResolveField(() => Boolean)
  isMine(@Parent() post, @User() user) {
    return post.authorId === user.userId;
  }
}

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

# 가벼운 화면
query { postsByAuthor { postId title } }

# 통계가 필요한 화면
query { postsByAuthor { postId title commentCount } }

@Resolver(() => Post)
class PostResolver {
  // 정적 필드는 entity의 컬럼에서 자동
  // 모든 파생/관계/계산은 ResolveField로 한 타입에 모인다

  @ResolveField(() => CoverOutput, { nullable: true })
  cover(...) { ... }                     // ← 1:1 관계

  @ResolveField(() => [CommentOutput])
  comments(...) { ... }                   // ← 1:N 관계

  @ResolveField(() => UserOutput)
  author(...) { ... }                     // ← N:1 관계

  @ResolveField(() => Int)
  commentCount(...) { ... }               // ← 집계 파생

  @ResolveField(() => Boolean)
  isMine(...) { ... }                     // ← 권한 파생

  @ResolveField(() => Boolean)
  canEdit(...) { ... }                    // ← 권한 파생

  @ResolveField(() => PostStats)
  stats(...) { ... }                      // ← 통계 묶음 (또 다른 노드)
}

새 데이터 요구사항
       │
       ▼
어느 도메인 노드의 무엇인가?
       │
   ┌───┴───┐
  속성?    완전히 새 도메인?
   │           │
   ▼           ▼
ResolveField  새 Output + 새 Query
추가          (드물어야 함)
   │
   ▼
끝.

# ❌ REST 사고방식 — 새 entry point 추가
type Query {
  postsByAuthor(input: ...): [PostOutput!]!
  commentCount(postId: ID!): Int!              # ← 새 query
  postAuthor(postId: ID!): UserOutput!         # ← 또 새 query
  postCommentList(postId: ID!): [Comment!]!    # ← 또 새 query
}

# ✅ GraphQL 사고방식 — 기존 노드에 모서리 추가
type Query {
  postsByAuthor(input: ...): [PostOutput!]!  # 진입점은 그대로
}

type PostOutput {
  postId: ID!
  title: String!
  commentCount: Int!         # ← ResolveField로 추가
  author: UserOutput!        # ← ResolveField
  comments: [CommentOutput!]! # ← ResolveField
}

# ResolveField일 때 — 한 번의 query
query {
  postsByAuthor(input: ...) {
    postId
    title
    commentCount     # 같이 가져옴
  }
}

# 별도 Query일 때 — N+1 라운드트립
query Step1 { postsByAuthor { postId } }
# 그 다음 클라이언트가 ID마다 따로:
query Step2($id: ID!) { commentCount(postId: $id) }
# 100개 post면 101번의 네트워크 호출

# 카운트 필요 없는 화면
query { postsByAuthor { postId title } }
# → SQL: posts WHERE ... 만 실행. count 쿼리 0회.

# 카운트 필요한 화면
query { postsByAuthor { postId title commentCount } }
# → SQL: posts + COUNT batch. 정확히 필요한 만큼.

@ObjectType()
class PostOutput {
  @Field()
  title: string;        // ← DB 컬럼. 함수 없음. 인자 받을 수가 없음.

  @Field()
  status: PostStatus;   // ← 같음. 그냥 데이터.
}

// vs

@Resolver(() => PostOutput)
class PostResolver {
  @ResolveField(() => [CommentOutput])
  comments(
    @Parent() post,
    @Args('limit', { nullable: true }) limit?: number,  // ← 함수가 있으니 인자 받음
  ) { ... }
}

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

query {
  user(input: { userId: "U1" }) {       # ← Query 진입점에 인자 1번
    name                                # ← 정적 필드 (인자 없음)

    publishedPosts: posts(status: PUBLISHED) {   # ← 모서리에 인자 + alias
      postId
      title
    }

    drafts: posts(status: DRAFT) {                # ← 같은 모서리 다른 인자
      postId
      title
    }

    followers(limit: 10) {                        # ← 또 다른 모서리에 또 다른 인자
      userId
      name
    }
  }
}

{
  "user": {
    "publishedPosts": [...],
    "drafts": [...],
    "followers": [...]
  }
}

query {
  user(input: { userId: "U1" }) {     # ← 이 인자는 user에만
    name                                # ← 인자 못 받음 (정적 필드)

    posts(status: PUBLISHED) {          # ← 이 인자는 posts에만
      postId                             # ← 인자 못 받음 (정적 필드)
      title                              # ← 인자 못 받음 (정적 필드)

      comments(limit: 10) {              # ← 이 인자는 comments에만
        content                           # ← 인자 못 받음
      }
    }
  }
}

// ❌ REST식 — 진입점이 Input마다 늘어남
type Query {
  userById(id: ID!): User
  userByEmail(email: String!): User
  userByPhone(phone: String!): User
  userByGoogleId(googleId: String!): User
}

// ✅ GraphQL식 — 한 진입점에 유연한 Input
type Query {
  user(input: UserInput!): User      # 진입점 1개
}

input UserInput {
  userId: ID
  email: String
  phone: String
  googleId: String
}
# 4개 중 하나만 채우면 됨 (서비스에서 분기)

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

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

// ❌
@Mutation(() => DeleteCommentOutput)   // { success, message }
async deleteComment(...) { ... }

// ✅
@Mutation(() => Post)                  // 영향받은 부모 반환
async deleteComment(...) {
  await this.commentService.deleteComment(...);
  return this.postService.findById(commentPostId);  // 갱신된 post
}

mutation {
  deleteComment(input: { commentId: "C1" }) {
    postId
    comments {        # ← 갱신된 comment 리스트가 한 번에 옴
      commentId
      content
    }
  }
}

// ❌ 호출 측에서 두 개를 묶는다
mutation {
  createUser(...) { ... }
  createOrganization(...) { ... }
}
// → 첫 번째가 성공하고 두 번째가 실패하면? 부분 성공의 지옥

// ✅ 백엔드에서 한 트랜잭션으로 묶어 새 mutation 제공
mutation {
  signUpWithOrganization(input: ...) { user { ... } organization { ... } }
}

// ❌ 중복 호출 시 2번 결제됨
@Mutation()
async chargePayment(input: { amount: Money }) { ... }

// ✅ 클라이언트 idempotency key
@Mutation()
async chargePayment(input: {
  amount: Money,
  idempotencyKey: ID!     // 같은 키로 재호출 시 같은 결과 반환
}) { ... }

// ❌
@Mutation() validatePost(...) { ... }     // 1단계
@Mutation() changeStatus(...) { ... }      // 2단계
@Mutation() sendNotification(...) { ... }  // 3단계
// → 클라이언트가 3번 라운드트립. 부분 실패 위험.

// ✅
@Mutation() publishPost(...) {
  // 검증 + 상태변경 + 알림을 한 트랜잭션으로
}

// ❌ — REST PATCH 방식
@Mutation()
updateUser(input: UpdateUserInput) {
  // input에 email, password, profile, settings, role 다 받음
  // 안에서 if/else로 분기
}

// ✅ — 의도별로 분리
@Mutation() changeEmail(...)
@Mutation() changePassword(...)
@Mutation() updateProfile(...)
@Mutation() updateSettings(...)
@Mutation() changeRole(...)        // 권한 다름

// modules/post/loaders/post-comments.loader.ts
@Injectable()
export class PostCommentsLoader {
  create(): DataLoader<number, CommentEntity[]> {
    return new DataLoader<number, CommentEntity[]>(async (postIds: readonly number[]) => {
      const comments = await this.commentRepository.find({
        where: { postId: In(postIds) },
        order: { createdAt: 'ASC' },
      });
      const byPost = new Map<number, CommentEntity[]>();
      for (const comment of comments) {
        const list = byPost.get(comment.postId) ?? [];
        list.push(comment);
        byPost.set(comment.postId, list);
      }
      return postIds.map((postId) => byPost.get(postId) ?? []);
      //                                                   ^^^^^
      //                                   빈 배열은 여기서 만들어진다
    });
  }
}

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

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

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

query PostsByAuthor($input: PostsByAuthorInput!) {
  postsByAuthor(input: $input) {
    postId
    ...
  }
}

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

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

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

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

type PostOutput {
  postId: ID!
  title: String!
  content: String
  status: PostStatus!
  publishedAt: DateTime
  createdAt: DateTime!
  updatedAt: DateTime!

  # 관계 — ResolveField, 모두 XxxOutput으로 통일
  author: UserOutput!
  cover: CoverOutput
  tags: [TagOutput!]!
  comments: [CommentOutput!]!
}

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

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

새 데이터 요구사항
       │
       ▼
어느 도메인 노드의 무엇인가?
       │
   ┌───┴───┐
  속성?    완전히 새 도메인?
   │           │
   ▼           ▼
ResolveField  새 Output + 새 Query
추가          (드물어야 함)
   │
   ▼
끝.

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

새 Query를 만들고 싶다
       │
       ▼
이게 진입점인가, 기존 노드의 속성인가?
       │
   ┌───┴───┐
  진입점     기존 노드 속성
   │          │
   ▼          ▼
새 Query     ResolveField로 추가
추가          (Query에 추가하지 않음)
   │
   ▼
같은 도메인의 여러 lookup이면
하나의 Query + 유연한 Input으로 통합

type Query {
  commentsByPost(input: CommentsByPostInput!): [CommentOutput!]!
}

type PostOutput {
  comments: [CommentOutput!]!   # ← 같은 데이터에 도달하는 다른 길
}

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

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