# 创建后端 (Adminhtml) 控制器操作 ## 说明此技能将指导您在 Adobe Commerce/Magento 2 (Mage-OS) 中为管理区域创建后端控制器操作。后端控制器通过适当的授权和 ACL（访问控制列表）集成来处理 Magento 管理面板中的 HTTP 请求。 ## 何时使用 * 创建自定义管理页面或部分 * 为管理 UI 组件构建 AJAX 端点 * 实现管理表单提交处理程序 * 为网格组件创建大量动作 * 构建需要授权的自定义管理操作 ## 先决条件 * 现有的具有适当结构的 Magento 2 模块 * 了解ACL（访问控制列表）系统 * 了解 Magento 路由和依赖注入 * 了解管理会话和授权 ## Adobe 文档中的最佳实践 ### 1\.扩展后端操作基类后端控制器应该扩展 `\Magento\Backend\App\Action`：类 ActionName 扩展 \Magento\Backend\App\Action 实现 HttpGetActionInterface ### 2\.实现 HTTP 方法特定的接口始终实现 HTTP 方法特定的操作接口： * `HttpGetActionInterface` \- 用于 GET 请求 * `HttpPostActionInterface` \- 用于 POST 请求 * 两个接口都可以为接受多种方法的端点实现 ### 3\.定义 ACL 资源常量每个后端控制器必须定义“ADMIN_RESOURCE”常量： const ADMIN_RESOURCE = 'Vendor_Module::resource_name'; ### 4\.使用严格类型始终在控制器文件的顶部声明严格类型：声明(strict_types=1); ### 5\.授权是自动的 `\Magento\Backend\App\Action` 基类通过 `_isAllowed()` 方法自动检查 `ADMIN_RESOURCE` 常量与当前管理员用户的权限。 ## 逐步实施 ### 步骤 1：定义 ACL 资源 (acl.xml) 创建 `etc/acl.xml` 来定义访问控制资源： <访问控制列表> <资源> **ACL 资源结构：** * 每个资源都有一个唯一的ID（例如`Vendor_Module::entity_save`） * 资源是分层的——子资源继承父资源的权限 * 管理员用户必须拥有资源访问控制器的权限 ### 步骤 2：创建后端路由 (routes.xml) 在 `etc/adminhtml/routes.xml` 中定义路由配置： <路由器ID =“管理员”> <模块名称=“Vendor_Module”之前=“Magento_Backend”/> **网址结构：** `https://yourdomain.com/admin/{frontName}/{controller}/{action}` **示例：** 对于 frontName `vendormodule`，URL 将为：`https://yourdomain.com/admin/vendormodule/entity/index` ### 步骤 3：创建管理菜单 (menu.xml) [可选] 创建 `etc/adminhtml/menu.xml` 以添加菜单项： <菜单> <添加 id="Vendor_Module::menu" 标题=“模块名称” 模块=“供应商_模块” 排序顺序=“100” 资源=“Vendor_Module::菜单”/> <添加 id="Vendor_Module::entity" title="管理实体" 模块=“供应商_模块” 排序顺序=“10” 父=“Vendor_Module::菜单” 操作=“供应商模块/实体/索引” 资源=“Vendor_Module::实体”/> <添加 id="Vendor_Module::设置" 标题=“设置” 模块=“供应商_模块” 排序顺序=“20” 父=“Vendor_Module::菜单” 行动=“adminhtml / system_config /编辑/部分/供应商模块” 资源=“Vendor_Module::config”/> ### 步骤 4：创建控制器目录结构创建控制器目录：应用程序/代码/供应商/模块名称/控制器/Adminhtml/ └── 控制器名称/ └── ActionName.php **示例：** `Controller/Adminhtml/Entity/Index.php` 映射到 URL：`/admin/vendormodule/entity/index` ### 步骤 5：创建后端控制器操作类 #### 示例 1：管理网格页面控制器 resultPageFactory = $resultPageFactory; } /** * 执行动作 * * @返回页面 */ 公共函数execute()：页面 { /** @var 页面 $resultPage */ $resultPage = $this->resultPageFactory->create(); $resultPage->setActiveMenu('Vendor_Module::entity'); $resultPage->getConfig()->getTitle()->prepend(__('管理实体')); 返回$结果页； } } #### 示例 2：JSON 响应控制器（AJAX 端点） resultJsonFactory = $resultJsonFactory; $this->collectionFactory = $collectionFactory; } /** * 执行动作 * * @return 结果接口 */ 公共函数execute()：ResultInterface { $searchKey = $this->getRequest()->getParam('searchKey'); $pageNum = (int)$this->getRequest()->getParam('page', 1); $limit = (int)$this->getRequest()->getParam('limit', 10); /** @var \Vendor\Module\Model\ResourceModel\Entity\Collection $collection */ $collection = $this->collectionFactory->create(); $collection->addFieldToFilter('name', ['like' => "%{$searchKey}%"]); $collection->setCurPage($pageNum)->setPageSize($limit); $totalValues = $collection->getSize(); $结果=[]; foreach（$collection 作为$entity）{ $结果[$entity->getId()] = [ '值' => $entity->getId(), '标签' => $entity->getName(), 'identifier' => sprintf(__('ID: %s'), $entity->getId()) ]; } /** @var \Magento\Framework\Controller\Result\Json $resultJson */ $resultJson = $this->resultJsonFactory->create(); 返回 $resultJson->setData([ '选项' => $结果， '总计' => 空($结果) ? 0：$totalValues ]); } } #### 示例 3：使用表单键验证保存操作 entityFactory = $entityFactory; $this->entityRepository = $entityRepository; } /** * 执行动作 * * @return 结果接口 */ 公共函数execute()：ResultInterface { $resultRedirect = $this->resultRedirectFactory->create(); $data = $this->getRequest()->getPostValue(); 如果（！$数据）{ $this->messageManager->addErrorMessage(__('没有数据可保存。')); 返回 $resultRedirect->setPath('*/*/'); } 尝试{ $entityId = $this->getRequest()->getParam('entity_id'); 如果 ($entityId) { $entity = $this->entityRepository->getById($entityId); } 否则{ $entity = $this->entityFactory->create(); } $实体->setData($data); $this->entityRepository->save($entity); $this->messageManager->addSuccessMessage(__('实体保存成功。')); if ($this->getRequest()->getParam('back')) { 返回 $resultRedirect->setPath('*/*/edit', ['id' => $entity->getId()]); } 返回 $resultRedirect->setPath('*/*/'); } catch (LocalizedException $e) { $this->messageManager->addErrorMessage($e->getMessage()); } catch (\Exception $e) { $this->messageManager->addExceptionMessage( $e, __('保存实体时出现问题。') ）； } return $resultRedirect->setPath('*/*/edit', ['id' => $entityId ?? null]); } } #### 示例 4：群体动作控制器过滤器= $过滤器； $this->collectionFactory = $collectionFactory; $this->entityRepository = $entityRepository; } /** * 执行动作 * * @return 结果接口 */ 公共函数execute()：ResultInterface { 尝试{ $collection = $this->filter->getCollection($this->collectionFactory->create()); $deletedCount = 0; foreach（$collection 作为$entity）{ $this->entityRepository->delete($entity); $deletedCount++； } $this->messageManager->addSuccessMessage( __('总共 %1 条记录已被删除。', $deletedCount) ）； } catch (LocalizedException $e) { $this->messageManager->addErrorMessage($e->getMessage()); } catch (\Exception $e) { $this->messageManager->addExceptionMessage( $e, __('删除记录时发生错误。') ）； } /** @var \Magento\Backend\Model\View\Result\Redirect $resultRedirect */ $resultRedirect = $this->resultFactory->create(ResultFactory::TYPE_REDIRECT); 返回 $resultRedirect->setPath('*/*/'); } } #### 示例 5：删除操作 entityRepository = $entityRepository; } /** * 执行动作 * * @return 结果接口 */ 公共函数execute()：ResultInterface { $resultRedirect = $this->resultRedirectFactory->create(); $id = $this->getRequest()->getParam('id'); 如果（！$id）{ $this->messageManager->addErrorMessage(__('需要实体 ID。')); 返回 $resultRedirect->setPath('*/*/'); } 尝试{ $this->entityRepository->deleteById((int)$id); $this->messageManager->addSuccessMessage(__('实体删除成功。')); } catch (LocalizedException $e) { $this->messageManager->addErrorMessage($e->getMessage()); } catch (\Exception $e) { $this->messageManager->addExceptionMessage( $e, __('删除实体时发生错误。') ）； } 返回 $resultRedirect->setPath('*/*/'); } } ### 第 6 步：创建布局 XML 创建布局 XML：`view/adminhtml/layout/vendormodule_entity_index.xml` <页面 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:View/Layout/etc/page_configuration.xsd"> <更新句柄=“样式”/> <正文> <参考容器名称=“内容”> ### 步骤 7：清除缓存并测试 # 清除缓存 ddev exec bin/magento 缓存：刷新 # 升级设置（针对新的 ACL 资源） ddev exec bin/magento 设置：升级 # 如果需要的话编译 ddev exec bin/magento 设置：di：编译 # 测试对管理控制器的访问 # 导航至：https://ntotank.ddev.site/admin/vendormodule/entity/index ## 常见模式 ### 模式 1：内联编辑（AJAX 保存）公共函数execute()：ResultInterface { $resultJson = $this->resultJsonFactory->create(); $items = $this->getRequest()->getParam('items', []); 如果（空（$items））{ 返回 $resultJson->setData([ 'messages' => [__('请更正发送的数据。')], '错误' => true ]); } foreach ($items as $entityId => $entityData) { 尝试{ $entity = $this->entityRepository->getById($entityId); $entity->setData(array_merge($entity->getData(), $entityData)); $this->entityRepository->save($entity); } catch (\Exception $e) { 返回 $resultJson->setData([ '消息' => [$e->getMessage()], '错误' => true ]); } } 返回 $resultJson->setData([ 'messages' => [__('记录已保存。')], '错误' => 假 ]); } ### 模式 2：自定义授权检查 /** * 检查管理员是否有权限 * * @返回布尔值 */ 受保护函数 _isAllowed(): bool { // 自定义授权逻辑 $isAllowed = $this->_authorization->isAllowed('Vendor_Module::entity'); // 额外的自定义检查 if ($isAllowed && $this->getRequest()->getParam('special_flag')) { $isAllowed = $this->_authorization->isAllowed('Vendor_Module::special_permission'); } 返回$isAllowed； } ### 模式 3：在管理表单中上传文件公共函数execute()：ResultInterface { $data = $this->getRequest()->getPostValue(); // 处理文件上传 if (isset($_FILES['image']) && $_FILES['image']['name']) { 尝试{ $uploader = $this->uploaderFactory->create(['fileId' => 'image']); $uploader->setAllowedExtensions(['jpg', 'jpeg', 'gif', 'png']); $uploader->setAllowRenameFiles(true); $uploader->setFilesDispersion(true); $结果 = $上传者->保存( $this->mediaDirectory->getAbsolutePath('vendor_module/entity/') ）； $data['image'] = 'vendor_module/entity' 。 $结果['文件']; } catch (\Exception $e) { $this->messageManager->addErrorMessage($e->getMessage()); } } // 继续保存逻辑... } ## 测试管理控制器 ### 单元测试示例创建：`Test/Unit/Controller/Adminhtml/Entity/SaveTest.php` createMock(\Magento\Backend\App\Action\Context::class); $entityFactory = $this->createMock(\Vendor\Module\Model\EntityFactory::class); $entityRepository = $this->createMock(\Vendor\Module\Api\EntityRepositoryInterface::class); // 创建控制器实例 $controller = new Save($context, $entityFactory, $entityRepository); // 测试执行 // 在这里添加断言 } } ## 故障排除 ### 问题：访问被拒绝 (403) * 检查 ACL 资源是否在 `etc/acl.xml` 中定义 * 验证“ADMIN_RESOURCE”常量与 ACL 资源 ID 匹配 * 确保管理员用户角色具有资源的权限 * 运行 `ddev exec bin/magento 缓存:flush` * 检查商店 > 配置 > 管理 > 管理基本 URL ### 问题：404 未找到 * 验证 `routes.xml` 是否在 `etc/adminhtml/` 中（而不是 `etc/frontend/`） * 检查frontName是否唯一且不冲突 * 确保控制器扩展 `\Magento\Backend\App\Action` * 运行 `ddev exec bin/magento setup:upgrade` ### 问题：表单密钥验证失败 * 确保表单包含表单键：`getFormKey() ?>` * POST请求自动验证表单键 * 对于 AJAX，在数据中包含表单键 ### 问题：菜单未显示 * 检查 `menu.xml` 是否在 `etc/adminhtml/` 中 * 验证ACL资源权限 * 清除管理缓存：`ddev exec bin/magento 缓存：清理配置` * 检查admin用户是否有资源的权限 ## 安全最佳实践 1. **始终定义 ACL 资源** ：切勿对生产控制器使用 `const ADMIN_RESOURCE = 'Magento_Backend::admin'` 2. **验证输入**：使用输入验证器和过滤器 3. **使用表单密钥**：Magento 自动验证 POST 请求的表单密钥 4. **转义输出** : 在模板中使用 `$escaper->escapeHtml()` 5. **检查权限** : 让 `_isAllowed()` 处理授权 6. **使用类型提示**：确保声明严格类型 7. **记录敏感操作** ：使用记录器进行删除/更新操作 ## 参考文献 * Adobe Commerce 前端核心： * Magento 2 后端开发： * ACL 文档： * 管理 UI 组件： ## NTOTanks-具体注释 * 遵循PSR-12编码标准 * 对所有 Magento CLI 命令使用 `ddev exec` 前缀 * 后端控制器与 UI 组件的 Hyvä 管理模块集成 * 清除缓存并重新编译后测试管理控制器 * 在“系统”>“用户角色”中检查管理员用户权限

创建后端控制器

包含技能