FoalTS 中如何优雅地验证子控制器路径参数

在构建基于 FoalTS 框架的 RESTful API 时，路径参数验证是一个常见需求。本文将深入探讨如何在 FoalTS 中高效地实现路径参数的验证，特别是在控制器嵌套场景下的最佳实践。

路径参数验证的基本方法

FoalTS 提供了 @ValidatePathParam 装饰器来验证路径参数。基本用法是在控制器方法上添加装饰器：

@Get('/:id')
@ValidatePathParam('id', { type: 'string', format: 'uuid' })
async getUser(ctx: Context) {
  // 方法实现
}

这种方式对于简单路由非常有效，但当路由结构变得复杂时，特别是使用嵌套控制器时，就会出现重复验证的问题。

嵌套控制器场景的挑战

在大型应用中，我们经常使用控制器嵌套来组织路由。例如：

export class ParentController {
  subControllers = [
    controller('/:versionId/child', ChildController)
  ];
}

传统做法是在每个子控制器的方法上都添加 @ValidatePathParam 装饰器，这会导致大量重复代码，降低了代码的可维护性。

类级别验证的解决方案

FoalTS 支持将 @ValidatePathParam 装饰器直接应用于控制器类，这样装饰器会作用于该控制器的所有方法：

@ValidatePathParam('versionId', { type: 'string', format: 'uuid' })
export class ChildController {
  @Get()
  async getHandler(ctx: Context) {
    // 自动验证 versionId
  }

  @Post()
  async postHandler(ctx: Context) {
    // 同样自动验证 versionId
  }
}

这种方法的优势在于：

1. 减少代码重复，提高可维护性
2. 确保所有相关路由的一致性验证
3. 使代码结构更加清晰

验证规则的设计考虑

在设计路径参数验证时，需要考虑以下几点：

1. 参数类型：明确参数应该是字符串、数字还是其他类型
2. 格式要求：如 UUID、日期格式等特殊格式
3. 业务规则：参数是否需要满足特定的业务逻辑条件
4. 错误处理：统一的错误响应格式

实际应用建议

在实际项目中，建议：

1. 对于共享同一参数的多个路由，使用类级别验证
2. 保持验证规则的集中管理，便于后期修改
3. 考虑创建自定义验证装饰器来处理复杂业务规则
4. 编写单元测试确保验证逻辑的正确性

通过合理利用 FoalTS 的装饰器特性，可以构建出既简洁又健壮的 API 验证层，显著提升代码质量和开发效率。