用途:面向 Bitrix 框架(main 23.0+,已验证 main 26.800.0)的 Engine\Controller 控制器开发,覆盖 AJAX 与路由动作的命名、参数注入、过滤器、访问控制与响应封装。
主要能力与规则:
- 基础:文件结构、动作命名、最小控制器、自动注入参数、PageNavigation,见 rules/basics.md。
- 过滤器:默认预过滤器、过滤属性、configureActions()、#[ActionAccess]、自定义过滤器,见 rules/filters.md。
- 响应:错误处理、JSON 封装、响应类、renderView()、作用域、REST v3,见 rules/errors-response.md。
关键约束:
- 动作只做编排:输入 → 服务 → Result → 数据或 addErrors();服务通过动作参数注入(DI 规范见 bitrix-framework)。
- 过滤属性自 main 26.250 起可用;旧内核用 configureActions()。同一动作不可同时使用两者,否则抛 ActionConfigurationException。
- METHOD_* 常量位于 ActionFilter\HttpMethod,而非属性 Attribute\Rule\HttpMethod;在属性上引用会在构建控制器时抛错,导致该控制器所有动作失败。
- 规则属性会追加到默认项(Authentication、HttpMethod([GET, POST])、Csrf);重复添加 #[Authentication] 或 #[Csrf] 会使过滤器执行两次。
- PascalCase 文件需按类名大小写写控制器段:vendor:module.Post.create;小写 post 会解析到 lib/infrastructure/controller/post.php 并在 Linux 上失败。REST 会将方法名小写,因此 PascalCase 控制器无法通过经典 REST(bitrix-rest)访问。
- HTML(renderView/renderComponent)仅用于路由可达的控制器;BX.ajax.runAction() 期望 JSON。
适用场景:编写或维护 Bitrix 控制器、AJAX 接口与路由动作。限制:具体安装命令、收费与平台信息暂未提供。