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

HTTP RPC 사양

비공식 베타 번역

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

메서드와 타입 매핑​

HTTP MethodMappingNotes
GET.query()Input JSON-stringified in query param.
e.g. myQuery?input=${encodeURIComponent(JSON.stringify(input))}
POST.mutation()Input as POST body.
GET.subscription()Subscriptions are supported via Server-sent Events using httpSubscriptionLink, or via WebSockets using wsLink.

중첩 프로시저 접근​

중첩 프로시저는 점(dot)으로 구분되므로, 아래의 byId 요청은 최종적으로 /api/trpc/post.byId 경로로 요청됩니다.

ts
export const appRouter = router({
  post: router({
    byId: publicProcedure.input(String).query(async (opts) => {
      // [...]
    }),
  }),
});
ts
export const appRouter = router({
  post: router({
    byId: publicProcedure.input(String).query(async (opts) => {
      // [...]
    }),
  }),
});

일괄 처리(Batching)​

일괄 처리 시 동일한 HTTP 메서드를 사용하는 모든 병렬 프로시저 호출을 데이터 로더를 활용해 단일 요청으로 결합합니다.

  • 호출된 프로시저 이름은 pathname에서 쉼표(,)로 결합됩니다.

  • 입력 매개변수는 Record<number, unknown> 형태의 input 쿼리 매개변수로 전송됩니다.

  • batch=1 쿼리 매개변수를 반드시 전달해야 합니다.

  • 응답에 서로 다른 상태 코드가 섞여 있을 경우 207 Multi-Status를 반환합니다 (예: 한 호출은 실패하고 다른 호출은 성공한 경우)

일괄 처리 요청 예시​

/api/trpc에 노출된 라우터 예시:​

server/router.ts
tsx
export const appRouter = t.router({
  postById: t.procedure.input(String).query(async (opts) => {
    const post = await opts.ctx.post.findUnique({
      where: { id: opts.input },
    });
    return post;
  }),
  relatedPosts: t.procedure.input(String).query(async (opts) => {
    const posts = await opts.ctx.findRelatedPostsById(opts.input);
    return posts;
  }),
});
server/router.ts
tsx
export const appRouter = t.router({
  postById: t.procedure.input(String).query(async (opts) => {
    const post = await opts.ctx.post.findUnique({
      where: { id: opts.input },
    });
    return post;
  }),
  relatedPosts: t.procedure.input(String).query(async (opts) => {
    const posts = await opts.ctx.findRelatedPostsById(opts.input);
    return posts;
  }),
});

... React 컴포넌트 내 정의된 두 쿼리:​

MyComponent.tsx
tsx
export function MyComponent() {
  const post1 = trpc.postById.useQuery('1');
  const relatedPosts = trpc.relatedPosts.useQuery('1');
 
  return (
    <pre>
      {JSON.stringify(
        {
          post1: post1.data ?? null,
          relatedPosts: relatedPosts.data ?? null,
        },
        null,
        4,
      )}
    </pre>
  );
}
MyComponent.tsx
tsx
export function MyComponent() {
  const post1 = trpc.postById.useQuery('1');
  const relatedPosts = trpc.relatedPosts.useQuery('1');
 
  return (
    <pre>
      {JSON.stringify(
        {
          post1: post1.data ?? null,
          relatedPosts: relatedPosts.data ?? null,
        },
        null,
        4,
      )}
    </pre>
  );
}

위 쿼리는 다음 데이터와 함께 단일 HTTP 호출 발생:​

Location propertyValue
pathname/api/trpc/postById,relatedPosts
search?batch=1&input=%7B%220%22%3A%221%22%2C%221%22%3A%221%22%7D *

*) 상기 input은 다음의 결과입니다:

ts
encodeURIComponent(
  JSON.stringify({
    0: '1', // <-- input for `postById`
    1: '1', // <-- input for `relatedPosts`
  }),
);
ts
encodeURIComponent(
  JSON.stringify({
    0: '1', // <-- input for `postById`
    1: '1', // <-- input for `relatedPosts`
  }),
);

일괄 처리 응답 예시​

Example output from server
json
[
  // result for `postById`
  {
    "result": {
      "data": {
        "id": "1",
        "title": "Hello tRPC",
        "body": "..."
        // ...
      }
    }
  },
  // result for `relatedPosts`
  {
    "result": {
      "data": [
        /* ... */
      ]
    }
  }
]
json
[
  // result for `postById`
  {
    "result": {
      "data": {
        "id": "1",
        "title": "Hello tRPC",
        "body": "..."
        // ...
      }
    }
  },
  // result for `relatedPosts`
  {
    "result": {
      "data": [
        /* ... */
      ]
    }
  }
]

HTTP 응답 사양​

전송 계층에 무관한 사양 구현을 위해 가능한 범위 내에서 JSON-RPC 2.0을 준수합니다.

성공 응답​

Example JSON Response
json
{
  "result": {
    "data": {
      "id": "1",
      "title": "Hello tRPC",
      "body": "..."
    }
  }
}
json
{
  "result": {
    "data": {
      "id": "1",
      "title": "Hello tRPC",
      "body": "..."
    }
  }
}
ts
interface SuccessResponse {
  result: {
    data: TOutput; // output from procedure
  }
}
ts
interface SuccessResponse {
  result: {
    data: TOutput; // output from procedure
  }
}

오류 응답​

Example JSON Response
json
[
  {
    "error": {
      "json": {
        "message": "Something went wrong",
        "code": -32600, // JSON-RPC 2.0 code
        "data": {
          // Extra, customizable, meta data
          "code": "INTERNAL_SERVER_ERROR",
          "httpStatus": 500,
          "stack": "...",
          "path": "post.add"
        }
      }
    }
  }
]
json
[
  {
    "error": {
      "json": {
        "message": "Something went wrong",
        "code": -32600, // JSON-RPC 2.0 code
        "data": {
          // Extra, customizable, meta data
          "code": "INTERNAL_SERVER_ERROR",
          "httpStatus": 500,
          "stack": "...",
          "path": "post.add"
        }
      }
    }
  }
]

  • 가능한 경우 발생한 오류의 HTTP 상태 코드를 전파합니다.

  • 응답에 서로 다른 상태 코드가 섞여 있을 경우 207 Multi-Status를 반환합니다 (예: 한 호출은 실패하고 다른 호출은 성공한 경우)

  • 오류 처리 및 커스터마이징 방법은 오류 형식 지정 참조

오류 코드와 HTTP 상태 매핑​

ts
const HTTP_STATUS_CODES = {
  PARSE_ERROR: 400,
  BAD_REQUEST: 400,
  UNAUTHORIZED: 401,
  PAYMENT_REQUIRED: 402,
  FORBIDDEN: 403,
  NOT_FOUND: 404,
  METHOD_NOT_SUPPORTED: 405,
  TIMEOUT: 408,
  CONFLICT: 409,
  PRECONDITION_FAILED: 412,
  PAYLOAD_TOO_LARGE: 413,
  UNSUPPORTED_MEDIA_TYPE: 415,
  UNPROCESSABLE_CONTENT: 422,
  PRECONDITION_REQUIRED: 428,
  TOO_MANY_REQUESTS: 429,
  CLIENT_CLOSED_REQUEST: 499,
  INTERNAL_SERVER_ERROR: 500,
  NOT_IMPLEMENTED: 501,
  BAD_GATEWAY: 502,
  SERVICE_UNAVAILABLE: 503,
  GATEWAY_TIMEOUT: 504,
} as const;
ts
const HTTP_STATUS_CODES = {
  PARSE_ERROR: 400,
  BAD_REQUEST: 400,
  UNAUTHORIZED: 401,
  PAYMENT_REQUIRED: 402,
  FORBIDDEN: 403,
  NOT_FOUND: 404,
  METHOD_NOT_SUPPORTED: 405,
  TIMEOUT: 408,
  CONFLICT: 409,
  PRECONDITION_FAILED: 412,
  PAYLOAD_TOO_LARGE: 413,
  UNSUPPORTED_MEDIA_TYPE: 415,
  UNPROCESSABLE_CONTENT: 422,
  PRECONDITION_REQUIRED: 428,
  TOO_MANY_REQUESTS: 429,
  CLIENT_CLOSED_REQUEST: 499,
  INTERNAL_SERVER_ERROR: 500,
  NOT_IMPLEMENTED: 501,
  BAD_GATEWAY: 502,
  SERVICE_UNAVAILABLE: 503,
  GATEWAY_TIMEOUT: 504,
} as const;

오류 코드와 JSON-RPC 2.0 오류 코드 매핑​

Available codes & JSON-RPC code
ts
/**
 * JSON-RPC 2.0 Error codes
 *
 * `-32000` to `-32099` are reserved for implementation-defined server-errors.
 * For tRPC we're copying the last digits of HTTP 4XX errors.
 */
export const TRPC_ERROR_CODES_BY_KEY = {
  /**
   * Invalid JSON was received by the server.
   * An error occurred on the server while parsing the JSON text.
   */
  PARSE_ERROR: -32700,
  /**
   * The JSON sent is not a valid Request object.
   */
  BAD_REQUEST: -32600, // 400
 
  // Internal JSON-RPC error
  INTERNAL_SERVER_ERROR: -32603, // 500
  NOT_IMPLEMENTED: -32603, // 501
  BAD_GATEWAY: -32603, // 502
  SERVICE_UNAVAILABLE: -32603, // 503
  GATEWAY_TIMEOUT: -32603, // 504
 
  // Implementation specific errors
  UNAUTHORIZED: -32001, // 401
  PAYMENT_REQUIRED: -32002, // 402
  FORBIDDEN: -32003, // 403
  NOT_FOUND: -32004, // 404
  METHOD_NOT_SUPPORTED: -32005, // 405
  TIMEOUT: -32008, // 408
  CONFLICT: -32009, // 409
  PRECONDITION_FAILED: -32012, // 412
  PAYLOAD_TOO_LARGE: -32013, // 413
  UNSUPPORTED_MEDIA_TYPE: -32015, // 415
  UNPROCESSABLE_CONTENT: -32022, // 422
  PRECONDITION_REQUIRED: -32028, // 428
  TOO_MANY_REQUESTS: -32029, // 429
  CLIENT_CLOSED_REQUEST: -32099, // 499
} as const;
ts
/**
 * JSON-RPC 2.0 Error codes
 *
 * `-32000` to `-32099` are reserved for implementation-defined server-errors.
 * For tRPC we're copying the last digits of HTTP 4XX errors.
 */
export const TRPC_ERROR_CODES_BY_KEY = {
  /**
   * Invalid JSON was received by the server.
   * An error occurred on the server while parsing the JSON text.
   */
  PARSE_ERROR: -32700,
  /**
   * The JSON sent is not a valid Request object.
   */
  BAD_REQUEST: -32600, // 400
 
  // Internal JSON-RPC error
  INTERNAL_SERVER_ERROR: -32603, // 500
  NOT_IMPLEMENTED: -32603, // 501
  BAD_GATEWAY: -32603, // 502
  SERVICE_UNAVAILABLE: -32603, // 503
  GATEWAY_TIMEOUT: -32603, // 504
 
  // Implementation specific errors
  UNAUTHORIZED: -32001, // 401
  PAYMENT_REQUIRED: -32002, // 402
  FORBIDDEN: -32003, // 403
  NOT_FOUND: -32004, // 404
  METHOD_NOT_SUPPORTED: -32005, // 405
  TIMEOUT: -32008, // 408
  CONFLICT: -32009, // 409
  PRECONDITION_FAILED: -32012, // 412
  PAYLOAD_TOO_LARGE: -32013, // 413
  UNSUPPORTED_MEDIA_TYPE: -32015, // 415
  UNPROCESSABLE_CONTENT: -32022, // 422
  PRECONDITION_REQUIRED: -32028, // 428
  TOO_MANY_REQUESTS: -32029, // 429
  CLIENT_CLOSED_REQUEST: -32099, // 499
} as const;

기본 HTTP 메서드 재정의​

쿼리/뮤테이션에 사용되는 HTTP 메서드를 재정의하려면 methodOverride 옵션을 사용하세요:

server/httpHandler.ts
tsx
// Your server must separately allow the client to override the HTTP method
const handler = createHTTPHandler({
  router: router,
  allowMethodOverride: true,
});
server/httpHandler.ts
tsx
// Your server must separately allow the client to override the HTTP method
const handler = createHTTPHandler({
  router: router,
  allowMethodOverride: true,
});
client/trpc.ts
tsx
import { createTRPCClient, httpLink } from '@trpc/client';
import type { AppRouter } from './server';
 
// The client can then specify which HTTP method to use for all queries/mutations
const client = createTRPCClient<AppRouter>({
  links: [
    httpLink({
      url: `http://localhost:3000`,
      methodOverride: 'POST', // all queries and mutations will be sent to the tRPC Server as POST requests.
    }),
  ],
});
client/trpc.ts
tsx
import { createTRPCClient, httpLink } from '@trpc/client';
import type { AppRouter } from './server';
 
// The client can then specify which HTTP method to use for all queries/mutations
const client = createTRPCClient<AppRouter>({
  links: [
    httpLink({
      url: `http://localhost:3000`,
      methodOverride: 'POST', // all queries and mutations will be sent to the tRPC Server as POST requests.
    }),
  ],
});

심화 학습​

다음 TypeScript 정의 파일에서 상세 내용 확인 가능: