webapi开发接口设计要不要区分"查询接口"和"动作接口"

在日常开发中，你可能遇到过这样的困惑：

为什么有的接口用 GET 请求，有的用 POST？
查询数据用 GET 没问题，那新增、修改、删除要用什么方法？
PUT、PATCH、DELETE 这些 HTTP 方法到底有什么区别？
为什么要搞这么复杂，直接用 POST 不行吗？

今天我们就来深入聊聊这个话题—— 接口设计，到底要不要区分"查询接口"和"动作接口"？

PART 01

查询接口

什么是查询接口和动作接口?

在正式讨论之前，我们先明确一下概念。

查询接口是指那些只获取数据、不改变服务端状态的接口。

典型的查询接口：

获取用户信息

搜索商品列表

查看订单详情

获取配置信息

这些接口的共同特点是：调用多次和调用一次的效果是一样的，不会对数据产生任何副作用。

PART 02

动作接口

动作接口则是指那些会对服务端状态产生改变的接口。

典型的动作接口：

创建新订单

修改用户头像

删除某条记录

发起支付

发送消息

这些接口的共同特点是：调用一次和调用多次的结果可能不同，会产生副作用。

PART 03

为什么要区分

1.语义清晰，一眼就能看懂

当我们看到 /api/users 是 GET 请求时，我们知道这是在查看用户列表。
当我们看到 /api/users 是 POST 请求时，我们知道这是在创建新用户。
HTTP 方法本身就是一种语义表达，让调用者不需要去看文档就知道这个接口要做什么。

GET    /api/users      # 获取用户列表
POST   /api/users      # 创建新用户
GET    /api/users/123  # 获取指定用户
PUT    /api/users/123  # 更新指定用户（完整更新）
DELETE /api/users/123  # 删除指定用户

这种设计让接口自描述，降低了沟通成本。

2. 缓存优化

浏览器和 CDN 会对 GET 请求进行缓存，但不会缓存 POST 请求。

对于查询接口来说，缓存可以大幅提升性能：

# 第一次请求
GET /api/products?category=books
→ 返回 200 OK + 数据 + Cache-Control: max-age=3600

# 缓存有效期内再次请求
GET /api/products?category=books
→ 直接从缓存返回，不需要到达服务器

而动作接口不应该被缓存，因为每次调用都可能产生不同的结果。

3. 安全性

GET 请求的参数暴露在 URL 中，适合不敏感的查询操作
POST 请求的参数在请求体中，适合敏感的操作（如登录、支付）
某些代理服务器默认不缓存 POST 请求，更安全
GET 请求可能会被浏览器history记录、server日志记录，而 POST 相对更隐蔽

4. 幂等性保证

幂等性是指：同一个请求执行一次和执行多次的结果是一样的。

HTTP 方法	幂等性	说明
`GET`	幂等	查询多次结果相同
`POST`	非幂等	创建多次会产生多条记录
`PUT`	幂等	更新多次结果相同
`DELETE`	幂等	删除多次结果相同
`PATCH`	非幂等	部分更新可能不同

理解幂等性对于重试机制非常重要。如果一个接口调用失败，客户端可能会自动重试：

GET 重试：安全，多次查询结果一样

PUT 重试：安全，更新一次和更新多次结果一样

POST 重试：危险！可能创建多条重复记录

5.符合 RESTful 规范

REST（Representational State Transfer）是一种架构风格，它强调：

使用 HTTP 方法表达操作类型

资源 URI 要名词而非动词

无状态交互

虽然 RESTful 不是银弹，但它是一种被广泛接受和理解的约定。遵循这个约定可以让你的 API 更容易被其他开发者接受。

PART 04

不区分会怎样

如果所有接口都使用 POST 会怎么样？

# 查询用户 - 用 POST
POST/api/getUser
POST/api/queryUserList

# 创建用户 - 用 POST
POST/api/createUser

# 更新用户 - 用 POST
POST/api/updateUser

# 删除用户 - 用 POST
POST/api/deleteUser

这种设计的问题：

语义混乱
调用方无法从请求本身判断这个接口是要查询还是修改，必须依赖接口命名或者文档。
无法利用 HTTP 语义
缓存、重试、安全性等 HTTP 特性都无法发挥作用。
可发现性差
好的 RESTful API 可以通过 HATEOAS 让客户端发现相关操作，但如果都用，这个优势就荡然无存了。
违反直觉

开发者需要记住每个接口的具体名称，而不是用惯用的方式与 API 交互。

PART 05

实际项目中如何设计

原则一：查询用 GET，动作用 POST

这是一个最基本的原则：

// 查询接口 - GET
@GetMapping("/api/users")
public List＜User＞ getUsers() { ... }

@GetMapping("/api/users/{id}")
public User getUser(@PathVariable Long id) { ... }

// 动作接口 - POST
@PostMapping("/api/users")
public User createUser(@RequestBody User user) { ... }

// 但如果动作需要幂等性，用 PUT 更合适
@PutMapping("/api/users/{id}")
public User updateUser(@PathVariable Long id, @RequestBody User user) { ... }

@DeleteMapping("/api/users/{id}")
public void deleteUser(@PathVariable Long id) { ... }

原则二：复杂查询可以用 POST

有时候查询条件非常复杂，URL 参数不够用：

# GET 查询 - URL 长度有限制
GET/api/users?age=20&city=beijing&status=active&sort=name&order=asc

# POST 查询 - 请求体可以传递复杂结构
POST/api/users/search
{
"filters":[
    {"field":"age","operator":"＞=","value":20},
    {"field":"city","equals":"beijing"},
    {"field":"status","equals":"active"}
],
"sort":{"field":"name","order":"asc"},
"page":1,
"size":20
}

这种场景下，用 POST 做查询是合理的，但要注意命名规范：

@PostMapping("/api/users/search")
public List＜User＞ searchUsers(@RequestBody UserQuery query) { ... }

原则三：批量操作要谨慎

批量操作可能涉及多个资源的变更，需要考虑幂等性：

// 批量删除 - 用 DELETE，幂等
@DeleteMapping("/api/users/batch")
public void deleteUsers(@RequestBody List＜Long＞ ids) { ... }

// 批量更新 - 用 PUT，幂等
@PutMapping("/api/users/batch")
public List＜User＞ updateUsers(@RequestBody List＜User＞ users) { ... }

原则四：动作接口用动词还是名词

这是一个常见的困惑：

# 用动词（传统方式）
POST /api/createOrder
POST /api/deleteUser

# 用名词 + HTTP 方法（RESTful）
POST   /api/orders      # 创建订单
DELETE /api/users/123   # 删除用户

推荐使用名词 + HTTP 方法的方式，因为它更符合 RESTful 规范。

但有些动作确实很难用名词表达：

# 发送验证码 - 很难找到合适的名词
POST /api/sendSmsCode

# 发起支付 - 也是动作
POST /api/initiatePayment

# 这种情况用动词是可以接受的

原则五：版本控制

随着 API 的演进，可能需要对接口进行版本控制：

# URL 版本控制
GET /api/v1/users
GET /api/v2/users

# Header 版本控制
GET /api/users
Accept: application/vnd.myapp.v2+json

PART 06

常见误区

误区一：GET 请求不能有请求体

技术上，HTTP 规范并没有禁止 GET 请求有请求体。但实际上：

大多数 HTTP 客户端和服务器对 GET 请求体的支持不一致

代理服务器、负载均衡器可能会忽略 GET 请求体

可读性差，开发者会感到困惑

建议：查询条件复杂时用 POST 查询，而不是给 GET 加请求体。

误区二：所有修改都用 POST

POST 是最"万能"的方法，但这不意味着它应该被滥用：

更新用 PUT（完整更新）或 PATCH（部分更新）

删除用 DELETE

这些方法有明确的语义，不应该全部用 POST 代替

误区三：必须严格遵守 RESTful

RESTful 是一种风格指南，不是强制规范。

如果你的项目：

是一个面向公众的 API，需要被大量第三方调用 → 尽量遵循 RESTful

是一个内部系统，调用方可控 → 可以适当简化

关键是团队统一、文档清晰，而不是教条地遵循某个规范。

PART 07

总结

回到最初的问题：接口设计要不要区分"查询接口"和"动作接口"？

答案：建议区分。

区分查询接口和动作接口的好处：

语义清晰 - 一眼就能看懂接口的用途

缓存优化 - GET 请求可以被缓存，提升性能

安全性 - 敏感操作用 POST 更安全

幂等性 - 明确接口的幂等特性，便于重试

符合规范 - RESTful 是被广泛接受的约定

当然，也不必教条地遵循规则。关键是团队统一、约定明确、文档清晰。

记住：好的 API 设计是为了让人更容易理解和使用，而不是为了彰显技术。

阅读原文：原文链接