同一组实体存在多重关系时如何设计区分API端点

两个查询对应User和Course的两类完全独立的关联关系，不能共用无修饰的/users/me/courses路径，以下是两种经过生产验证的通用设计方式，可根据项目规范选择：

方案1：路径明确标注关联语义（优先推荐） #

直接在路径中体现关联关系，语义零歧义，联调、维护成本最低：

• 获取用户正在学习的课程：GET /users/me/learning-courses，也可按嵌套资源写法设计为GET /users/me/courses/learning
• 获取用户拥有编辑权限的课程：GET /users/me/editable-courses，也可按嵌套资源写法设计为GET /users/me/courses/editable

这种方式扩展性强，后续如果需要新增用户收藏的课程、已学完的课程等同类查询，直接新增对应路径即可，不会影响现有接口逻辑。

方案2：统一入口+语义化查询参数 #

如果希望把用户关联的所有课程查询收敛到同一个路径入口，可以保留基础路径，通过有明确含义的查询参数区分关联类型：

• 获取用户正在学习的课程：GET /users/me/courses?relation=learning
• 获取用户拥有编辑权限的课程：GET /users/me/courses?relation=editable

使用该方案需要注意两个规则：

• 禁止使用无意义的魔法值作为参数值，比如不要设计?type=1、?r=edit这类需要额外查文档才能理解的写法
• 必须明确缺省参数的返回逻辑：要么不带参数时默认返回某一类常用数据（比如默认返回学习中的课程），要么直接返回参数校验错误，绝对不能把不同关联关系的课程混合返回。

不要为了刻意贴合所谓的RESTful格式硬用模糊的通用路径，REST设计的核心是资源语义清晰，把不同业务含义的资源集合拆分路径完全符合设计原则，不属于冗余设计。

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