复杂查询接口：GET 还是 POST？

问题背景

在开发接口给前端使用时，接口是查询后端数据的接口，返回一个列表。但前端下发的接口里包含：

• 分页参数
• 过滤条件
• 一个 list 类型的对象（对象有两个属性）

问题：如果接口定义成 GET，参数不好传；如果定义为 POST，这又是个获取数据的接口。最佳实践是什么？

推荐方案：使用 POST 进行复杂查询

官方和业界实践

POST 用于复杂查询是被广泛接受的实践。

主流 API 都这样做：

• Elasticsearch: 使用 POST /_search 进行查询
• GraphQL: 所有查询都使用 POST
• GitHub API: 复杂搜索使用 POST
• Microsoft Graph API: 复杂查询使用 POST

方案对比

方案1：GET 请求（不推荐）

GET /api/timepoints?page=1&size=10&datasetId=yyy

问题：

• URL 长度限制（通常 2048 字符）
• 复杂对象（列表）难以表达
• 参数重复，难以维护
• 可读性差

方案2：POST 请求用于查询（推荐）

POST /api/timepoints/query
Content-Type: application/json

{
  "page": 1,
  "size": 10,
  "filters": {
    "isAdmin": true,
    "dateRange": "2024-01-01"
  },
  "timePointInfos": [
    {
      "dataSetId": "dataset1",
      "timeStamp": 1234567890
    },
    {
      "dataSetId": "dataset2",
      "timeStamp": 9876543210
    }
  ]
}

优点：

• 无长度限制
• 支持复杂数据结构
• 可读性好
• 易于维护和扩展

方案3：混合方案

# 简单查询用 GET
GET /api/timepoints?page=1&size=10

# 复杂查询用 POST
POST /api/timepoints/search

最佳实践建议

HTTP 方法选择规则

权威参考

1. Microsoft REST API Guidelines

"Use POST for complex queries with request bodies"

2. Google API Design Guide

"Custom methods can use any HTTP verb, including POST for queries"

3. Roy Fielding (REST 创始人) 的观点

REST 并不严格限制 POST 只能用于创建，关键是语义清晰和一致性。

总结

应使用 POST 的原因：

1. 技术上：避免 URL 长度限制和编码问题
2. 可维护性：清晰的请求体结构
3. 扩展性：未来易于添加新的查询条件
4. 业界实践：主流 API 的通用做法
5. 语义清晰：通过端点名称（如 /query 或 /search）明确表达意图

这不违反 REST 原则，反而是务实和专业的选择。关键是保持 API 设计的一致性和文档化。