RESTful API应返回编码还是转译描述？寻求最佳实践指导

这是个非常常见的API设计问题，我结合行业里的实际做法帮你拆解下三个方案的优劣，以及适合你的场景的最佳实践：

选项1：返回编码+提供独立查找列表API #

这种方案的核心是分离数据主体和字典数据，优势很明确：

• 大幅降低单次API的响应体积，尤其是返回大量列表数据时，不会因为重复的描述信息浪费带宽
• 查找列表通常是低频变更的静态数据，客户端可以缓存起来，不用每次请求都重新获取
• 服务端逻辑更简洁，不用在查询主体数据时做复杂的关联拼接

但它的痛点也很突出：

• 客户端需要额外维护缓存逻辑，还要处理字典更新的同步问题（比如某个编码的描述变更后，客户端怎么及时感知）
• 如果用户首次访问就需要展示完整信息，得先请求主体数据再请求字典，增加了请求次数，可能拖慢页面加载速度

适合场景：字典数据极少变更，且客户端需要频繁加载大量主体数据（比如分页展示1000条人员列表），或者多个页面需要复用同一套字典的情况。

选项2：返回完全填充的对象 #

这是当前面向终端用户的API的主流设计思路：

• 客户端逻辑极简，拿到数据直接就能渲染，不用做额外的关联查找转换
• 返回的数据语义清晰，对终端用户（或前端开发人员）更友好，不用再去对应编码含义
• 避免了选项1中多次请求的问题，单次请求就能拿到所有需要展示的信息

缺点也存在：

• 当返回大量列表数据时，重复的字典信息会增加响应体积（比如1000条人员数据都带完整的国家对象）
• 服务端需要在查询时做关联查询，增加了数据库查询的复杂度，关联表较多时可能影响性能

不过这些问题都有优化空间：比如服务端支持字段按需返回（让客户端通过参数指定需要哪些关联字段），或者对高频关联数据做缓存，减少数据库关联的压力。

适合场景：终端用户需要直接展示完整信息，且单次请求的数据量不是特别大的情况；或者客户端是移动端，带宽有限但希望减少请求次数的场景。

选项3：自引用链接（HATEOAS风格） #

这种RESTful风格的设计更适合探索式访问的API，但正如你所说，在批量请求场景下完全不可行——1000条数据发起1000次请求不仅会压垮服务器，也会让客户端性能极差。

它的合理适用场景通常是单条数据的详情页：比如用户查看某个人的详情时，可能需要进一步探索关联资源（比如查看该人员所属国家的详细信息），这时在返回的person对象里加个countryOfOriginUrl字段，用户点击时再去请求详情，是比较合适的。但批量列表场景下绝对不推荐。

综合建议 #

结合你的场景（多数用户会请求大量人员数据并以列表展示），我推荐两种实用的组合方案：

1. 默认返回编码+可选填充关联数据：

   • 基础API只返回编码（比如gender:1, countryOfOrigin:"US"），同时提供一个可选参数（比如expand=gender,countryOfOrigin），当客户端需要完整信息时，带上这个参数，服务端就返回填充后的对象。
   • 这样兼顾了性能和灵活性：批量列表请求用基础模式减少体积，单条详情请求用expand拿到完整信息。

2. 缓存字典数据+客户端预加载：

   • 如果字典数据变更极少，客户端可以在启动时预加载所有字典列表并缓存，之后请求主体数据时直接在本地做映射。
   • 服务端可以提供一个字典更新的通知接口（或者让客户端定期轮询），当字典有变更时再更新缓存。

这两种方案都是行业里的常用最佳实践，能很好平衡性能和开发成本。

内容的提问来源于stack exchange，提问作者RHarris