【API 设计之道】01 资源导向设计 (ROD)：告别 RPC 风格的“动词地狱”

最新推荐文章于 2025-12-08 19:37:52 发布

原创最新推荐文章于 2025-12-08 19:37:52 发布 · 191 阅读

2 ·

CC 4.0 BY-SA版权

文章标签：

#rpc #网络协议 #网络

大家好，我是Tony Bai。

欢迎来到我们的专栏《API 设计之道：从设计模式到 Gin 工程化实现》的第一讲。

在开始讲解之前，我想先带你看一张“恐怖”的路由表。这是我曾在某次代码审查中看到的一个真实项目的 router.go 文件片段（为了保护隐私，我做了一些脱敏处理）：

// 典型的 "面条式" 路由配置
r.POST("/getUser", GetUser)
r.POST("/createUser", CreateUser)
r.POST("/update_user_status", UpdateUserStatus)
r.POST("/deleteUser", DeleteUser)
r.POST("/user/getOrders", GetUserOrders)
r.POST("/api/query_product_list", QueryProductList)
r.POST("/cancel_order", CancelOrder)

看着这段代码，你的第一感觉是什么？

如果是“这没问题啊，挺清晰的”，那你可能已经陷入了 RPC（远程过程调用）风格 的思维陷阱。

这段代码的问题在于：它把 HTTP 仅仅当成了一个传输通道，而不是一种应用架构。 这种设计风格被称为“动词地狱”（Verb Hell）。随着业务增长，你的 API 会迅速膨胀成成百上千个无规律的 endpoint，就像一碗纠缠不清的面条，不仅难以维护，更难以在团队间形成统一的规范。

今天这一讲，我们就来谈谈现代云原生 API 设计的第一原则：资源导向设计（Resource-oriented Design，简称 ROD），并看看如何在 Gin 项目中通过工程化手段落地这一原则。

为什么我们会陷入“动词地狱”？

这种 /get_user 风格的接口之所以流行，是因为它非常符合我们写后端代码的直觉。

在 Go 语言（以及大多数编程语言）中，我们的业务逻辑是由函数（Functions）驱动的。我们定义一个函数名（动词），传入参数，返回结果。当我们把这个逻辑暴露给网络时，直觉告诉我们：URL 就是函数名，HTTP Body 就是参数。

这就是典型的 RPC 思维。

然而，RESTful 架构乃至现代云原生 API 的核心哲学是：网络上的交互对象应该是“事物”（Nouns），而非“动作”（Verbs）。

如果不转变这个思维，你会遇到以下痛点：

命名爆炸：getUser, queryUser, fetchUser, findUser... 每个开发者都有自己的习惯，团队协作成本极高。
HTTP 语义丢失：全部使用 POST一把梭，HTTP 协议中精心设计的 GET（缓存）、PUT（幂等）、DELETE（安全）等语义完全失效。
层级关系混乱：/user/getOrders 和 /order/listByUser 到底该用哪个？缺乏统一的层级结构。