如何将TypeScript接口与类型转换为JSON以实现Fastify互操作性

作为Fastify新手，不想重复编写JSON Schema是很合理的需求——毕竟TS接口已经定义了数据结构，直接复用能减少冗余。下面分开发阶段预生成和运行时动态转换两种场景给你具体方案：

一、开发阶段：提前生成JSON Schema文件 #

适合已经有成熟TS接口，想预先生成静态Schema文件供Fastify导入使用的场景，常用工具是typescript-json-schema。

步骤： #

1. 安装依赖：

npm install typescript-json-schema --save-dev

2. 编写你的TS接口（比如src/types.ts）：

export interface User {
  id: number;
  username: string;
  email?: string;
  isActive: boolean;
}

3. 用命令行生成Schema：

npx typescript-json-schema src/types.ts User --out src/schemas/user.json

• 解释：src/types.ts是你的类型文件路径，User是要生成Schema的接口名，--out指定输出的JSON文件路径。

4. 在Fastify路由中导入使用：

import fastify from 'fastify';
import userSchema from './schemas/user.json';

const app = fastify();

app.post('/users', {
  schema: {
    body: userSchema,
    response: {
      201: userSchema
    }
  }
}, async (req, res) => {
  // 处理请求，req.body会自动按Schema验证
  return req.body;
});

如果需要批量生成多个接口的Schema，可以写一个简单的Node脚本调用typescript-json-schema的API，避免手动执行命令。

二、运行时：用TypeBox动态转换（推荐） #

如果你希望直接在代码中用TS类型定义，同时自动生成JSON Schema供Fastify做验证，@sinclair/typebox是最优解——Fastify官方对它有原生支持，既能获得TS的类型检查，又能自动生成JSON Schema做运行时验证，完全不用手动写两份定义。

步骤： #

1. 安装依赖：

npm install @sinclair/typebox fastify-type-provider-typebox --save

2. 用TypeBox定义你的类型（和TS接口完全兼容，也可以把现有TS接口转为TypeBox格式）：

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

// 直接用TypeBox定义，同时具备TS类型和JSON Schema能力
const UserSchema = Type.Object({
  id: Type.Number(),
  username: Type.String(),
  email: Type.Optional(Type.String()),
  isActive: Type.Boolean()
});

// 导出对应的TS类型，方便业务代码复用
type User = Static<typeof UserSchema>;

// 如果要复用现有TS接口，直接映射为TypeBox结构即可
export interface LegacyUser {
  id: number;
  username: string;
  email?: string;
  isActive: boolean;
}
const LegacyUserSchema = Type.Strict(Type.Object({
  id: Type.Number(),
  username: Type.String(),
  email: Type.Optional(Type.String()),
  isActive: Type.Boolean()
}));

3. 配置Fastify使用TypeBox类型提供器：

import fastify from 'fastify';
import { TypeBoxTypeProvider } from 'fastify-type-provider-typebox';

// 创建Fastify实例时指定类型提供器，获得TS类型提示
const app = fastify().withTypeProvider<TypeBoxTypeProvider>();

4. 在路由中直接使用TypeBox类型作为Schema：

app.post('/users', {
  schema: {
    body: UserSchema,
    response: {
      201: UserSchema
    }
  }
}, async (req, res) => {
  // 这里req.body会自动获得TS类型提示，同时Fastify会用生成的JSON Schema做运行时验证
  return req.body;
});

这种方案的好处是：一次定义，同时获得编译时类型检查和运行时数据验证，完全不用手动维护JSON Schema，非常适合Fastify项目的长期维护。

额外提示 #

• 如果你的TS接口里有联合类型、枚举等复杂结构，typescript-json-schema和TypeBox都能很好地处理，不需要额外配置。
• Fastify本身也支持直接传入TypeBox类型作为Schema，不用手动转换，因为它内部会自动把TypeBox类型解析为JSON Schema。

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