子资源创建URI选型：带main={main-id}查询参数还是层级路由？

针对你说的主资源（main-resource）和子资源（sub-resource）的一对多关联场景，两种URI方案各有门道，具体选哪个得看业务逻辑和API的设计需求：

一、层级URI方案（GET /main-resources/{main-id}/sub-resources、POST /main-resources/{main-id}/sub-resources） #

优点： #

• 语义够直白：层级结构一眼就能看出sub-resource是依赖main-resource的从属资源，完全符合RESTful资源定位的思路，用户不用查文档也能大概猜明白。
• 权限管控更顺手：如果子资源的访问权限完全绑定主资源，层级URI能在路由层面直接做校验——先验证main-id的合法性和用户权限，再处理子资源请求，逻辑更顺。
• 不会乱加参数：资源路径本身就明确了关联上下文，不会出现查询参数乱用、不规范的情况。

缺点： #

• 端点维护费劲儿：得给每个主资源下的子资源单独搞一套CRUD端点，要是有好几种主资源类型，路由数量直接翻倍，代码复杂度蹭蹭涨。
• 灵活性差点意思：要是后续需要加其他筛选条件（比如除了main-id还要按状态过滤），层级URI还是得加查询参数，不如一开始就用查询参数灵活。

二、查询参数方案（GET /sub-resources?main={main-id}、POST /sub-resources?main={main-id}） #

优点： #

• 端点复用性强：所有子资源操作都用/sub-resources这一个端点，不用额外维护层级路由，代码结构更干净，还能通过中间件统一解析参数注入逻辑。
• 扩展性拉满：后续要加其他筛选条件（比如?main=1&status=active&created_at=2024），直接加查询参数就行，根本不用改路由结构。
• 场景全覆盖：既能支持“关联主资源创建”，也能支持“独立创建”——POST请求要么通过查询参数传main-id，要么全靠请求体传参，逻辑统一不割裂。

缺点： #

• 语义没那么直观：对API不熟的用户，可能得查文档才知道main参数是啥意思，不如层级URI一眼懂。
• 权限校验稍麻烦：得在业务逻辑层或者中间件里单独校验main-id的合法性，没法在路由层面直接拦截，多了点校验成本。

三、具体怎么选？ #

1. 优先层级URI的情况：
   • 子资源完全依赖主资源存在，没主资源就活不了（比如订单明细，没有订单就不存在明细）。
   • 业务里子资源的操作必须强绑主资源，而且基本不需要其他筛选条件。
2. 优先查询参数的情况：
   • 子资源可以独立存在，只是和主资源有关联（比如文章和标签，标签能单独创建，也能关联文章）。
   • 需要经常用多个条件筛选子资源，或者以后大概率要加其他筛选条件。
   • 想尽量复用端点，少折腾路由维护的事儿。

要是你纠结语义和灵活性没法兼顾，也可以两种方案都支持：层级URI用来强调从属关系，查询参数用来灵活筛选，后端把两种请求的逻辑统一处理就行。比如：

• GET /main-resources/1/sub-resources 和 GET /sub-resources?main=1 返回一模一样的结果
• POST /main-resources/1/sub-resources 和 POST /sub-resources?main=1 执行相同的创建逻辑

这样既满足不同用户的使用习惯，又把语义和灵活性都顾到了。

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