ORPC v0.23.0 发布：输入输出结构定制化新特性解析

ORPC（OpenAPI RPC Framework）是一个基于 TypeScript 的 API 开发框架，它通过结合 OpenAPI 规范和 RPC 模式，为开发者提供了类型安全和高效的 API 开发体验。最新发布的 v0.23.0 版本引入了一个重要的新特性——输入输出结构定制化功能，这为 API 的数据处理方式带来了更大的灵活性。

输入输出结构定制化功能详解

在 API 开发中，请求和响应的数据结构处理是一个核心关注点。ORPC v0.23.0 通过引入 inputStructure 和 outputStructure 配置项，让开发者能够根据实际需求选择最适合的数据处理方式。

输入结构配置（inputStructure）

inputStructure 提供了两种模式来处理传入的请求数据：

1. compact（紧凑模式）

   • 自动合并路径参数（params）与查询参数（query）或请求体（body）
   • 简化了输入处理，适用于简单的 API 场景
   • 减少了代码中处理不同来源参数的复杂度

2. detailed（详细模式）

   • 保持路径参数、查询参数、请求头和请求体的分离
   • 提供更精细的控制，适用于需要明确区分不同来源参数的复杂场景
   • 保留了完整的请求上下文信息

输出结构配置（outputStructure）

同样地，outputStructure 也提供了两种响应数据处理方式：

1. compact（紧凑模式）

   • 仅返回响应体内容
   • 简化了响应结构，适用于大多数基础 API 场景
   • 减少了不必要的数据传输

2. detailed（详细模式）

   • 分离响应头和响应体
   • 允许开发者精细控制响应头信息
   • 适用于需要自定义 HTTP 头的高级场景

实际应用示例

以下是一个使用详细模式的完整示例，展示了如何定义和处理具有复杂结构的 API：

os.route({
  inputStructure: 'detailed',  // 使用详细输入结构
  outputStructure: 'detailed' // 使用详细输出结构
})
.input(z.object({
  params: z.object({ id: z.string() }),      // 路径参数
  query: z.object({ search: z.string() }),   // 查询参数
  body: z.object({ name: z.string() }).optional(), // 请求体
}))
.handler((input) => ({
  body: { message: 'Hello' },                // 响应体
  headers: { 'x-header': 'value' },          // 自定义响应头
}));

这个示例清晰地展示了如何：

• 分别定义路径参数、查询参数和请求体
• 在处理器中返回包含响应体和自定义头的完整响应
• 保持输入输出结构的明确分离

技术实现细节

在底层实现上，ORPC 通过增强 Zod 模式验证的能力来支持这一特性。Zod 是一个强大的 TypeScript 模式验证库，ORPC 利用它来：

1. 根据选择的输入结构模式，自动重组或保持请求数据的原始结构
2. 对不同类型的参数进行统一的类型验证
3. 将复杂的模式定义转换为清晰的 OpenAPI 规范

值得注意的是，v0.23.0 还修复了 Zod 到 JSON Schema 转换过程中描述信息丢失的问题，进一步提升了文档生成的准确性。

适用场景分析

紧凑模式最适合：

• 简单的 CRUD 操作
• 快速原型开发
• 参数来源单一的 API 端点

详细模式则更适合：

• 需要精细控制 HTTP 头的 API
• 需要明确区分不同来源参数的复杂业务逻辑
• 需要向后兼容的历史 API
• 需要完整请求上下文的中间件处理

升级建议

对于现有项目，升级到 v0.23.0 后：

1. 评估现有 API 是否需要更精细的输入输出控制
2. 对于简单 API，可以考虑使用紧凑模式简化代码
3. 对于复杂 API，详细模式可以提供更好的可维护性
4. 注意检查 Zod 描述信息在文档生成中的表现

ORPC v0.23.0 的输入输出结构定制化功能为开发者提供了更灵活的数据处理方式，无论是构建简单的微服务还是复杂的企业级 API，都能找到合适的配置方案。这一特性的引入，进一步巩固了 ORPC 作为现代化 API 开发框架的地位。