在现代Node.js后端开发中，Fastify凭借其高性能和丰富插件生态，正逐渐成为Express以外的主流选择。然而，一个长期困扰开发者的问题是：当使用TypeScript编写Fastify应用时，如何避免在路由层和控制器层重复定义数据传输对象（DTO）类型？近日，这一话题在Stack Overflow和GitHub社区引发热议，众多开发者分享了自己的实践方案。本文将深入剖析这一痛点，并梳理出几种行之有效的解决路径。

痛点：重复代码的代价

假设我们有一个典型的用户注册接口。在控制器中，我们定义了CreateUserDto接口：

interface CreateUserDto {
  username: string;
  email: string;
  password: string;
}

然而在Fastify路由定义中，为了启用schema验证和自动序列化，往往需要再次声明几乎相同的类型：

fastify.post('/users', {
  schema: {
    body: {
      type: 'object',
      properties: {
        username: { type: 'string' },
        email: { type: 'string', format: 'email' },
        password: { type: 'string', minLength: 8 }
      },
      required: ['username', 'email', 'password']
    }
  }
}, async (request, reply) => {
  const dto = request.body as CreateUserDto;
  // ...控制器逻辑
});

这种重复不仅增加了维护成本——当DTO字段变更时必须同时修改两处，还容易引发类型错位错误。更糟糕的是，TypeScript静态类型检查与Fastify运行时的schema验证是割裂的，你可能在编译时通过了检查，却在运行时遭遇意料之外的字段缺失。

社区涌现的四种主流解法

1. 基于TypeBox的类型派生

Fastify官方推荐的TypeBox库允许你定义JSON Schema的同时生成TypeScript类型。通过Type.Static操作符，你可以从schema自动推导出DTO类型：

import { Type, Static } from '@sinclair/typebox';

const CreateUserSchema = Type.Object({
  username: Type.String(),
  email: Type.String({ format: 'email' }),
  password: Type.String({ minLength: 8 })
});

type CreateUserDto = Static<typeof CreateUserSchema>;

fastify.post('/users', {
  schema: { body: CreateUserSchema }
}, async (request) => {
  const dto = request.body as CreateUserDto;
  // 使用dto...
});

这种方法实现了“schema即类型”——修改schema后，DTO类型自动更新，零重复。但代价是需要学习TypeBox的API，且对于复杂的嵌套验证规则，表达式可能略显冗长。

2. 使用class-validator + class-transformer

如果你来自NestJS生态，或许更熟悉基于类装饰器的做法。通过装饰器同时定义验证和类型：

import { IsString, IsEmail, MinLength } from 'class-validator';
import { Expose } from 'class-transformer';

class CreateUserDto {
  @Expose() @IsString() username: string;
  @Expose() @IsEmail() email: string;
  @Expose() @IsString() @MinLength(8) password: string;
}

然后在Fastify路由中使用plainToClass和validate：

import { plainToClass } from 'class-transformer';
import { validate } from 'class-validator';

fastify.post('/users', async (request) => {
  const dto = plainToClass(CreateUserDto, request.body, { excludeExtraneousValues: true });
  const errors = await validate(dto);
  if (errors.length > 0) {
    throw new Error('Validation failed');
  }
  // 使用dto...
});

这种方式为习惯于面向对象风格的开发者提供了熟悉的体验，但由于class-validator在Fastify中并非原生支持，需要手动注入错误处理逻辑，额外增加了一定工作量。

3. 自定义Fastify装饰器

更激进的做法是编写一个自定义装饰器，将类与路由schema绑定。例如，参考NestJS的@Body()装饰器设计：

function ValidateBody<T>(dtoClass: new () => T) {
  return (target: Object, propertyKey: string, descriptor: PropertyDescriptor) => {
    const original = descriptor.value;
    descriptor.value = async function (request: FastifyRequest, reply: FastifyReply) {
      const dto = plainToClass(dtoClass, request.body, { excludeExtraneousValues: true });
      const errors = await validate(dto);
      if (errors.length) {
        reply.code(400).send({ errors });
        return;
      }
      request.body = dto;
      return original.call(this, request, reply);
    };
  };
}

然后在控制器中使用：

class UserController {
  @ValidateBody(CreateUserDto)
  async createUser(request: FastifyRequest, reply: FastifyReply) {
    const dto = request.body as CreateUserDto;
    // ...
  }
}

这种方案实现了极致的DRY（Don't Repeat Yourself），但需要理解装饰器元编程，且可能与Fastify的路由注册流程产生耦合。

4. 拥抱TypeScript的as const与模板字面量

对于追求轻量级的场景，可以利用TypeScript 4.1+的模板字面量类型和as const，将JSON Schema定义直接作为类型：

const schema = {
  body: {
    type: 'object',
    properties: {
      username: { type: 'string' } as const,
      email: { type: 'string', format: 'email' } as const,
      password: { type: 'string', minLength: 8 } as const
    },
    required: ['username', 'email', 'password'] as const
  }
} as const;

type SchemaBody = typeof schema.body;
type DTO = {
  [K in keyof SchemaBody['properties']]: 
    SchemaBody['properties'][K] extends { type: 'string' } ? string : never;
};

// 注意：该方案仅适用于简单类型，不支持嵌套对象和复杂校验

这种方法无需任何外部库，但表达能力有限，且容易因类型推断细节出错，更适合快速原型阶段。

专家观点：选择应基于团队与项目规模

“没有银弹。”Fastify核心贡献者之一Matteo Collina在一次线上分享中指出，“选择哪种模式取决于你的团队背景和项目的生命周期。如果项目需要高度一致的API文档（如OpenAPI），强烈建议使用TypeBox，因为它能与@fastify/swagger完美集成。如果团队更偏向面向对象，class-validator配合一个简单的中间件包装也不错。”

事实上，GitHub上已有多个Fastify脚手架项目将TypeBox作为默认配置。例如，Fastify官方维护的create-fastify-app CLI工具在TypeScript模板中内建了TypeBox支持，极大降低了入门门槛。

未来展望：Fastify自身是否能解决？

有开发者已在Fastify的GitHub仓库提交RFC，建议增加装饰器机制或schemaFromDto的辅助函数，使框架能直接从类定义生成schema。虽然目前尚未被合并，但社区动态表明这一需求得到了核心团队的关注。与此同时，TypeB ox的维护者也在计划推出更高级的元数据反射支持，向NestJS的体验靠拢。

结论

工具的选择本质上是对开发体验与维护成本的权衡。对于新项目，建议优先采用TypeBox方案，既能享受JSON Schema原生性能优势，又可避免类型重复。对于已有大量基于class-validator的项目，可以逐步将Fastify路由封装为装饰器模式。无论选择哪条路径，核心原则始终如一：让类型定义只出现一次，让代码与文档自动同步。毕竟，在软件工程中，消除重复不仅是美学追求，更是降低认知负荷、防止缺陷的根本手段。