服务端之NestJS接口响应message编写规范详解、写给前后端都舒服的接口、API提示信息标准化

前言

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

定义

响应结构示例（NestJS风格）

1return {
2   status: 200, // 可选，HTTP状态码
3   message: '获取数据成功', // 提示信息
4   data: {
5       list, // 数据列表
6       page: 1, // 当前页
7       size: 10, // 每页数量
8       total: list.length // 数据总数
9   }
10};
11

各字段作用

字段	类型	说明
status	number	HTTP或自定义状态码，用于程序判断
message	string	操作反馈信息，可显示给用户或用于日志
data	object	实际返回的数据对象，包含列表、分页或其他信息

提示信息设计原则

简洁明了 1、不宜过长，一般3~12个汉字。 2、避免含糊不清的词，如“完成了”、“OK”等。

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

上下文清晰 1、提示信息应体现操作对象或类型，如“用户列表获取成功”而不是“获取成功”。

可扩展与模板化 1、对于多类型数据返回，可使用模板化语法：
1message: `${dataType}获取成功`
2
2、如设备列表获取成功、订单数据获取成功

面向用户与面向开发分层 1、前端提示：简短易懂，强调用户操作状态。 2、后台日志 / 文档：正式、完整，便于排查接口状态。

提示信息风格分类

简洁风格（前端显示）

场景示例
通用成功获取数据成功、操作成功
列表数据数据加载完成、列表加载成功
数据更新更新成功、保存成功

正式 / 日志风格（后台接口 / 接口文档）

场景示例
数据获取数据已成功获取、列表数据已返回
数据更新数据更新操作已完成、保存操作成功
数据删除删除操作已完成、记录已成功删除

带数量 / 上下文提示

场景示例
列表数据已成功获取用户列表，共15条数据
分页数据列表数据获取成功，共10条记录，当前页1
操作反馈设备列表加载完成，共20条可用设备

带操作指引提示

场景示例
后续操作提示数据加载成功，可进行下一步操作
页面跳转提示数据获取成功，请查看详情
用户操作操作成功，数据已更新

场景	示例
通用成功	获取数据成功、操作成功
列表数据	数据加载完成、列表加载成功
数据更新	更新成功、保存成功

场景	示例
数据获取	数据已成功获取、列表数据已返回
数据更新	数据更新操作已完成、保存操作成功
数据删除	删除操作已完成、记录已成功删除

场景	示例
列表数据	已成功获取用户列表，共15条数据
分页数据	列表数据获取成功，共10条记录，当前页1
操作反馈	设备列表加载完成，共20条可用设备

场景	示例
后续操作提示	数据加载成功，可进行下一步操作
页面跳转提示	数据获取成功，请查看详情
用户操作	操作成功，数据已更新

提示信息模板化设计

模板 为了统一风格和减少重复代码，可设计模板：

1function buildMessage(dataType: string, action: '获取' | '加载' | '更新' | '删除', extra?: string) {
2   return `${dataType}${action}成功${extra ? `，${extra}` : ''}`;
3}
4
5// 示例
6message: buildMessage('用户列表', '获取', `共 ${list.length} 条`)
7

输出：用户列表获取成功，共10条

模板化好处： 1、统一风格，易维护 2、可动态生成提示内容 3、可适配多语言（国际化）

国际化与多语言支持

模板 在国际化项目中，message应使用语言文件或翻译key，避免硬编码：

1return {
2   message: i18n.__('data.fetch_success'),  // 英文：Data fetched successfully
3   data
4};
5

好处 1、适配不同语言 2、前端可直接展示翻译内容 3、后端日志仍可使用统一key便于排查

最佳实践

前端提示短小清晰 1、数据加载完成、获取数据成功

后台 / 日志提示正式完整 1、数据已成功获取、列表数据已返回

数量提示增加用户反馈 1、列表数据获取成功，共${list.length}条

模板化 + 动态内容 1、提高复用率，降低出错率

避免模糊词 1、不使用“OK”、“完成了”、“操作成功了” 2、必须明确操作对象、状态或数量

参考示例（NestJS响应）

1return {
2   status: 200,
3   message: `用户列表获取成功，共 ${list.length} 条`,
4   data: {
5       list,
6       page: 1,
7       size: 10,
8       total: list.length
9   }
10};
11

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

总结

1、message字段是接口的重要组成部分，承担操作反馈和提示作用。 2、优化目标：简洁、统一、明确、可扩展、可国际化。 3、规范化提示信息： 3.1、前端提示：短小清晰，用户友好 3.2、后端日志 / 文档：正式完整，便于排查 3.3、可模板化，适应多接口、多数据类型 3.4、可动态添加数量或操作引导

统一风格示例清单推荐

类型示例message
数据获取获取数据成功 / 数据已成功获取 / 列表数据获取成功，共N条
数据更新更新成功/数据更新操作已完成
数据删除删除成功/记录已成功删除
操作提示数据加载成功，可进行下一步操作
列表提示用户列表获取成功，共 N条

类型	示例message
数据获取	获取数据成功 / 数据已成功获取 / 列表数据获取成功，共N条
数据更新	更新成功/数据更新操作已完成
数据删除	删除成功/记录已成功删除
操作提示	数据加载成功，可进行下一步操作
列表提示	用户列表获取成功，共 N条

API响应message清单（可直接使用）

1、前端提示（简洁直观） 获取数据成功、数据加载完成、操作成功、保存成功、更新成功、删除成功

2、后端日志 / 正式风格（完整清晰） 数据已成功获取、数据获取操作完成、列表数据已返回、数据更新操作已完成、记录已成功删除、请求已成功处理

3、列表类提示（带上下文） 用户列表获取成功、设备列表获取成功、订单列表获取成功、日志记录获取成功、配置数据获取成功

4、分页 / 带数量提示 列表数据获取成功，共${list.length}条、用户列表加载完成，共${list.length}条、数据获取成功，当前页${page}/共${totalPages}页、数据加载成功，本页${list.length}条，总数${total}条、查询成功，符合条件的数据共${total}条

5、操作提示 / 引导型 数据加载成功，可进行下一步操作、操作成功，数据已更新、删除成功，记录已移除、保存成功，请刷新查看、数据获取成功，请查看列表

《服务端之NestJS接口响应message编写规范详解、写给前后端都舒服的接口、API提示信息标准化》是转载文章，点击查看原文。