如何消除Nest.js控制器方法中路由名称的重复定义？

问题背景 #

在前后端共享类型的Nest.js系统中，控制器代码存在路由名称重复的冗余问题，且容易出现路由路径与类型不匹配的误用：

@Controller()
export class MyController {
  
  @ApplyRoute('GET /foo')
  async findAll(
    @Query() { name }: Routes['GET /foo']['query'], // 重复路由名称
  ): Promise<Routes['GET /foo']['response']> { // 重复路由名称
    return { foo: true }
  }
}

GET /foo重复出现三次：用于声明HTTP方法/路径、获取查询参数类型、约束返回类型。

系统的路由类型定义与装饰器实现如下：

// 全局路由类型定义
type Routes = {
  'GET /foo': {
    query: { name: string }
    response: { foo: true }
  }

  'GET /bar': {
    query: {},
    response: { bar: true }
  }
}

// ApplyRoute装饰器实现
export function ApplyRoute(routeName: keyof Routes): MethodDecorator {
  const [method, path] = routeName.split(' ') as ['GET' | 'POST', string]
  return applyDecorators(
    RequestMapping({ path, method: RequestMethod[method] }),
  )
}

我们希望实现类似以下的简洁写法（示例语法）：

@Controller()
export class MyController {
  
  @ApplyRoute('GET /foo') {
    async findAll(
      @Query() { name }: CurrentRoute['query'],
    ): Promise<CurrentRoute['response']> {
      return { foo: true }
    }
  }
}

解决方案 #

方案1：局部类型别名复用路由键 #

通过在控制器内定义局部类型别名，一次性绑定路由键，后续直接复用：

@Controller()
export class MyController {
  
  @ApplyRoute('GET /foo')
  async findAll(
    @Query() { name }: Route['query'],
  ): Promise<Route['response']> {
    return { foo: true }
  }
}

// 与方法绑定的局部类型别名，仅需定义一次路由键
type Route = Routes['GET /foo']

该方案简单直接，代码侵入性低，能快速消除重复。

方案2：结合satisfies运算符（TypeScript 4.9+推荐） #

利用TypeScript 4.9新增的satisfies运算符，确保路由键的合法性，同时通过字面量类型推断自动关联路由类型：

@Controller()
export class MyController {
  // 用satisfies确保路由键属于Routes的有效键，同时保留字面量类型
  private readonly route = 'GET /foo' satisfies keyof Routes;
  
  @ApplyRoute(this.route)
  async findAll(
    @Query() { name }: Routes[typeof this.route]['query'],
  ): Promise<Routes[typeof this.route]['response']> {
    return { foo: true }
  }
}

该方案兼顾类型安全与代码简洁性，是新版本TypeScript下的最优选择。

方案3：元数据+类型工具实现自动关联 #

通过装饰器存储路由元数据，配合类型工具提取当前方法对应的路由类型：

// 修改ApplyRoute为带元数据存储的泛型装饰器
export function ApplyRoute<T extends keyof Routes>(routeName: T) {
  const [method, path] = routeName.split(' ') as ['GET' | 'POST', string];
  const requestDecorator = RequestMapping({ path, method: RequestMethod[method] });

  return function(target: any, propertyKey: string) {
    requestDecorator(target, propertyKey);
    // 存储路由名称到元数据
    Reflect.defineMetadata('routeKey', routeName, target, propertyKey);
  };
}

// 类型工具：从控制器方法中提取对应的路由类型
type CurrentRoute<C, M extends keyof C> = Routes[typeof Reflect.getMetadata('routeKey', C.prototype, M)]

在控制器中使用：

@Controller()
export class MyController {
  
  @ApplyRoute('GET /foo')
  async findAll(
    @Query() { name }: CurrentRoute<MyController, 'findAll'>['query'],
  ): Promise<CurrentRoute<MyController, 'findAll'>['response']> {
    return { foo: true }
  }
}

该方案彻底消除路由键的重复书写，适合需要高度灵活类型关联的场景。

总结 #

• 快速改造选方案1，代码改动最小；
• 使用TypeScript 4.9+选方案2，兼顾简洁与类型安全；
• 追求极致类型关联选方案3，通过元数据实现自动绑定。

内容的提问来源于stack exchange，提问作者Alex Wayne