简介

本指南面向DouPHP后台CRUD开发，聚焦控制器层的职责与设计模式，给出RESTful API设计、资源路由、动作方法的标准化实践；详细说明数据接收、验证、处理、存储的标准流程；提供分页、搜索过滤、排序的实现方法；说明批量删除、批量更新、导入导出等批量操作的机制；并给出创建标准CRUD控制器、复杂数据处理与权限控制的示例路径。同时涵盖错误处理、响应格式与API文档生成的最佳实践。

项目结构

后台采用分层组织：控制器负责HTTP请求与响应编排，服务层封装业务逻辑，模型负责数据访问，请求对象负责输入校验与白名单。基类统一了视图渲染、重定向、JSON响应、删除二次确认、AJAX布尔切换等通用能力。

graph TB
subgraph "后台"
AC["Admin BaseController"]
ARtC["ArticleController"]
APC["ProductController"]
AFR["ArticleFormRequest"]
end
subgraph "核心"
CC["Core BaseController"]
end
subgraph "API"
ABC["Api BaseController"]
end
ARtC --> AC
APC --> AC
AC --> CC
ABC --> CC
ARtC --> AFR

核心组件

• 后台控制器基类（Admin BaseController）
  • 统一视图渲染、布局变量注入、AI工具栏注入、按钮链接绝对化、Flash消息归一化、删除二次确认分流、AJAX布尔切换响应。
• 核心控制器基类（Core BaseController）
  • 提供json/response/redirect等通用响应构造器，供三端复用。
• API控制器基类（Api BaseController）
  • 在核心基类之上提供API端会员中心导航构建能力。
• 表单请求对象（FormRequest）
  • 按场景（store/update）定义校验规则与字段白名单，自动注入到控制器action参数。

架构总览

后台CRUD遵循“控制器编排 + 服务实现 + 请求校验”的分层模式：

• 控制器：接收请求、调用服务、返回响应（视图/重定向/JSON）。
• 服务：封装增删改查、批量操作、复杂业务规则。
• 请求对象：集中管理校验规则与白名单，支持多场景。
• 基类：提供统一的响应与页面能力，减少重复代码。

sequenceDiagram
participant C as "控制器"
participant R as "请求对象"
participant S as "服务"
participant V as "视图/响应"
C->>R : 注入并validated()
R-->>C : 已校验数据
C->>S : insert/update/delete/action
S-->>C : 结果(含消息/跳转/确认URL)
C->>V : view()/redirect()->with()/respondDeleteResult()
V-->>C : 响应

详细组件分析

控制器基类与响应规范

• Admin BaseController
  • view(): 合并布局变量与页面数据，注入AI工具栏，渲染模板。
  • layoutVars(): 默认注入flashes、page_actions、page_sub_actions、面包屑等。
  • respondDeleteResult(): 根据是否需二次确认，返回302+flash或dou_msg.htm确认页。
  • respondToggle(): AJAX时返回JSON，普通请求走302+flash。
• Core BaseController
  • json()/response()/redirect(): 统一响应构造。
• Api BaseController
  • buildLinkUserCenter(): 复用前台导航构建器。

classDiagram
class CoreBaseController {
+json(data, statusCode, encodeOptions)
+response(content, statusCode, headers)
+redirect(url, statusCode)
}
class AdminBaseController {
+view(template, data, statusCode)
+layoutVars() array
+respondDeleteResult(result)
+respondToggle(request, value, message, backUrl)
}
class ApiBaseController {
+buildLinkUserCenter(currentModule) array
}
AdminBaseController --|> CoreBaseController
ApiBaseController --|> CoreBaseController

文章模块CRUD控制器

• 列表：读取分类ID、关键词、页码，调用服务获取分页数据，渲染article.htm。
• 新增：清理草稿附件、生成草稿令牌、准备默认数据，渲染表单。
• 提交新增：通过ArticleFormRequest按scene=store校验，调用服务insert，重定向至编辑页并带成功提示。
• 编辑：校验id合法性，加载编辑数据，渲染表单。
• 提交更新：按scene=update校验，调用服务update，重定向回编辑页。
• 删除：校验id，调用服务delete，使用respondDeleteResult处理二次确认或成功跳转。
• 批量操作：统一入口action，调用服务action，成功后重定向并提示。

sequenceDiagram
participant U as "管理员"
participant AC as "ArticleController"
participant FR as "ArticleFormRequest"
participant AS as "ArticleService"
U->>AC : GET /admin/article (index)
AC->>AS : buildArticleListData(...)
AS-->>AC : {list,pager}
AC-->>U : 渲染列表
U->>AC : POST /admin/article/store
AC->>FR : validated()
FR-->>AC : 已校验数据
AC->>AS : insert(data, draft_token, admin_id)
AS-->>AC : newId
AC-->>U : 重定向至编辑页(+success)

商品模块CRUD控制器

• 列表：支持分类筛选、关键词、分页，渲染product.htm。
• 新增：清理草稿、生成令牌、准备默认数据、可选品牌与用户等级选项。
• 提交新增：按scene=store校验，调用服务insert，重定向至编辑页。
• 编辑：校验id，加载编辑数据、属性列表、Markdown内容等，渲染表单。
• 提交更新：按scene=update校验，调用服务update，重定向回编辑页。
• 缩略图批量处理：根据查询条件与掩码标签刷新缩略图。
• 型号关联Ajax：参数校验后返回片段。
• 删除：校验id，调用服务delete，使用respondDeleteResult。
• 批量操作：统一入口action，调用服务action，成功后重定向并提示。

flowchart TD
Start(["进入商品列表"]) --> Read["读取 category_id / keyword / page"]
Read --> Query["调用服务构建列表数据"]
Query --> Render["渲染 product.htm"]
Render --> End(["完成"])

表单请求与校验

• ArticleFormRequest
  • validationData(): 在POST基础上补充update场景的id，确保规则生效。
  • rules(): 定义字段白名单与校验规则，区分store/update场景；支持slug开关与唯一性校验；draft_token在store场景必填。
  • 通过容器按action名注入scene，自动完成校验与白名单过滤。

flowchart TD
Enter(["进入 store/update"]) --> Scene{"场景?"}
Scene --> |store| RulesStore["应用store规则<br/>draft_token必填"]
Scene --> |update| RulesUpdate["应用update规则<br/>id必填"]
RulesStore --> Validated["validated() 返回白名单数据"]
RulesUpdate --> Validated
Validated --> Next["交给控制器或服务处理"]

分页、搜索过滤与排序

• 分页：控制器从请求中读取page，调用服务返回列表与pager，模板渲染分页控件。
• 搜索过滤：读取keyword/category_id等参数，传入服务进行条件组装。
• 排序：由服务内部决定默认排序或扩展排序参数（具体实现位于服务层）。

批量操作机制

• 统一入口：action方法接收post数据，交由服务执行批量逻辑（如批量删除、状态切换等）。
• 响应：成功后重定向回列表页并携带success提示。
• 二次确认：删除可通过respondDeleteResult返回confirm_url触发二次确认页。

数据权限控制

• 控制器通过auth('admin')->id()获取当前管理员ID，用于数据归属与审计。
• 服务层可根据管理员角色/权限进行行级数据过滤（具体实现位于服务层）。
• 建议：将权限判断下沉至服务层，控制器仅做编排。

RESTful API设计与资源路由

• 资源路由：每个模块对应一个路由文件，映射到控制器动作（如admin/article.php -> ArticleController）。
• 动作约定：index/list、create/store、edit/update、destroy、action（批量）。
• 响应格式：
  • 后台页面：view()/redirect()->with('success', msg)
  • 删除二次确认：respondDeleteResult()
  • AJAX布尔切换：respondToggle()
  • API端：优先使用ApiResponse::success/error（核心基类提供json/response）

依赖关系分析

• 控制器依赖服务：所有CRUD逻辑下沉到服务，控制器只做编排。
• 控制器依赖请求对象：校验与白名单集中在FormRequest。
• 基类提供通用能力：视图、重定向、响应、AI工具栏注入等。

graph LR
AC["ArticleController"] --> ASvc["ArticleService"]
PC["ProductController"] --> PSvc["ProductService"]
AC --> AReq["ArticleFormRequest"]
AC --> ABc["Admin BaseController"]
PC --> ABc
ABc --> CBc["Core BaseController"]

性能考虑

• 列表查询避免大字段：服务层在列表查询中排除content等大字段，减少内存占用。
• 批量预取：对图片等资源进行批量URL解析，避免循环中逐条查库。
• 缓存：首页与配置项可结合缓存减少重复计算。
• 分页：始终使用分页，避免一次性加载大量数据。

故障排查指南

• 表单校验失败：检查FormRequest的rules与validationData，确认场景绑定是否正确。
• 非法ID访问：控制器在edit/destroy中对id进行合法性校验，失败抛出领域异常并跳转。
• 删除未生效：确认服务返回结构包含back_url与message；如需二次确认，返回confirm_url。
• 批量操作无效：检查action方法是否正确传递post数据至服务，并重定向到正确地址。

结论

DouPHP后台CRUD以“控制器编排 + 服务实现 + 请求校验”为核心，配合基类提供的统一响应与页面能力，形成高内聚、低耦合的开发范式。遵循本文档的标准化流程，可快速构建稳定、可维护的后台功能，并便于扩展批量操作、权限控制与API文档生成。

附录

• 标准CRUD控制器清单
  • 文章：admin/controller/article/ArticleController.php
  • 商品：admin/controller/product/ProductController.php
• 表单请求示例
  • 文章表单请求：admin/request/article/ArticleFormRequest.php
• 基类参考
  • 后台基类：admin/controller/BaseController.php
  • 核心基类：core/controller/BaseController.php
  • API基类：api/controller/BaseController.php