NestJS 接口响应 Message 字段编写规范与最佳实践

引言

在构建后端服务时，接口响应不仅仅是数据的传递，更是系统状态的反馈。一个规范统一的 message 字段设计，能显著提升系统的可维护性，减少前后端沟通成本。

设计原则

简洁明了 提示语不宜过长，控制在 3~12 个汉字为宜。避免使用'完成了'、'OK'这类含糊词汇。

统一风格 同一项目内的接口建议遵循统一的动词 + 状态组合，例如：'获取数据成功'、'数据加载完成'。

上下文清晰 提示信息应体现操作对象，如'用户列表获取成功'，而非笼统的'获取成功'。

NestJS 实现方案

在实际开发中，我们通常通过全局异常过滤器和统一的响应 DTO 来落地这些规范。

// 统一响应结构
export class ApiResponse<T> {
  success: boolean;
  message: string;
  data?: T;
}

// 全局异常过滤器示例
@Injectable()
export class AllExceptionsFilter implements ExceptionFilter {
  catch(exception: HttpException, host: ArgumentsHost) {
    const ctx = host.switchToHttp();
    const response = ctx.getResponse();
    const status = exception.getStatus();

    // 这里可以统一处理错误 message
    response.json({
      success: false,
      message: exception.message || '服务器内部错误',
      data: null,
    });
  }
}

注意，实际运行时建议将具体业务错误码映射到友好的中文提示，日志层保留详细堆栈以便排查。

消息分类与模板

为了兼顾前端展示与后台日志，我们可以对 message 进行分层设计。

获取数据成功、数据加载完成、操作成功、保存成功、更新成功、删除成功。