SuperAPI AI 工具集

apply-phoenix-controller-conventions

编程与开发

查看项目

更新于 10-15 22:16

技能介绍

用途:在编写或修改 Phoenix 控制器模块时套用一致的惯用模式。若功能使用 LiveView,需先调用 phoenix-liveview-essentials;传统请求/响应场景可直接使用本技能。

主要能力与约定:路由用 resources 表达 RESTful、用 scope 分组;控制器保持精简,业务逻辑委托给 context;控制器 plug 用于认证与资源加载,采用 when action not in [...] 的排除式写法;每个涉及访问控制的 action 都要校验与授权;JSON API 用 FallbackController 统一处理错误,不在 action 内写 catch-all case;按格式匹配管线,JSON 用 :api(无 session、无 CSRF),HTML 用 :browser;plug 与 action 之间用 conn.assigns 传数据,不用 Process 字典;重定向路径不得插值用户输入,使用 ~p"..." 验证路由。

使用方式:路由中集合路由挂在父资源下、成员路由放顶层(Phoenix 无 shallow: true);plug 示例为 plug :require_authenticated_user when action not in [:index, :show] 与 plug :load_user when action in [:edit, :update];参数校验放在 context 的 changeset(cast/2 只允许声明字段),控制器原样透传参数;JSON 端点用 with 配合 action_fallback 与 FallbackController,按 {:error, :not_found}、{:error, :unauthorized} 等元组返回对应状态码;浏览器端对预期错误做模式匹配并配合 flash 重定向,用户触发的查询避免用 get_user!/1。

检查点:用 mix phx.routes 验证路由与管线,用 mix test test/controllers/ 验证错误元组映射与豁免 action 不触发认证 plug。

限制与常见错误:控制器内联 Repo.insert 等业务逻辑、公开 action 未加 action 守卫的认证 plug、重定向使用用户提供的 URL、每个 action 重复 JSON 错误处理、JSON 端点误用 :browser 管线、用 Process 字典跨 plug 传值均属错误做法。配套技能包括 phoenix-json-api、phoenix-liveview-essentials、phoenix-scopes、phoenix-uploads。