본문 바로가기
버전: 11.x

링크 개요

비공식 베타 번역

이 페이지는 PageTurner AI로 번역되었습니다(베타). 프로젝트 공식 승인을 받지 않았습니다. 오류를 발견하셨나요? 문제 신고 →

링크는 tRPC 클라이언트와 서버 간 데이터 흐름을 커스터마이징할 수 있게 해줍니다. 각 링크는 단일 기능을 수행해야 하며, 이는 tRPC 작업(쿼리, 뮤테이션, 구독)에 대한 독립적인 수정이나 로깅과 같은 작업 기반 사이드 이펙트가 될 수 있습니다.

여러 링크를 배열로 조합하여 tRPC 클라이언트 설정의 links 속성에 제공할 수 있으며, 이는 링크 체인을 나타냅니다. 즉 tRPC 클라이언트는 요청 시 links 배열에 추가된 순서대로 링크를 실행하고, 응답 처리 시에는 역순으로 다시 실행합니다. 다음은 링크 체인의 시각적 표현입니다:

tRPC Link DiagramtRPC Link Diagram. Based on Apollo's.
참고

아래 예제들은 Next.js를 사용한다고 가정하지만, 일반 tRPC 클라이언트를 사용할 때도 동일하게 추가할 수 있습니다

utils/trpc.ts
tsx
import { httpBatchLink, loggerLink } from '@trpc/client';
import { createTRPCNext } from '@trpc/next';
export default createTRPCNext<AppRouter>({
  config() {
    const url = `http://localhost:3000`;
    return {
      links: [
        loggerLink(),
        httpBatchLink({
          url,
        }),
      ],
    };
  },
});
utils/trpc.ts
tsx
import { httpBatchLink, loggerLink } from '@trpc/client';
import { createTRPCNext } from '@trpc/next';
export default createTRPCNext<AppRouter>({
  config() {
    const url = `http://localhost:3000`;
    return {
      links: [
        loggerLink(),
        httpBatchLink({
          url,
        }),
      ],
    };
  },
});

커스텀 링크 생성​

링크는 TRPCLink 타입을 따르는 함수입니다. 각 링크는 세 부분으로 구성됩니다:

  1. 링크는 TRPCClientRuntime 타입의 매개변수를 갖는 함수를 반환합니다. 이 인자는 tRPC가 전달하며 종료 링크 생성 시 사용됩니다. 종료 링크를 생성하지 않는 경우 매개변수가 없는 함수를 생성하면 됩니다. 이 경우 링크는 호출 없이 links 배열에 추가됩니다(links: [..., myLink, httpBatchLink(...)]).

  2. 1단계 함수는 두 가지 속성을 가진 객체를 매개변수로 받는 또 다른 함수를 반환합니다: op는 클라이언트가 실행 중인 Operation이며, next는 체인에서 다음 링크를 호출하는 데 사용하는 함수입니다.

  3. 2단계 함수는 @trpc/server가 제공하는 observable 함수를 반환하는 최종 함수를 반환합니다. observable은 observer를 받는 함수를 허용하며, 이는 링크가 작업 결과를 처리하는 방법을 상위 체인에 알리는 데 도움을 줍니다. 이 함수에서 next(op)를 반환해 그대로 둘 수도 있고, next를 구독하여 링크가 작업 결과를 처리하도록 할 수 있습니다.

예시​

utils/customLink.ts
tsx
import { TRPCLink } from '@trpc/client';
import { observable } from '@trpc/server/observable';
import type { AppRouter } from '~/server/routers/_app';
export const customLink: TRPCLink<AppRouter> = () => {
  // here we just got initialized in the app - this happens once per app
  // useful for storing cache for instance
  return ({ next, op }) => {
    // this is when passing the result to the next link
    // each link needs to return an observable which propagates results
    return observable((observer) => {
      console.log('performing operation:', op);
      const unsubscribe = next(op).subscribe({
        next(value) {
          console.log('we received value', value);
          observer.next(value);
        },
        error(err) {
          console.log('we received error', err);
          observer.error(err);
        },
        complete() {
          observer.complete();
        },
      });
      return unsubscribe;
    });
  };
};
utils/customLink.ts
tsx
import { TRPCLink } from '@trpc/client';
import { observable } from '@trpc/server/observable';
import type { AppRouter } from '~/server/routers/_app';
export const customLink: TRPCLink<AppRouter> = () => {
  // here we just got initialized in the app - this happens once per app
  // useful for storing cache for instance
  return ({ next, op }) => {
    // this is when passing the result to the next link
    // each link needs to return an observable which propagates results
    return observable((observer) => {
      console.log('performing operation:', op);
      const unsubscribe = next(op).subscribe({
        next(value) {
          console.log('we received value', value);
          observer.next(value);
        },
        error(err) {
          console.log('we received error', err);
          observer.error(err);
        },
        complete() {
          observer.complete();
        },
      });
      return unsubscribe;
    });
  };
};

참고 자료​

커스텀 링크 생성에 대한 실제 참고 자료가 필요하다면, tRPC가 제공하는 내장 링크 일부를 GitHub에서 확인할 수 있습니다.

종료 링크​

종료 링크는 링크 체인의 마지막 링크입니다. next 함수를 호출하는 대신, 종료 링크는 구성된 tRPC 작업을 tRPC 서버로 전송하고 OperationResultEnvelope를 반환할 책임이 있습니다.

tRPC 클라이언트 설정에 추가하는 links 배열에는 최소한 하나의 링크가 있어야 하며, 이 링크는 종료 링크여야 합니다. links 끝에 종료 링크가 없으면 tRPC 작업이 tRPC 서버로 전송되지 않습니다.

httpBatchLink는 tRPC가 권장하는 종료 링크입니다.

httpLink, wsLink, localLink는 다른 종료 링크의 예시입니다.

컨텍스트 관리​

작업이 링크 체인을 따라 이동할 때 각 링크가 읽고 수정할 수 있는 컨텍스트를 유지합니다. 이를 통해 링크들은 실행 로직에서 사용할 메타데이터를 체인을 따라 전달할 수 있습니다.

현재 컨텍스트 객체를 얻고 수정하려면 op.context에 접근하세요.

특정 작업에 대한 컨텍스트 객체의 초기값을 설정하려면 query 또는 useQuery 훅(또는 mutation, subscription 등)에 context 매개변수를 제공하면 됩니다.

사용 예제는 특정 요청에 대한 배치 비활성화를 참조하세요.