API设计：不同数据访问层级用查询参数还是独立端点？

你的这种单端点加查询参数的设计是社区普遍认可的合理方案，尤其适配响应格式一致、仅数据范围不同的场景，具体分析如下：

单端点方案的优势 #

• 语义统一：GET /articles 本身就代表「获取文章集合」，用查询参数withUnpublished来区分数据范围，完全符合RESTful的资源定位逻辑，不会让开发者混淆多个相似端点的含义。
• 代码复用：后端无需维护两套高度重复的业务逻辑（比如文章列表的分页、排序、基础过滤规则），只需在权限校验后调整数据查询条件即可，大幅减少冗余代码。
• 客户端友好：客户端只需记住一个端点，根据需求动态添加或移除查询参数即可，不用切换不同请求路径，降低集成成本。

实施时的关键注意事项 #

• 严格权限校验：当请求携带withUnpublished参数时，必须强制校验令牌是否包含articles:read_unpublished权限，未通过校验直接返回403 Forbidden，杜绝未授权访问未发布内容。
• 默认行为明确：确保不带参数时默认返回已发布文章，这个规则要在API文档里清晰标注，避免开发者误解预期结果。
• 扩展性兼容：后续如果需要添加分页（如page、limit）或其他过滤条件（如categoryId），单端点方案能自然扩展，无需为新条件拆分端点。

适合拆分端点的场景 #

只有当两种场景的业务逻辑差异极大时，才考虑拆分，比如：

• 未发布文章需要返回审核状态、编辑日志等额外字段，导致响应结构和已发布文章差异明显。
• 两种场景的性能要求不同，比如未发布文章需要关联查询更多数据，单独拆分端点可针对性优化缓存或数据库查询。

但在你的场景中，响应格式一致、仅数据范围不同，单端点加查询参数的方案是更理想的选择。

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