API路由命名最佳实践：解决动态参数与固定端点的冲突

问题根源 #

路由框架会按注册顺序或匹配优先级处理请求，动态路由:id属于模糊匹配，会优先捕获/tasks/后的任意字符串，导致archived-count被误识别为ID参数。

最佳实践解决方案 #

• 调整路由注册顺序
  所有静态路径的路由（如/tasks/archived-count）必须早于动态参数路由（如/tasks/:id）注册。绝大多数后端框架（Express、NestJS、FastAPI等）遵循"先匹配先处理"的规则，提前注册静态路由就能避免被动态路由拦截。
  示例（Express）：

  // 先注册静态统计路由
  app.get('/api/v1/tasks/archived-count', (req, res) => {
    res.json({ archivedCount: 12 });
  });
  
  // 后注册动态详情路由
  app.get('/api/v1/tasks/:id', (req, res) => {
    res.json({ taskId: req.params.id });
  });
  

• 给动态路由参数添加匹配约束
  通过正则表达式限定:id的格式（比如仅允许数字、UUID），让动态路由只匹配符合ID规则的字符串，自然排除archived-count这类非ID格式的路径。
  示例（Express）：

  // 限定id为数字格式
  app.get('/api/v1/tasks/:id(\\d+)', (req, res) => {
    res.json({ taskId: req.params.id });
  });
  
  // 注册静态路由（顺序不强制，但建议仍放在前面）
  app.get('/api/v1/tasks/archived-count', (req, res) => {
    res.json({ archivedCount: 12 });
  });
  

• 重构路由结构（规范API设计）
  从RESTful语义出发，将统计类接口与资源详情接口分离，避免路径重叠：

  • 方案1：将统计接口移到子路径，如GET /api/v1/tasks/stats/archived-count
  • 方案2：用查询参数区分，如GET /api/v1/tasks?type=archived&action=count
    这种方式从根源上消除路由冲突，同时让API结构更清晰易懂。

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