HTTP 请求方法详解

什么是 HTTP 方法？

HTTP 方法（也叫 HTTP 动词）是客户端告诉服务器**「我想做什么」**的方式。

客户端：我想 查 用户信息     → GET /users/123
客户端：我想 创建 新用户     → POST /users
客户端：我想 修改 用户信息   → PUT /users/123
客户端：我想 删除 用户       → DELETE /users/123

核心方法速查

GET — 获取数据

GET /users/123

• 含义：请求获取指定资源的数据
• 类比：去图书馆借书——你只是想看书，不会改变书架上的书
• 安全：不会修改服务器上的数据
• 幂等：多次请求结果相同
• 参数：通常放在 URL 查询参数中（?name=张三&age=25）

适用场景：查询、搜索、获取详情

POST — 创建数据

POST /users
Body: {"name": "张三", "age": 25}

• 含义：在服务器上创建一条新数据
• 类比：去邮局寄信——你新增了一封信，改变了邮局的数据
• 安全：会修改服务器上的数据
• 幂等：多次请求会创建多条数据（不幂等）
• 参数：放在请求体（Body）中

适用场景：注册用户、提交表单、发送消息

PUT — 完整替换数据

PUT /users/123
Body: {"name": "李四", "age": 30}

• 含义：用新数据完整替换指定资源
• 类比：去柜台改签——用一张新票替换原有的票
• 安全：会修改服务器上的数据
• 幂等：多次请求结果相同（都是替换为同样的数据）
• 参数：放在请求体中，通常需要完整的资源数据

适用场景：更新整个用户信息、替换配置文件

PATCH — 部分更新数据

PATCH /users/123
Body: {"age": 30}

• 含义：部分修改指定资源的某些字段
• 类比：去柜台改签——只改日期，不改其他信息
• 安全：会修改服务器上的数据
• 幂等：多次请求结果相同
• 参数：放在请求体中，只需要要修改的字段

适用场景：修改用户昵称、更新部分配置

DELETE — 删除数据

DELETE /users/123

• 含义：删除指定资源
• 类比：去银行销户——彻底删掉账户
• 安全：会修改服务器上的数据（删除）
• 幂等：多次请求结果相同（第一次删了，后面几次都是「已经删了」）
• 参数：通常在 URL 中

适用场景：删除用户、删除文件、取消订阅

语义对比表

安全 vs. 幂等

这两个概念经常被混淆，需要理清：

安全（Safe）

安全 = 这个方法不会修改服务器上的数据。

GET /users/123     → 安全（只读）
POST /users        → 不安全（会创建数据）

幂等（Idempotent）

幂等 = 执行一次和执行多次的效果一样。

GET /users/123     → 幂等（每次返回同样的数据）
POST /users        → 不幂等（每次创建一条新数据）
PUT /users/123     → 幂等（每次都是替换为同样的数据）
DELETE /users/123  → 幂等（第一次删了，后面几次都是「已删除」）

AI API 为什么只用 POST？

你可能会问：「AI API 明明只是「提问」，为什么用 POST 而不是 GET？」

原因：

1. 请求体可能很大：对话历史、工具定义、系统提示词都可能很长，放在 URL 里不合适
2. GET 有长度限制：URL 长度有限制（通常 2KB-8KB），复杂的 AI 请求可能超限
3. 语义上更像「操作」：AI 生成回复是一个「计算任务」，更像 POST 的语义
4. 安全考虑：请求体放在 Body 中，不会出现在服务器日志里（保护敏感内容）

请求体 vs. URL 参数

┌─────────────────────────────────────────────────────┐
│ GET /search?q=你好&limit=10                          │
│                                                     │
│ ↑ URL 参数：适合简单、短小的查询                    │
│ ↑ 有长度限制，不适合复杂数据                         │
└─────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────┐
│ POST /v1/messages                                   │
│ Body: {                                             │
│   "model": "claude-sonnet-4-5",                     │
│   "messages": [...],                                │
│   "tools": [...]                                    │
│ }                                                   │
│                                                     │
│ ↑ 请求体：适合复杂、大型的数据                       │
│ ↑ 无长度限制（理论上），支持任意结构                 │
└─────────────────────────────────────────────────────┘

常见的 RESTful 设计误区

在 API 文档中的标识

当你看到 API 文档时，通常会这样标识：

POST /v1/messages
GET /v1/models
DELETE /v1/files/{file_id}

解析：

• 第一个词是 HTTP 方法
• 后面的路径是端点（Endpoint）
• {file_id} 是路径参数（需要在 URL 中替换为实际值）

实战示例

curl 命令速查

# GET 请求
curl https://api.example.com/users/123

# POST 请求（带 JSON 数据）
curl -X POST https://api.example.com/users \
  -H "Content-Type: application/json" \
  -d '{"name": "张三", "age": 25}'

# PUT 请求（完整替换）
curl -X PUT https://api.example.com/users/123 \
  -H "Content-Type: application/json" \
  -d '{"name": "李四", "age": 30}'

# PATCH 请求（部分更新）
curl -X PATCH https://api.example.com/users/123 \
  -H "Content-Type: application/json" \
  -d '{"age": 30}'

# DELETE 请求
curl -X DELETE https://api.example.com/users/123

常见问题

总结

返回 REST API 基础概念 了解 API 的请求/响应结构 返回 JSON 数据结构基础 了解请求体中的 JSON 数据如何组织