REST API输入输出Schema能否不同？更新请求格式选型咨询

核心结论 #

推荐沿用POST创建时的userId字段格式来实现PUT更新请求，示例如下：

PUT /members/200

{
   "userId": 50,
   "role": "admin"
}

业界共识分析 #

• 保持接口风格一致性：创建操作（POST）用userId指定关联用户，更新操作（PUT）沿用相同字段，能降低客户端开发者的学习成本，避免因字段格式切换产生混淆。
• 输入简洁性优先：更新关联用户仅需用户的唯一标识，无需传递完整的user对象，减少请求数据冗余，同时降低客户端的构造成本。
• 避免语义歧义：如果使用user: {id: 50}的格式，客户端可能误以为可以同时更新user的其他属性（如firstName），但你的业务场景仅需修改关联的用户ID，userId字段能更清晰地表达操作意图，减少不必要的误解和后端校验逻辑。

输入输出Schema的差异合理性 #

REST API的输入和输出Schema完全允许不同，这是业界的常见设计方式，原因在于两者的设计目标不同：

• 输入Schema：核心是收集完成业务操作所需的最小必要数据，比如创建/更新ProjectMember时，只需要userId和role就能完成关联和权限设置，不需要返回的资源ID或用户详细信息。
• 输出Schema：核心是提供完整的资源上下文，方便客户端直接使用，因此包含id（资源自身标识）和user（关联用户的详细信息）是合理的，能减少客户端额外调用用户接口的次数。

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