RESTful API端点架构优化：多角色共用同一端点的最佳方案

针对你遇到的「同一用户兼具admin和customer角色时，端点无法正确识别用户期望身份执行对应逻辑」的问题，以下是几种实用的解决思路：

1. 让用户在请求中明确指定身份上下文 #

在请求中加入明确标识字段，告诉系统当前要以哪种角色执行操作：

• 请求体字段：在PUT请求的body里添加acting_as字段，可选值为admin或customer。后台服务先校验该用户是否拥有对应的角色，再执行对应逻辑：
  • 若acting_as=customer，需额外验证该用户是目标订单的所有者，再执行审批/拒绝逻辑
  • 若acting_as=admin，验证用户的admin权限后执行照片更新逻辑
• 查询参数：在URL后追加?acting_as=customer或?acting_as=admin，实现方式和请求体字段类似，优势是GET/DELETE请求也能复用逻辑，且UI切换身份时只需修改参数即可

2. 通过请求上下文自动识别 #

利用请求来源的上下文信息自动判断用户意图，无需手动输入：

• 在不同UI的请求头中加入自定义标识，比如客户UI的请求统一携带X-Acting-Role: customer，后台服务读取该头信息后执行对应逻辑
• 注意必须配合资源归属校验：即使头信息指定customer，也要验证用户确实是该订单的所有者；指定admin时，验证用户的admin权限

3. 按操作类型拆分端点（推荐） #

遵循REST单一职责原则，将两种不同的操作拆分到独立端点，从根源避免身份混淆：

• PUT:/api/orders/{ORDER_ID}/photo-proof：仅用于admin更新照片凭证，后台校验用户的admin权限
• POST:/api/orders/{ORDER_ID}/photo-proof/approval：用于审批/拒绝操作，后台校验用户是该订单的所有者（兼具admin角色的用户只要是订单所有者也能调用）
  这种方案更清晰，便于维护和测试，也符合API设计的最佳实践

通用注意事项 #

• 所有方案都必须做双重校验：角色权限校验 + 资源归属校验，不能仅依赖角色判断
• 日志中记录用户的实际角色和操作时指定的身份上下文，便于问题排查

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