Hoppa till huvudinnehållet
Version: 9.x

HTTP RPC-specifikation

Inofficiell Beta-översättning

Denna sida har översatts av PageTurner AI (beta). Inte officiellt godkänd av projektet. Hittade du ett fel? Rapportera problem →

Metoder <-> Typmappning​

HTTP MethodMappingNotes
GET.query()Input JSON-stringified in query param.
e.g. myQuery?input=${encodeURIComponent(JSON.stringify(input))
POST.mutation()Input as POST body.
n/a.subscription()Subscriptions are not supported in HTTP transport

Batchbearbetning​

Vid batchbearbetning kombinerar vi alla parallella procedure-anrop av samma typ i en enda begäran med hjälp av en data loader.

  • De anropade procedurernas namn kombineras med kommatecken (,) i pathname

  • Indataparametrar skickas som en query-parameter kallad input som har formen Record<number, unknown>.

  • Vi måste också skicka batch=1 som en query-parameter.

  • Om svaret innehåller olika statuskoder skickar vi tillbaka 207 Multi-Status (t.ex. om ett anrop misslyckades och ett annat lyckades)

Exempelförfrågan för batchbearbetning​

Med en router som denna exponerad på /api/trpc:​

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

... Och två queries definierade så här i en React-komponent:​

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

Ovanstående skulle resultera i exakt 1 HTTP-anrop med denna data:​

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 i ovanstående är resultatet av:

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`
  }),
);

Exempelsvar för batchbearbetning​

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

HTTP-svarsspecifikation​

För att ha en specifikation som fungerar oberoende av transportlagret försöker vi följa JSON-RPC 2.0 där möjligt.

Lyckat svar​

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

Felsvar​

Example JSON Response
json
[
  {
    "id": null,
    "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
[
  {
    "id": null,
    "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"
        }
      }
    }
  }
]

  • När möjligt propagerar vi HTTP-statuskoder från det kastade felet.

  • Om svaret innehåller olika statuskoder skickar vi tillbaka 207 Multi-Status (t.ex. om ett anrop misslyckades och ett annat lyckades)

  • För mer information om felhantering och hur du anpassar den, se Felformatering.

Felkoder <-> HTTP-status​

ts
PARSE_ERROR: 400,
BAD_REQUEST: 400,
NOT_FOUND: 404,
INTERNAL_SERVER_ERROR: 500,
UNAUTHORIZED: 401,
FORBIDDEN: 403,
TIMEOUT: 408,
CONFLICT: 409,
CLIENT_CLOSED_REQUEST: 499,
PRECONDITION_FAILED: 412,
PAYLOAD_TOO_LARGE: 413,
METHOD_NOT_SUPPORTED: 405,
ts
PARSE_ERROR: 400,
BAD_REQUEST: 400,
NOT_FOUND: 404,
INTERNAL_SERVER_ERROR: 500,
UNAUTHORIZED: 401,
FORBIDDEN: 403,
TIMEOUT: 408,
CONFLICT: 409,
CLIENT_CLOSED_REQUEST: 499,
PRECONDITION_FAILED: 412,
PAYLOAD_TOO_LARGE: 413,
METHOD_NOT_SUPPORTED: 405,

Felkoder <-> JSON-RPC 2.0-felkoder​

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,
  // Implementation specific errors
  UNAUTHORIZED: -32001, // 401
  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
  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,
  // Implementation specific errors
  UNAUTHORIZED: -32001, // 401
  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
  CLIENT_CLOSED_REQUEST: -32099, // 499
} as const;

Fördjupa dig​

Du kan läsa mer detaljer genom att granska TypeScript-definitionerna i