如何为Express.js的res.json定义默认响应结构类型？

要实现让res.json必须包含message和error字段，同时支持自定义额外数据，你可以通过扩展Express的类型定义来实现，具体步骤如下：

1. 定义统一的响应类型 #

先创建一个包含必填字段的基础类型，再通过泛型支持自定义的额外数据：

// 可以放在项目的types/express.d.ts文件中
type BaseResponse = {
  message: string;
  error: boolean;
};

// 泛型类型，允许拼接自定义数据字段
type ApiResponse<T = Record<string, never>> = BaseResponse & T;

2. 扩展Express的Response接口 #

在类型定义文件中覆盖原生Response的json方法，限制它只能接收我们定义的ApiResponse类型：

declare global {
  namespace Express {
    interface Response {
      json: <T = Record<string, never>>(body: ApiResponse<T>) => this;
    }
  }
}

// 标记文件为模块，避免全局类型冲突
export {};

3. 在路由中使用增强后的类型 #

现在路由里的res.json会自动校验字段完整性，缺少message或error时TypeScript会直接报错：

import { Request, Response } from 'express';
import Product from './models/Product';

export const getProduct = async (
  req: Request<{ id: string }, {}, {}>,
  res: Response
): Promise<void> => {
  const productId = req.params.id;
  const foundProduct = await Product.findOne({ _id: productId });

  // ✅ 正确用法：包含必填字段+自定义数据
  res.status(200).json({
    message: "Product found",
    error: false,
    product: foundProduct
  });

  // ❌ 错误用法：缺少必填字段，TypeScript会抛出错误提示
  // res.status(200).json({ product: foundProduct });
};

补充说明 #

• 确保tsconfig.json的include配置包含你的类型定义文件路径，比如"include": ["src/**/*", "types/**/*"]
• 如果需要区分成功/错误响应的不同结构，可以进一步拆分出SuccessResponse和ErrorResponse，核心思路都是通过扩展Express类型实现约束

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