Postman的form-data不支持字段注释，但可通过Key嵌入提示（如avatar__png_jpg_only）、Description区写Markdown说明或集合级文档统一维护；禁用Headers/Params藏备注以防风险。
Postman 里 form-data 字段没法加注释，但可以绕过
Postman 的 form-data 编辑界面本身不支持给每个字段加备注或注释——界面上只有 Key、Value、类型下拉框（Text / File）三列，没有“说明”“备注”“Comment”栏。这不是你操作错了，是它真没这个功能。
但实际协作中又常需要标注：比如 avatar 字段只接受 PNG/JPG、metadata 要求是 JSON 字符串、temp_id 是前端生成的临时标识……这些信息不写下来，下次重进请求就容易填错。
可行做法是：
- 在
Key名称里嵌入简短提示，例如：avatar__png_jpg_only、metadata__json_string—— 不影响后端接收（只要后端按约定名取值），又能一眼识别约束 - 把完整说明写在 Postman 请求的 Description 区域（点击右上角「⋯」→ Edit → Description 标签页），用 Markdown 列出各字段用途、格式、是否必填
- 如果团队用 Postman 工作区，可配合文档型集合（Documentation tab），把表单字段说明统一维护在集合级文档里，避免重复粘贴
为什么不能在 headers 或 params 里藏备注？
有人试过把字段说明塞进 Headers（比如加个 X-Note: avatar must be ）或 <code>Params（比如加个 debug_note=avatar_format_check），这看似简单，但有明确风险：
Postman 12.27.7 Windows x64 官方安装包，适用于 API 设计、调试、测试与协作。该系列包含 Enterprise 云端性能测试静态 IP 出口能力，以及接口规范标签管理改进，适合受限网络测试与规范资源组织场景。
- 后端通常会校验
Content-Type: multipart/form-data的 boundary 和字段结构，额外 header 或 query 参数不会被解析进 form-data 正文，纯属冗余；某些严格网关甚至会拦截非白名单 header - 如果误把说明当真实参数传到后端（比如
Params里的debug_note），而接口又没做参数过滤，可能引发日志污染、SQL 注入（若拼接进日志语句）、或触发风控规则 -
Params会拼到 URL 上，导致 URL 过长、被代理截断，或暴露敏感说明信息（如 “test_env_only”）
测试时怎么快速确认字段是否生效？
光写备注没用，得验证字段真被发出去了。最直接的方式是打开 Postman Console（View → Show Postman Console），发一次请求，看原始请求体里有没有你填的 Key 和对应 Value：
- 文本字段会显示为
Content-Disposition: form-data; name="avatar"+ 后续内容 - 文件字段除了
name，还会显示filename="xxx.png"和Content-Type: image/png - 如果某个字段完全没出现在 console 的 raw request 里，大概率是类型选错了（比如该选
File却用了Text），或者 Key 名拼写和后端要求不一致
注意：console 里看不到你写在 Description 或 Key 名里的备注文字，它只反映实际发出的 HTTP 数据。
多人协作时最容易忽略的一点
Postman 的 form-data 字段顺序不保证传输顺序，也不影响解析——后端靠 name（即 Key）匹配，不是靠位置。但人眼阅读时习惯从上往下看，所以建议把必填字段放上面、文件字段放中间、调试用的临时字段（如 _debug_timestamp）放最底下。这种排列不是技术要求，而是降低队友误操作概率的软性规范。
