深入理解TRPC中的HTTP RPC规范-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_00184/article/details/148325840

深入理解TRPC中的HTTP RPC规范

trpc trpc/trpc 是一个用于 Rust 语言编写的 RPC 框架，支持服务端和客户端的多种通信协议和数据格式。适合在分布式系统中实现服务间的通信。特点是提供了高效的通信协议、简单易用的 API 和良好的可扩展性。项目地址: https://gitcode.com/gh_mirrors/tr/trpc

前言

TRPC是一个现代化的RPC框架，它通过TypeScript提供了类型安全的远程过程调用体验。本文将深入探讨TRPC中的HTTP RPC规范，帮助开发者理解其工作原理和最佳实践。

HTTP方法与TRPC操作类型的映射

TRPC将不同的HTTP方法与特定的操作类型相关联，这种设计既符合RESTful原则，又保持了RPC的灵活性：

| HTTP方法 | TRPC操作类型 | 说明 | | --------- | ---------------- | -------------------------------------------------------------------- | | GET | .query() | 输入参数会被JSON序列化后作为查询参数传递 | | POST | .mutation() | 输入参数作为POST请求体传递 | | 不适用 | .subscription()| HTTP传输不支持订阅操作，需使用WebSocket等其他协议 |

查询(Query)操作详解

GET请求对应的.query()操作适用于数据获取场景。TRPC会将输入参数序列化为JSON字符串，然后进行URL编码，最终作为查询参数附加到URL中。例如：

/api/trpc/getUser?input=%7B%22id%22%3A%22123%22%7D

这实际上是以下对象的编码结果：

{"id":"123"}

变更(Mutation)操作详解

POST请求对应的.mutation()操作适用于数据修改场景。与查询不同，变更操作将输入参数直接作为请求体发送，这避免了URL长度限制问题，也更适合传输大量数据。

批量请求处理机制

TRPC提供了一种高效的批量请求机制，可以将多个并行调用合并为单个HTTP请求，显著减少网络开销。

批量请求的工作原理

路径构造：将多个过程调用的名称用逗号连接，形成组合路径
参数传递：所有输入参数合并为一个对象，通过input查询参数传递
批量标识：必须包含batch=1查询参数以标识这是一个批量请求
响应处理：如果各调用结果状态不同，返回207 Multi-Status响应

实际应用示例

假设我们有以下两个查询需要同时执行：

获取ID为"1"的文章详情(postById)
获取相关文章列表(relatedPosts)

合并后的请求会具有以下特征：

路径：/api/trpc/postById,relatedPosts
查询参数：
- batch=1
- input=%7B%220%22%3A%221%22%2C%221%22%3A%221%22%7D

其中input参数解码后为：

{
  "0": "1",  // postById的输入
  "1": "1"   // relatedPosts的输入
}

服务器会返回一个数组，按请求顺序包含各个调用的结果。

HTTP响应规范

TRPC的HTTP响应设计参考了JSON-RPC 2.0规范，确保了跨传输层的一致性。

成功响应结构

{
  id: null;           // 固定为null，保持与JSON-RPC兼容
  result: {
    type: 'data';     // 固定为'data'
    data: TOutput;    // 过程调用的实际输出
  }
}

错误响应结构

错误响应包含丰富的诊断信息：

{
  id: null;
  error: {
    json: {
      message: string;       // 错误描述
      code: number;         // JSON-RPC 2.0错误码
      data: {               // 额外的元数据
        code: string;       // TRPC错误码
        httpStatus: number; // HTTP状态码
        stack?: string;    // 可选堆栈跟踪
        path: string;      // 调用路径
      }
    }
  }
}

错误代码映射

TRPC定义了完善的错误代码体系，并与HTTP状态码和JSON-RPC 2.0错误码建立了对应关系。

TRPC错误码与HTTP状态码对照

| TRPC错误码 | HTTP状态码 | | ------------------------ | ---------- | | PARSE_ERROR | 400 | | BAD_REQUEST | 400 | | UNAUTHORIZED | 401 | | FORBIDDEN | 403 | | NOT_FOUND | 404 | | METHOD_NOT_SUPPORTED | 405 | | TIMEOUT | 408 | | CONFLICT | 409 | | PRECONDITION_FAILED | 412 | | PAYLOAD_TOO_LARGE | 413 | | INTERNAL_SERVER_ERROR | 500 | | CLIENT_CLOSED_REQUEST | 499 |

TRPC错误码与JSON-RPC 2.0错误码对照

TRPC扩展了JSON-RPC 2.0规范，使用-32000到-32099范围内的代码表示实现定义的错误：

| TRPC错误码 | JSON-RPC 2.0代码 | | ------------------------ | ---------------- | | PARSE_ERROR | -32700 | | BAD_REQUEST | -32600 | | INTERNAL_SERVER_ERROR | -32603 | | UNAUTHORIZED | -32001 | | FORBIDDEN | -32003 | | NOT_FOUND | -32004 | | METHOD_NOT_SUPPORTED | -32005 | | TIMEOUT | -32008 | | CONFLICT | -32009 | | PRECONDITION_FAILED | -32012 | | PAYLOAD_TOO_LARGE | -32013 | | CLIENT_CLOSED_REQUEST | -32099 |