본문으로 건너뛰기
버전: 11.x

링크 개요

링크는 tRPC 클라이언트와 서버 간의 데이터 흐름을 사용자 정의할 수 있게 합니다. 링크는 하나의 기능만 수행해야 하며, 이는 tRPC 작업(쿼리, 뮤테이션, 또는 구독)에 대한 자체적으로 완결된 수정이거나 작업에 기반한 부수 효과(예: 로깅)일 수 있습니다.

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

tRPC Link DiagramtRPC 링크 다이어그램. Apollo의에 기반함.
utils/trpc.ts
ts
import { createTRPCClient, httpBatchLink, loggerLink } from '@trpc/client';
import type { AppRouter } from './server';
 
export const trpc = createTRPCClient<AppRouter>({
  links: [
    loggerLink(),
    httpBatchLink({
      url: 'http://localhost:3000',
    }),
  ],
});
utils/trpc.ts
ts
import { createTRPCClient, httpBatchLink, loggerLink } from '@trpc/client';
import type { AppRouter } from './server';
 
export const trpc = createTRPCClient<AppRouter>({
  links: [
    loggerLink(),
    httpBatchLink({
      url: 'http://localhost:3000',
    }),
  ],
});

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

  1. 링크는 매개변수가 없는 함수를 반환합니다. 이는 링크가 초기화되는 설정 단계로, 앱당 한 번만 발생하며 캐시나 기타 상태를 저장하는 데 유용합니다.
  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';
 
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';
 
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, httpBatchStreamLink, httpSubscriptionLink, wsLink, localLink 같은 다른 종단 링크를 사용할 수도 있습니다.

컨텍스트 관리​

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

op.context에 액세스하여 현재 컨텍스트 객체를 가져오고 수정합니다.

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

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