这是API设计里很常见的场景，我结合实际项目经验和行业通用做法来分析下这几个方案：

方案1：单一端点，按权限返回不同字段 #

这种方案的核心是同一个资源端点，根据请求者的授权状态返回不同的资源表示，其实非常贴合REST架构中“资源表示”的设计思想——同一个资源对不同的访问者可以展示不同的内容。

优点： #

• 语义清晰：客户端只需要记住GET /users/{uuid}这一个端点，不用区分公开/私有路径，降低认知成本
• 维护简单：不需要额外维护两套端点逻辑，权限判断集中在同一个接口里处理
• 行业通用：很多知名API都采用这种模式，开发者接受度高

缺点： #

• 客户端需要处理动态返回结构：未授权和授权请求的返回字段不一致，前端要做好兼容（比如判断email字段是否存在）
• 文档需要明确说明不同权限下的返回差异，否则容易让开发者踩坑

方案2：拆分公开/私有端点 #

把公开资源和私有资源放在不同的端点下，比如/user-profiles/{uuid}（公开）和/users/{uuid}（私有），嵌套资源同理拆分。

优点： #

• 职责明确：从端点路径就能直接判断资源的权限要求，不会混淆
• 客户端无需处理动态结构：每个端点的返回结构是固定的，前端逻辑更简单

缺点： #

• 端点冗余：同一类资源需要维护两套端点，增加了开发和维护成本
• 资源定位不统一：比如用户的文章，/articles/{id}和/users/{uuid}/articles/{id}本质是同一个资源，但拆分后容易让开发者疑惑该调用哪个
• 扩展性差：如果后续新增更多权限等级，可能需要继续拆分更多端点，导致路径体系越来越复杂

其他可选方案 #

• 查询参数控制字段范围：比如GET /users/{uuid}?scope=public，但这种方式不如基于身份的权限控制安全，因为客户端可以随意修改参数，而且权限逻辑应该由服务端判断，不是客户端主动选择
• HATEOAS扩展：在公开端点的返回中加入指向私有资源的链接（比如"private_profile": "/users/{uuid}"），当用户授权后可以通过该链接获取完整信息。这种方式更符合REST的成熟架构，但会增加系统复杂度，适合大型复杂的API系统

最终推荐 #

如果你的系统场景相对简单，优先选择方案1——它既符合REST设计原则，又能兼顾开发和维护效率。只要在文档里清晰标注不同权限下的返回差异，客户端做好字段存在性判断，就能很好地解决问题。

如果你的系统有非常严格的权限边界要求，或者公开/私有资源的差异极大（比如字段完全不重叠），方案2也是可行的，但一定要保持端点命名的一致性，避免混乱。

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