NestJS 接口响应 message 编写规范与 API 提示信息标准化

前言

在现代后端开发中，接口响应不仅仅是数据的传递，还承担着向前端或用户传递操作状态和结果的功能。一个规范、统一的 message 字段设计，可以显著提升系统的可维护性、前端开发效率和用户体验。

定义

响应结构示例（NestJS 风格） 各字段作用

提示信息设计原则

• 简洁明了
  1. 不宜过长，一般 3~12 个汉字。
  2. 避免含糊不清的词，如'完成了'、'OK'等。
• 统一风格
  1. 同一项目接口建议使用统一动词 + 状态组合，例如：获取数据成功、数据加载完成。
• 上下文清晰
  1. 提示信息应体现操作对象或类型，如'用户列表获取成功'而不是'获取成功'。
• 可扩展与模板化
  1. 对于多类型数据返回，可使用模板化语法。
  2. 如设备列表获取成功、订单数据获取成功。
• 面向用户与面向开发分层
  1. 前端提示：简短易懂，强调用户操作状态。
  2. 后台日志 / 文档：正式、完整，便于排查接口状态。

提示信息风格分类

• 简洁风格（前端显示）
• 正式 / 日志风格（后台接口 / 接口文档）
• 带数量 / 上下文提示
• 带操作指引提示

提示信息模板化设计

• 模板 为了统一风格和减少重复代码，可设计模板。
• 输出 用户列表获取成功，共 10 条。
• 模板化好处
  1. 统一风格，易维护
  2. 可动态生成提示内容
  3. 可适配多语言（国际化）

国际化与多语言支持

• 模板 在国际化项目中，message 应使用语言文件或翻译 key，避免硬编码。
• 好处
  1. 适配不同语言
  2. 前端可直接展示翻译内容
  3. 后端日志仍可使用统一 key 便于排查

最佳实践

• 前端提示短小清晰
  1. 数据加载完成、获取数据成功
• 后台 / 日志提示正式完整
  1. 数据已成功获取、列表数据已返回
• 数量提示增加用户反馈
  1. 列表数据获取成功，共${list.length}条
• 模板化 + 动态内容
  1. 提高复用率，降低出错率
• 避免模糊词
  1. 不使用'OK'、'完成了'、'操作成功了'
  2. 必须明确操作对象、状态或数量

参考示例（NestJS 响应）

1. 前端显示，用户列表获取成功，共 10 条
2. 日志可记录 status+message 用于接口监控

总结

1. message 字段是接口的重要组成部分，承担操作反馈和提示作用。