GET / POST 请求示例：写成可复现的调试记录
一句话回答
有调试价值的请求示例，必须写明方法、完整 URL、参数位置与编码、关键请求头，以及可观察的预期响应；缺少这些只能照抄，无法用于排查。GET 与 POST 的示例在参数位置、编码和重复执行风险上不同；文中示例均为占位演示，未实际执行。
一个请求示例能不能用于调试，关键看它是否包含重放后仍能解释结果的信息：方法、完整 URL、参数位置与编码、必要请求头、以及预期可观察到的响应。缺少任何一项，照抄之后就只能靠猜。下面先分别看 GET 与 POST 示例应写成什么样，再给出按顺序取证的步骤。
边界先说明：本文不引用具体服务端点的参数表，因为没有提供可核验的官方文档材料；API.PLUS 各端点的路径、鉴权头名称与错误码含义待核实，请以其官方文档为准。文中示例使用 example.com 与 YOUR_KEY 占位，均未执行，不作为实际结果。
GET 示例：参数在 URL 里，重点看编码和可重复性#
GET 把参数放在 query string 中，示例必须写出实际取值，并标明哪些是占位：
curl -sS -i 'https://example.com/v1/search?q=widget'
以上为未执行的演示示例。调试时有三处容易出问题：
- 编码：空格、中文、
&、+需要百分号编码，否则参数会被切分或误解。 - 密钥位置：不要把密钥写进 URL。按方法语义，GET 通常被视为安全且幂等的（这是推断，具体仍取决于服务实现），但它常被完整记入访问日志与浏览器历史。
- 路径占位符：
/v1/items/{id}这类示例要写成实际值或明确的占位，混用会让人误以为路径写错了。
POST 示例：body 与 Content-Type 必须一起写#
curl -sS -i -X POST 'https://example.com/v1/items' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer YOUR_KEY' \
--data '{"name":"demo","size":3}'
以上为未执行的演示示例。POST 的失效点集中在请求体：
- Content-Type 与实际编码不一致（例如声明为 JSON，实际发的是表单串），服务端可能解析为空对象，也可能直接报错。
- 表单与 JSON 混用：两种 body 结构不能拼在一起。
- 重复提交：POST 没有 GET 那样的天然可重复性，网络重试可能造成重复创建。是否需要幂等键，取决于具体服务的设计，本次材料未提供依据，待核实。
调试时按顺序采集证据#
- 先确认请求真的发出去了：核对方法、路径、请求头，特别是代理或 SDK 是否改写了其中任何一项。
- 先看状态码，再看响应头：Content-Type、缓存相关头、请求 ID 往往比 body 更早说明问题出在哪一层。
- 然后看 body 里的错误结构：错误码与错误字段的含义需要对照官方文档，不要自行推断。
- 做减法：删掉可选参数和多余请求头，保留最小可复现集，再逐个加回。
- 最后才看环境差异：超时、代理、TLS、重定向这类因素影响面广，放在最后排查能避免过早怀疑。
GET 与 POST 示例要素对照#
| 项目 | GET 示例要写清的 | POST 示例要写清的 |
|---|---|---|
| 参数位置 | query string，完整取值 | body，结构（JSON/表单） |
| 必须体现的请求头 | 鉴权头、Accept | Content-Type 与鉴权头 |
| 重复执行风险 | 通常较低（推断） | 可能重复创建，需按服务约定处理 |
| 高发失效点 | 编码、URL 长度 | 编码与声明不一致、必填字段缺失 |
把示例写成一份可复现的记录，好处不只是自己回头能重跑：同事复现时能直接判断问题出在参数、请求头还是环境上。至于某个端点的必填字段、限流规则与错误码定义，在没有官方文档材料的情况下不应写入示例；标为待核实，比写一个看似确定但无出处的值更安全。
