ts-rest 客户端强制200状态码响应的实现方案

背景介绍

在基于ts-rest构建API客户端时，开发者经常需要处理各种HTTP状态码响应。默认情况下，ts-rest客户端会返回包含状态码和响应体的联合类型，这意味着开发者必须显式检查状态码才能安全访问响应体数据。

问题分析

传统处理方式需要开发者编写冗余的状态检查代码，例如：

const data = await client.posts.create({
  body: {
    title: 'My Post',
    content: 'This is my post',
  },
});

if (data.status === 200) {
  console.log('Success');
} else {
  console.log('Something went wrong');
}

这种模式在简单场景下显得过于繁琐，特别是当开发者已经通过自定义API函数确保只返回200状态码时。

解决方案

方案一：严格状态码模式

1. 在路由定义中启用严格状态码检查：

const router = c.router({
  posts: {
    get: {
      method: 'GET',
      path: '/posts/:id',
      responses: {
        200: z.object({...}),
        404: null
      }
    }
  }
}, {
  strictStatusCodes: true
});

2. 结合throwOnUnknownStatus: true配置初始化客户端：

const client = initClient(contract, {
  baseUrl: '...',
  throwOnUnknownStatus: true
});

这种配置下：

• 仅定义200响应时，非200状态码会自动抛出错误
• 定义多个状态码时，需要显式处理每个状态码情况
• 响应体类型会自动推断为定义的类型或null

方案二：代理封装模式

通过创建代理包装器自动处理响应：

type Extract200Response<T> = T extends { status: 200; body: infer R } ? R : never;

function createNestedProxy<T>(client: T) {
  return new Proxy(client, {
    get(target, prop) {
      const original = target[prop];
      if (typeof original === 'function') {
        return async (...args) => {
          const result = await original(...args);
          if (result?.status === 200) return result.body;
          throw result;
        };
      }
      return original;
    }
  });
}

此方案特点：

• 自动解构200响应的body
• 非200响应自动抛出
• 保持类型安全

最佳实践建议

1. 简单API场景推荐使用严格状态码模式，配置简单且类型安全
2. 复杂场景需要处理多种状态码时，建议明确声明所有可能的响应状态
3. 代理模式适合需要统一错误处理的场景，但要注意类型转换的安全性

总结

ts-rest提供了灵活的状态码处理机制，开发者可以根据项目需求选择最适合的方案。通过合理配置，可以显著减少样板代码，提高开发效率，同时保持类型安全性。