Postman中添加参数注释的推荐方式是使用Examples功能：在请求页右侧点击Add example，填写Example name和实际参数值，并在Description栏写明用途、字段含义等说明，该备注仅存于Postman内部、不影响请求发送。
Postman 本身不支持在请求参数（Query、Form Data、URL 参数等）里直接写注释，一写就报错或被当成真实参数发出去。想给参数加说明，必须绕开“把注释塞进请求体”这个误区，用真正生效的、服务端无感的方式。
用 Examples 给整个请求加用途备注
这是最稳定、最推荐的做法：备注只存在 Postman 内部，不影响任何请求发送。
- 在请求编辑页右侧点击 Add example 按钮，创建一个示例
- 填写
Example name（比如正常登录-手机号密码或异常场景-空密码） - 在
Request body或Params区域填入对应的实际参数值（不带注释） - 在
Description栏里写清楚用途、字段含义、前置条件，比如：测试用户未绑定手机号时的注册流程，email 必须为新邮箱，invite_code 可为空 - 保存后，点右上角
Send旁的下拉箭头，就能快速切换不同场景，描述也会跟着显示
JSON body 里加伪注释字段（仅限开发自测）
如果必须在 raw JSON 里“看着像有注释”，只能靠约定俗成的冗余字段，但要注意：服务端必须忽略这些字段，否则会报错。
Postman 12.27.7
下载
Postman 12.27.7 Windows x64 官方安装包，适用于 API 设计、调试、测试与协作。该系列包含 Enterprise 云端性能测试静态 IP 出口能力，以及接口规范标签管理改进，适合受限网络测试与规范资源组织场景。
- 字段名统一用
_xxx.comment格式，例如："_userId.comment": "必填，对应数据库 user.id" - 确保这些字段不会被后端解析——有些框架（如 Spring Boot）默认会把未知字段反序列化失败，得配
@JsonIgnoreProperties(ignoreUnknown = true) - 不要用
//或/* */，JSON 标准不认，Postman 发送时会直接报SyntaxError: Unexpected token - 示例有效结构：
{
"_id.comment": "主键，不可重复",
"id": 128,
"_page.comment": "当前页码，从 1 开始",
"page": 1,
"pageSize": 15
}Pre-request Script 动态注入说明（适合复杂调试链路）
当备注需要和变量、环境联动（比如“当前使用的是 staging 环境的 mock token”），就得靠脚本动态写入日志，而不是改请求内容。
- 在 Pre-request Script 中加一行：
console.log("[DEBUG] 使用 env:", pm.environment.name, "token 来源:", pm.variables.get("auth_token_source")); - 打开 Postman 控制台（
View → Show Postman Console），每次请求前都能看到上下文说明 - 这种方式不污染请求，也不依赖服务端配合，但缺点是备注不出现在 UI 上，只对调试者可见
- 别试图用脚本往
pm.request.url.query或pm.request.body里塞中文说明字段——那等于发脏数据
真正容易被忽略的一点：所有“看起来像备注”的做法，只要改动了请求原始结构（哪怕只是多一个 _comment 字段），都得和服务端同学对齐是否允许。最省心的方案永远是 Examples + Description，它不走网络、不触发校验、不增加联调成本。
