按用户自定义权限过滤REST资源端点的最佳实践探讨

优先推荐查询参数过滤的方案，这是REST API设计领域的标准做法，完全适配你的场景，原因如下：

• 符合REST资源导向核心原则：店铺是统一的资源实体，不同权限对应的店铺只是这个资源集合的子集，没必要拆分出独立端点。
• 扩展性更强：后续如果新增权限类型（比如viewer），不需要新增API端点，只需要扩展参数的可选值即可。
• 代码复用性高：后端可以复用同一套店铺查询的基础逻辑，仅在最后追加权限过滤条件，减少重复代码的维护成本。

具体实现建议 #

• 使用直观的参数命名，比如 GET /api/v1/stores?permission=admin 或者 GET /api/v1/stores?role=admin，比 filter=permission:admin 更符合主流API的参数设计习惯，前后端都更容易理解。
• 后端必须做好权限校验：过滤前要确保用户确实拥有指定的权限类型，不能让用户通过参数绕过权限限制（比如不能让普通用户通过permission=admin获取不属于自己的店铺）；同时保留默认行为——不指定参数时返回用户所有有权限的店铺，和你当前的需求完全匹配。

为什么不推荐角色专属端点 #

• 会导致端点膨胀：后续新增权限类型时，就要不断新增/api/v1/admin-stores、/api/v1/manager-stores这类端点，维护成本直线上升。
• 违背REST的统一性原则：同一个资源被拆分成多个端点，会增加前后端开发的认知负担，也不符合API设计的简洁性要求。

其他可选方案（不推荐当前场景） #

• 如果未来权限逻辑变得复杂（比如需要同时筛选拥有admin和manager权限的店铺），可以考虑支持更灵活的过滤语法，比如 GET /api/v1/stores?filter=permission:in(admin,manager)，但当前场景下单参数的方式已经足够简洁实用。
• 也可以让后端返回用户所有有权限的店铺，并在每个店铺数据里带上用户的权限标识，由前端自行过滤展示。但这种方式会传输不必要的数据，浪费带宽，而且后端才是权限校验的可靠来源，前端过滤存在安全风险，不建议采用。

总结来说，用查询参数过滤是当前场景下的最优解，既符合REST设计规范，又能满足UI的视图需求，同时具备良好的扩展性。

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