如何在Express中强制JSON响应返回特定类型？

我们正在用Express + TypeScript开发API，要求所有接口必须返回特定格式的JSON响应，想给所有端点强制这个格式。原本打算覆盖Express处理器中Response对象的json()方法类型，但遇到了问题：找不到只覆盖这个特定方法的清晰方案。目前可选的两种方式都不理想：

• 完全覆盖所有Express类型，但需要重新声明所有类型而不只是单个函数签名（我们用了声明模块的方式）
• 用命名空间扩展Request接口的新类型，但没法覆盖已有类型

想咨询：

1. 是否可以仅覆盖单个函数的类型？
2. 如果不行，还有什么方法能在使用Response.json()时强制特定类型？

1. 仅覆盖Response.json()的类型（可行） #

你不需要完全重写所有Express类型，只需要在自定义的类型声明文件中局部重写Response接口的json方法即可。具体步骤：

1. 在项目根目录创建types/express.d.ts（或任意.d.ts文件，确保TypeScript能识别到）
2. 重新声明express-serve-static-core模块，仅修改Response接口的json方法：

// types/express.d.ts
import { Response as ExpressResponse } from 'express-serve-static-core';

// 定义你的强制响应格式类型
type ApiResponse<T = unknown> = {
  success: boolean;
  data?: T;
  message?: string;
};

declare module 'express-serve-static-core' {
  interface Response extends ExpressResponse {
    // 覆盖原json方法，强制传入ApiResponse类型
    json(body: ApiResponse): this;
  }
}

这样TypeScript就会强制要求你调用res.json()时必须传入符合ApiResponse格式的对象，不会影响Response接口的其他方法。

注意：如果你的项目中使用了@types/express，确保这个自定义声明文件被包含在tsconfig.json的include数组里。

2. 其他替代方案 #

如果上述类型覆盖的方式不符合你的需求，还可以用以下几种方式强制响应格式：

方案A：封装自定义响应函数 #

创建一个全局可用的包装函数，替代原生的res.json()：

// utils/response.ts
import { Response } from 'express';

type ApiResponse<T = unknown> = {
  success: boolean;
  data?: T;
  message?: string;
};

export const sendResponse = <T>(res: Response, data: ApiResponse<T>) => {
  return res.json(data);
};

在路由中使用：

// routes/user.ts
import { sendResponse } from '../utils/response';

router.get('/user', (req, res) => {
  // 这里必须传入符合ApiResponse格式的对象，否则TypeScript报错
  sendResponse(res, {
    success: true,
    data: { id: 1, name: 'John' }
  });
});

方案B：用中间件验证响应格式 #

可以写一个后置中间件，在响应发送前验证格式（适合运行时检查，配合类型检查使用）：

// middleware/validateResponse.ts
import { Request, Response, NextFunction } from 'express';

type ApiResponse<T = unknown> = {
  success: boolean;
  data?: T;
  message?: string;
};

export const validateResponse = (req: Request, res: Response, next: NextFunction) => {
  const originalJson = res.json;
  res.json = function(body: ApiResponse) {
    // 运行时验证格式
    if (typeof body.success !== 'boolean') {
      throw new Error('响应格式错误：success必须为布尔值');
    }
    return originalJson.call(this, body);
  };
  next();
};

然后在全局注册中间件：

// app.ts
import { validateResponse } from './middleware/validateResponse';

app.use(validateResponse);

方案C：使用类型断言+工具类型 #

如果不想修改全局类型，可以在每次调用res.json()时用类型断言强制检查：

type ApiResponse<T = unknown> = {
  success: boolean;
  data?: T;
  message?: string;
};

router.get('/user', (req, res) => {
  const response = {
    success: true,
    data: { id: 1, name: 'John' }
  } as const satisfies ApiResponse;
  
  res.json(response);
});

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