技能使用指南

phoenix-routing（Phoenix路由定义Skill）Skill 是什么？如何安装使用？

phoenix-routing（Phoenix路由定义Skill）专注 Phoenix 路由层，覆盖单路由、resources 资源路由、scope 作用域、pipeline 管道与 ~p 验证路由，并内置最佳实践与常见陷阱清单，帮你在编译期发现路由错误、统一团队写法。本文详解安装接入、使用步骤、竞品对比与典型场景，助你快速上手。

Phoenix路由定义Skillphoenix-routing
8 个章节 约 15 分钟阅读 AI 智能生成

Phoenix路由定义Skill：用编译期校验把 Phoenix 路由写对、写稳、写清楚

  • 一句话定位：phoenix-routing 是一个专注于 Phoenix 框架路由层的 AI 技能，帮你在 router.ex 里定义单路由、资源路由、作用域、管道与验证路由，并给出配套的最佳实践与常见陷阱提醒。
  • 核心能力：覆盖 get/post/patch/put/delete 单路由、resources 八条 RESTful 路由、:only/:except/:as、嵌套资源、scope 嵌套作用域、pipeline 与 pipe_through、forward 转发，以及用 ~p 符咒做编译时验证。
  • 差异化价值：它不仅“会写宏”，还内建了 15 条最佳实践和 15 条常见陷阱清单（硬编码路径、过度嵌套、漏配管道、路由顺序错误等），相当于把资深 Phoenix 开发者的经验固化进工作流。
  • 使用门槛：无需手动敲命令调用，它作为 AI 助手的后台能力，在你描述“给用户模块加一套 CRUD 路由”这类需求时被自动匹配；技能详情中标注“用户可调用: false”，并允许 Bash、Read 两类工具。
  • 适合谁用：正在用 Elixir / Phoenix 做 Web 或 API 开发的后端工程师、刚接触 Phoenix 路由约定的新手，以及需要重构老项目路由结构的维护者。

1. 该技能叫什么？如何下载安装 AI 技能提升开发效率？

这个技能的中文名是 Phoenix路由定义Skill，英文名 phoenix-routing，技能 ID 为 14199。

它要解决的问题很具体：Phoenix 的路由层宏非常多，resources、scope、pipeline、~p 各自有各自的写法约定，新手容易写出“能跑但不规范”的路由——比如直接拼接字符串路径而不是用验证路由、把资源嵌套到四五层、忘了给敏感路由挂上身份验证管道、把通用路由写在具体路由前面导致后者永远匹配不到。这类问题在编译期不报错，往往上线后才暴露。该技能的定位就是把“写对路由”这件事变成一个可复用、可校验的过程。

安装与接入思路（一键式 AI 技能的标准流程）：

  1. 准备前提：你已经在一个支持 AI 技能（Skill）机制的编程助手或 IDE 环境中工作，并且本地有可运行的 Phoenix 项目（用于让技能读取 router.ex 或执行 mix phx.routes 校验）。
  2. 检索技能：在技能市场 / 技能仓库 / 技能管理面板中，用英文名 phoenix-routing 或技能 ID 14199 搜索。具体入口位置与检索方式以官方说明为准。
  3. 添加并启用：将该技能安装到当前工作区或项目级配置中。安装命令、配置文件路径等细节，以官方说明为准。
  4. 确认工具授权：该技能声明允许使用 Bash 与 Read 两类工具。前者用于执行 mix phx.routes 之类的只读检查命令，后者用于读取路由文件内容。若你的环境默认禁用 Bash，需要在权限设置中放行，否则路由校验类能力会受限。
  5. 验证是否生效：安装后，用一句自然语言提出一个路由需求，例如“给订单模块加一套只读的 RESTful 路由，挂在 /api/v1 下并走 JSON 管道”。如果返回结果中出现了 scope、pipe_through、resources ... only: [:index, :show] 这样的规范结构，并用 ~p 生成路径助手，说明技能已被正确加载。
  6. 注意调用方式：技能详情中明确标注“用户可调用: false”，这意味着它通常不是由你手动点按钮或敲命令触发，而是由 AI 助手在识别到 Phoenix 路由相关任务时自动匹配调用。你只需要用自然语言描述任务即可。

2. 该技能的主要功能和特点

  • 单路由与全 HTTP 动词支持：可用 get、post、patch、put、delete 定义单条路由，并正确映射到控制器动作。
  • 动态段捕获：使用 :param_name 语法捕获 URL 参数，例如 get "/hello/:messenger", HelloController, :show，并说明该段会在控制器参数字典中可用。
  • 资源路由生成：resources "/users", UserController 一次性生成 index / edit / new / show / create / update / delete 共八条标准 RESTful 路由。
  • 资源路由瘦身：通过 only: 只生成需要的动作，通过 except: 排除不需要的动作，避免把全部 CRUD 接口暴露出去。
  • 别名与路径助手：as: :person 可自定义路径助手名称，让 ~p"/person" 替代 ~p"/users"。
  • 嵌套资源：支持父子层级关系，自动生成包含 :user_id 这类父级参数的路径结构。
  • 编译时验证路由：推荐使用 ~p 符咒，支持静态路径、动态变量插值、直接传结构体（通过 Phoenix.Param 协议提取 ID），把路由错误提前到编译期。
  • 作用域与命名空间：scope 用于分组路由、复用控制器模块前缀、构建嵌套作用域，并天然支持 API 版本化（如 /api/v1 与 /api/v2）。
  • 管道机制：pipeline 定义插头集合，pipe_through 将管道绑定到作用域，支持自定义插头、管道嵌套（如先 :browser 再鉴权插头）。
  • 高级管道范式：内置会话管理、多租户组织上下文注入、购物车获取或创建等可参考的管道实现模板。
  • 转发能力：forward 把某个路径前缀整体委托给另一个插头或应用，适合挂载管理后台、API 文档、后台作业面板。
  • 路由可观测性：指导使用 mix phx.routes 列出全部路由，并用 grep 过滤特定控制器或 HTTP 动词。
  • 自定义 URL 生成：通过实现 Phoenix.Param 协议的 to_param/1，让结构体生成基于 slug 的路径（如 /posts/my-great-post）。
  • 工程经验内建：附带的 15 条最佳实践与 15 条常见陷阱，把“怎么写得像老手”变成可检查的清单。

和普通编辑器的路由代码补全相比，它强在上下文理解与规范约束：补全只能给你片段，它能给出符合作用域分层、管道职责单一、验证路由优先原则的完整结构，并主动指出你可能踩的坑。

3. 如何使用该技能？

  1. 先讲清业务上下文。用一句自然语言描述模块、路径、动作范围与响应格式，例如：“我的 Phoenix 项目有个 PostController，需要文章列表、详情、创建、更新、删除，走 /api/v1，只返回 JSON。”
  2. 获取路由声明。技能会给出可直接粘贴到 router.ex 的宏定义，典型输出如下：
scope "/api/v1", HelloWeb.Api.V1, as: :api_v1 do
  pipe_through :api

  resources "/posts", PostController, except: [:new, :edit]
end
  1. 要求补齐路径助手。在控制器或模板里不要拼字符串，改用验证路由：~p"/api/v1/posts/#{post}"，其中 post 可以是结构体，Phoenix 会通过 Phoenix.Param 自动取 ID。
  2. 绑定管道。确认目标作用域通过 pipe_through 挂上了正确管道；若需要鉴权，让它生成一个像 pipeline :auth 这样职责单一的管道，再在敏感作用域上引用。
  3. 检查生成结果。让技能基于 Bash 工具执行 mix phx.routes，或用 mix phx.routes | grep posts 过滤，核对动词、路径、控制器、动作四列是否符合预期。
  4. 做一次规范复查。明确要求“按最佳实践和常见陷阱检查这段路由”，它会指出诸如硬编码路径、资源嵌套过深、路由顺序把通用规则放在具体规则之前、缺少 CSRF 或身份验证插头等问题。
  5. 输出说明。最终产出的通常是一段路由代码 + 路径助手用法 + 校验结论，你直接合并进项目即可，无需再手写样板。

4. 同类型竞品对比分析

方案名称 定位 核心功能 安装/使用门槛 适用场景 优势与不足
phoenix-routing（本技能） 面向 Phoenix 路由层的 AI 技能 单路由、资源路由、作用域、管道、验证路由、转发、路由检查与规范审查 需在支持技能机制的环境中安装并授权 Bash/Read，入口以官方说明为准 新建路由、重构路由结构、排查路由冲突 优势：覆盖面完整且带最佳实践与陷阱清单，输出即可用；不足：依赖宿主 AI 环境，路由之外的业务逻辑不负责
手写 Phoenix.Router 宏 框架原生方式 所有官方路由宏与管道能力 零安装，需熟悉宏语义与约定 所有 Phoenix 项目 优势：完全可控、无外部依赖；不足：规范全靠个人经验，容易漏配管道或写出未验证路径
查阅 Phoenix 官方路由指南 文档自学 权威说明与示例 零安装，需要自行检索与拼装 学习概念、查漏补缺 优势：最权威；不足：需要自己把文档片段改造成项目结构，无法针对你的代码给建议
Plug.Router 底层路由 更底层的通用路由方案 基于 Plug 的匹配与分发 需自行搭建匹配逻辑 非 Phoenix 场景、极简服务 优势：轻量灵活；不足：没有 resources 这类约定宏，也没有编译期验证路径助手，样板代码多

5. 该技能的典型应用场景与实际体验情况

场景一：个人开发者从零搭建 CRUD 后端。 角色是独立开发者，痛点是“知道要写资源路由，但不确定该不该生成 new/edit 这类给 HTML 表单用的动作”。使用方式是描述“纯 JSON API”后让技能生成 resources ... except: [:new, :edit]。实际体验：上手几乎无门槛，输出直接可粘贴；注意点是仍要自己确认控制器里对应动作确实存在，否则编译能过但运行时会缺函数。

场景二：团队做 API 版本化与前后端分离。 角色是后端团队成员，痛点是 /api/v1 与 /api/v2 并存时路径助手容易写混。技能会给出嵌套作用域加 as: 别名的结构，让 ~p"/api/v1/users"、~p"/api/v2/users" 各自独立。实际体验：效果明显，尤其是把字符串路径统一替换成 ~p 之后，重构时改名能立刻在编译期报错；注意事项是替换工作要一次性做完，混用字符串与验证路由会削弱收益。

场景三：多租户 SaaS 的鉴权与上下文注入。 角色是负责架构的后端工程师，痛点是“当前用户/组织上下文”散落在各处。技能提供了会话管道、assign_org_to_scope 组织注入、购物车获取或创建等可参考的管道写法，配合 pipeline :auth 做管道嵌套。实际体验：上手难度中等，需要理解插头执行顺序；注意事项是管道职责要单一，别把业务判断塞进路由定义里，这也是技能反复强调的一条实践。

场景四：老项目路由排查与重构。 角色是接手遗留项目的维护者，痛点是路由文件几百行、出现重复路由或匹配顺序问题。使用方式是让技能读取路由文件，结合 mix phx.routes | grep 逐段核对。实际体验：诊断效率高于纯人工通读，尤其对“通用路由抢走具体路由请求”这类隐蔽问题；注意事项是它会给出改动建议，但生产环境的管理、调试路由是否该暴露，仍需你按部署策略自行判断。

6. 该技能能为用户带来的价值

把隐性经验变成显性流程。 Phoenix 路由的坑大多不在语法，而在约定：该不该用 ~p、资源要不要 only、管道职责怎么切、嵌套几层算过深。技能把 15 条最佳实践与 15 条常见陷阱直接带到对话里，新手不必用一次线上事故来换这些经验。

把错误提前到编译期。 通过推荐 ~p 验证路由，路径拼写错误、参数类型不匹配、路由改名后遗漏更新等问题会在编译阶段暴露，而不是等到用户点击 404。对有一定规模的项目来说，这直接减少了回归测试与线上排查的时间。

降低上手门槛。 不熟悉 resources 八条路由映射关系、不清楚 :only/:except/:as 怎么组合的人，可以直接得到一份符合规范的路由定义，再对照理解，学习曲线显著变缓。

提升协作一致性。 团队里每个人写路由的风格容易发散，技能输出的结构统一（作用域分组、管道单一职责、验证路由优先），代码评审时争议点更少。

长期收益在于可维护性。 路由是 Web 应用的入口清单，结构清晰意味着后续加接口、做版本升级、拆分管理后台都更省力；forward 转发与作用域命名空间让模块边界天然清楚，项目变大后不会退化成一张巨型路由表。

7. 常见问题 FAQ

Q1：这个技能怎么安装？ 在支持 AI 技能机制的编程助手中，用英文名 phoenix-routing 或技能 ID 14199 检索并添加到工作区，然后确认 Bash、Read 工具权限已放行。具体安装入口、命令与配置路径以官方说明为准。

Q2：它是收费的吗？ 技能详情中没有提供任何定价信息，因此无法给出确定结论。是否收费取决于你所在平台的技能分发策略，请以官方说明为准。

Q3：为什么我不能像命令行工具那样手动调用它？ 技能信息中标注了“用户可调用: false”，说明它的设计定位是由 AI 助手在识别到 Phoenix 路由任务时自动匹配使用，而不是提供给用户直接执行的入口。你只需用自然语言描述需求即可。

Q4：它适合谁用？ 最适合正在用 Elixir / Phoenix 开发 Web 或 API 的后端工程师，尤其是刚接触 Phoenix 路由约定、或需要重构老项目路由结构的开发者。如果你用的是其他语言的框架，这个技能并不适用。

Q5：和直接手写路由、或查官方文档相比，我该选哪个？ 手写路由宏完全可控，但规范依赖个人经验；官方文档最权威，但需要自己把片段改造成项目结构。这个技能的价值在于把两者结合——基于你的实际代码给出符合约定的结构，并主动做规范与陷阱检查。建议用法是：用它出初稿和做复查，最终仍由你确认管道与鉴权策略是否符合部署要求。