【API 设计之道】04 字段掩码模式：让前端决定后端返回什么

大家好，我是Tony Bai。

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

在上一讲中，我们解决了那些无法被 CRUD 囊括的复杂业务逻辑。今天，我们将目光转向数据传输的效率问题。

在日常开发中，你是否遇到过这样的“拉扯”场景：

场景 A：前端开发了一款 App，在“用户列表页”只需要展示用户的 头像 和 昵称。

后端：直接复用了 GetUser 接口，返回了包含 身份证号、家庭住址、注册时间、最后登录IP 等 50 多个字段的超级大 JSON。

前端：抱怨说：“我就要两个字段，你给我几 KB 的数据，用户在地铁上信号不好，加载太慢了！能不能给我单写一个 GetUserSimple 接口？”

后端：心里苦——“为了这点破事又要写个新接口？如果不写，是不是还得定一个 UserSimpleDTO？”

这就陷入了 API 设计中经典的 过度获取（Over-fetching） 困境。

如果我们为每一种前端视图都定制一个后端接口，那就会陷入“BFF（Backend for Frontend）地狱”，后端变成了前端的“切图仔”；如果我们什么都不管，只返回全量数据，那就是对带宽和客户端内存的犯罪。

GraphQL 的出现很大程度上是为了解决这个问题，但为了这点需求引入整套 GraphQL 基础设施，成本又未免太高。

有没有一种办法，能在保持 RESTful 架构简洁性的同时，实现“按需索取”呢？

答案是肯定的。这就是今天我们要讲的API模式：字段掩码（Field Mask），也被称为“愿望清单（Wish List）”模式。

什么是字段掩码 (Field Mask)？

核心思想非常简单：客户端在请求中通过参数告诉服务端，“我只想要这些字段”，服务端据此对响应体进行裁剪。

架构模式视角

在架构设计领域，这种模式被称为 Response Shaping（响应塑形）。它打破了“服务端定义契约，客户端被动接受”的传统模式，赋予了客户端（消费者）定义数据形态的权力。