ts-rest/nest 框架中路由处理器的正确使用方式

问题背景

在使用 ts-rest 与 NestJS 集成时，开发者可能会遇到一个常见错误："impl is not a function"。这个错误通常发生在错误地使用了 @TsRestHandler 装饰器或者错误地组织了路由处理器的代码结构。

错误原因分析

这个错误的核心在于框架期望接收一个函数作为处理器实现，但实际接收到的却是一个对象。具体来说，当开发者直接返回一个包含 status 和 body 的对象时，框架会尝试将这个对象作为函数调用，从而引发错误。

正确使用方式

1. 使用 @TsRest 装饰器

对于简单的路由处理场景，应该使用 @TsRest 装饰器而非 @TsRestHandler。@TsRest 装饰器会自动处理返回值的封装：

@TsRest(UsersContract.findAll)
async findAll(
  @TsRestRequest() { query }: RequestShape['findAll'],
  @Res({ passthrough: true }) res: Response,
) {
  const data = await this.usersService.findAll(query.page, query.limit);
  return { status: 200 as const, body: data };
}

2. 使用 @TsRestHandler 的正确方式

如果需要更复杂的控制流程，可以使用 @TsRestHandler，但必须确保返回的是 tsRestHandler 函数：

@TsRestHandler(UsersContract.findAll)
async findAll() {
  return tsRestHandler(UsersContract.findAll, async ({ query }) => {
    const data = await this.usersService.findAll(query.page, query.limit);
    return { status: 200, body: data };
  });
}

3. 装饰器顺序的重要性

当使用多个装饰器时，@TsRestHandler 必须放在最前面，否则会导致框架无法正确初始化路由处理器：

// 正确顺序
@TsRestHandler(contract.posts.findMany)
@UseGuards(AbilitiesGuard)
@CheckAbilities({ action: Action.Read, subject: 'Post' })
findMany(@Req() req: RequestWithUser) {
  // 处理逻辑
}

最佳实践建议

1. 对于大多数简单场景，优先使用 @TsRest 装饰器，它更简洁且不易出错
2. 当需要复杂逻辑或自定义处理时，使用 @TsRestHandler 并确保返回 tsRestHandler 函数
3. 注意装饰器的顺序，保持 @TsRestHandler 在最前面
4. 类型安全是 ts-rest 的核心优势，确保返回类型与契约定义匹配

通过遵循这些实践，可以避免 "impl is not a function" 错误，并充分利用 ts-rest 与 NestJS 集成的强大功能。