【API 设计之道】02 标准方法论：CRUD 的哲学与 HTTP 动词的精准语义

大家好，我是Tony Bai。

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

在上一讲中，我们成功地把那一堆乱七八糟的 /get_user、/create_order 路由，重构成了整洁的资源层级结构。

今天，我们深入到每一个具体的 Handler 内部，聊聊最基础、但也最容易出错的 CRUD（增删改查） 实现。

你可能会觉得：“CRUD 谁不会写？不就是查数据库然后返回 JSON 吗？”

但请看下面这个场景，这曾是我们团队在生产环境中遇到的真实故障：

前端同学开发了一个“修改用户资料”的功能。用户只想修改“昵称”，于是前端发了一个请求。 后端使用 Go 的 struct 绑定参数，直接更新了数据库。 结果：用户的“存款余额”突然变成了 0。

原因：前端传来的 JSON 只包含 nickname。后端 Go 结构体中的 Balance 字段是一个 int 类型，因为前端没传，JSON 库将其反序列化为 Go 的零值 0。后端代码没有区分“未传值”和“传了0”，直接把数据库覆盖了。

这个惨痛的教训告诉我们：写 API 容易，写出语义精准、行为安全的 API 很难。

今天这一讲，我们将对标业界最严格的 API 设计规范，深入探讨 HTTP 动词背后的哲学，并用 Go 语言解决那个著名的“零值更新”陷阱。

语义的精度：不仅仅是动词

在资源导向设计(RoD)中，每一个 HTTP 动词都有其精准的数学性质。理解这些性质，是设计健壮 API 的前提。