请求入参json格式

### API 请求入参 JSON 格式规范

在构建和验证 API 请求时，确保 JSON 参数遵循标准格式至关重要。JSON 是一种轻量级的数据交换格式，因其结构简单、兼容性强而被广泛应用。

#### 基本结构
一个典型的 JSON 对象由键值对组成，其中键是字符串，值可以是多种类型之一（如字符串、数值、对象、数组等）。例如：

{
  "id": 1,
  "name": "张三",
  "email": "zhangsan@example.com"
}

此示例展示了最基础的 JSON 结构[^1]。

#### 复杂嵌套结构
对于更复杂的场景，JSON 支持多层嵌套的对象以及数组形式来表示列表或集合。比如：

{
  "user": {
    "id": 2,
    "profile": {
      "firstName": "李四",
      "lastName": "王五",
      "contactInfo": [
        {"type": "phone", "value": "+86-123456789"},
        {"type": "email", "value": "wangwu@example.org"}
      ]
    }
  },
  "preferences": ["reading", "traveling"]
}

上述例子不仅包含了简单的字段映射关系，还引入了子对象 `profile` 和数组类型的偏好设置 `preferences`。

#### 使用框架处理 JSON 输入
当利用像 Gin 或 FastAPI 这样的 Web 框架开发 RESTful APIs 时，通常会自动完成从 HTTP 请求到 Go/FastAPI 中相应数据类型的转换工作。开发者只需要定义好预期接收的数据模型即可。例如，在 Python 的 FastAPI 中可以通过 Pydantic 来声明期望接收到什么样的 JSON 数据，并自动生成相应的文档说明[^3]。

#### 验证工具推荐
为了方便测试和调试目的，建议使用 Postman 或 curl 工具发送带有特定 JSON 载荷的 POST 请求给目标服务端点。这有助于快速定位可能存在的问题并确认服务器能否正确解析传入的信息。

curl -X POST https://api.example.com/resource \
-H 'Content-Type: application/json' \
-d '{"key":"value"}'

通过这种方式可以直接观察返回的结果状态码及消息体内容，从而判断输入是否符合预期要求[^2]。