import{_ as s,o as a,c as t,a2 as h}from"./chunks/framework.B-QBKwc1.js";const y=JSON.parse('{"title":"控制器开发","description":"控制器是 HTTP 请求的入口，负责参数获取、调用 Service、返回统一 JSON 响应。","frontmatter":{},"headers":[],"relativePath":"zh/guide/controller.md","filePath":"zh/guide/controller.md"}'),n={name:"zh/guide/controller.md"};function k(l,i,p,e,r,d){return a(),t("div",null,[...i[0]||(i[0]=[h(`

3.6 控制器开发 ​

概述

控制器是 HTTP 请求的入口，负责参数获取、调用 Service、返回统一 JSON 响应。通过 #[Permission] 和 #[OperationLog] 注解实现权限校验和操作日志，配合基类快捷方法，单个接口通常只需几行代码。

控制器文件位置 ​

text
app/Http/Controllers/Api/ExampleController.php

完整代码（来自项目实际代码） ​

php
<?php

namespace App\\Http\\Controllers\\Api;

use App\\Attributes\\OperationLog;
use App\\Attributes\\Permission;
use App\\Http\\Controllers\\Controller;
use App\\Http\\Requests\\ExampleRequest;
use App\\Services\\ExampleService;
use Illuminate\\Http\\JsonResponse;

/**
 * 示例管理控制器
 *
 * 负责示例相关的接口入口，包含分页、列表、详情、新增、修改、删除、批量删除，
 * 以及数据导入、导出。
 * 具体业务逻辑委托给 ExampleService，控制器仅做参数校验、
 * 权限与日志标注及响应封装。
 *
 * 说明：
 * - 所有接口通过 #[Permission] 注解声明权限标识与描述，由框架统一鉴权。
 * - 所有接口通过 #[OperationLog] 注解声明操作日志（类型、模板），由框架统一记录。
 * - 导入 / 导出接口的日志类型分别为 TYPE_IMPORT、TYPE_EXPORT，与常规 CRUD 区分。
 * - 常规 CRUD 复用基类的
 *   _page / _list / _detail / _add / _update / _delete / _batchDelete 方法。
 * - 导入 / 导出走 ExampleService 的 import / export 专用方法。
 */
class ExampleController extends Controller
{
    /**
     * 构造函数
     *
     * 注入示例业务服务，供各接口方法复用。
     *
     * @param  ExampleService  $exampleService  示例业务服务
     */
    public function __construct(protected ExampleService $exampleService) {}

    /**
     * 查询分页
     *
     * 对应权限：sys:example:page，操作日志类型：查询。
     * 返回分页结构，适合列表页展示。
     *
     * @return JsonResponse 分页数据
     */
    #[OperationLog('示例管理-查询分页', OperationLog::TYPE_QUERY)]
    #[Permission('sys:example:page', '示例分页')]
    public function page(): JsonResponse
    {
        return $this->_page($this->exampleService);
    }

    /**
     * 查询列表
     *
     * 对应权限：sys:example:list，操作日志类型：查询。
     * 返回不分页的完整列表，适合下拉选择等场景。
     *
     * @return JsonResponse 列表数据
     */
    #[OperationLog('示例管理-查询列表', OperationLog::TYPE_QUERY)]
    #[Permission('sys:example:list', '示例列表')]
    public function list(): JsonResponse
    {
        return $this->_list($this->exampleService);
    }

    /**
     * 查询详情
     *
     * 对应权限：sys:example:detail，操作日志类型：查询，
     * 日志模板中包含示例ID：{id}。
     *
     * @param  int  $id  示例ID
     * @return JsonResponse 示例详情
     */
    #[OperationLog('示例管理-查询详情', OperationLog::TYPE_QUERY, '查询示例ID:{id}')]
    #[Permission('sys:example:detail', '示例详情')]
    public function detail(int $id): JsonResponse
    {
        return $this->_detail($this->exampleService, $id);
    }

    /**
     * 新增
     *
     * 对应权限：sys:example:add，操作日志类型：新增，
     * 日志模板中包含示例名称：{name}。
     *
     * @param  ExampleRequest  $request  已通过校验的示例请求
     * @return JsonResponse 新增结果
     */
    #[OperationLog('示例管理-新增', OperationLog::TYPE_ADD, '新增示例：{name}')]
    #[Permission('sys:example:add', '添加示例')]
    public function add(ExampleRequest $request): JsonResponse
    {
        return $this->_add($this->exampleService, $request->validated());
    }

    /**
     * 修改
     *
     * 对应权限：sys:example:update，操作日志类型：修改。
     * 若请求数据中缺少 id，则直接返回失败响应。
     *
     * @param  ExampleRequest  $request  已通过校验的示例请求
     * @return JsonResponse 修改结果
     */
    #[OperationLog('示例管理-修改', OperationLog::TYPE_UPDATE, '修改示例ID:{id}')]
    #[Permission('sys:example:update', '修改示例')]
    public function update(ExampleRequest $request): JsonResponse
    {
        $data = $request->validated();
        $id = $data['id'] ?? 0;
        if (empty($id)) {
            return $this->fail('缺少id参数');
        }

        return $this->_update($this->exampleService, $id, $data);
    }

    /**
     * 删除
     *
     * 对应权限：sys:example:delete，操作日志类型：删除，
     * 日志模板中包含示例ID：{id}。
     *
     * @param  int  $id  示例ID
     * @return JsonResponse 删除结果
     */
    #[OperationLog('示例管理-删除', OperationLog::TYPE_DELETE, '删除示例ID:{id}')]
    #[Permission('sys:example:delete', '删除示例')]
    public function delete(int $id): JsonResponse
    {
        return $this->_delete($this->exampleService, $id);
    }

    /**
     * 批量删除
     *
     * 对应权限：sys:example:batchDelete，操作日志类型：删除。
     * 从 JSON 请求体中读取 ids 数组，未传时按空数组处理。
     *
     * @return JsonResponse 批量删除结果
     */
    #[OperationLog('示例管理-批量删除', OperationLog::TYPE_DELETE)]
    #[Permission('sys:example:batchDelete', '批量删除')]
    public function batchDelete(): JsonResponse
    {
        $ids = $this->getJsonBody()['ids'] ?? [];

        return $this->_batchDelete($this->exampleService, $ids);
    }

    /**
     * 导出数据
     *
     * 对应权限：sys:example:export，操作日志类型：导出（TYPE_EXPORT）。
     * 由基类 _export() 统一处理文件生成与响应封装。
     *
     * @return JsonResponse 导出结果（data 为文件地址）
     */
    #[OperationLog('示例管理-导出数据', OperationLog::TYPE_EXPORT)]
    #[Permission('sys:example:export', '导出示例')]
    public function export(): JsonResponse
    {
        return $this->_export($this->exampleService);
    }

    /**
     * 导入数据
     *
     * 对应权限：sys:example:import，操作日志类型：导入（TYPE_IMPORT）。
     * 由基类 _import() 统一处理文件校验（格式/大小/MIME）与响应封装。
     *
     * @return JsonResponse 导入结果
     */
    #[OperationLog('示例管理-导入数据', OperationLog::TYPE_IMPORT, '通过Excel导入示例数据')]
    #[Permission('sys:example:import', '导入示例')]
    public function import(): JsonResponse
    {
        return $this->_import($this->exampleService);
    }
}

控制器模式

每个控制器遵循固定模式：

  1. 构造函数注入 Service（Laravel 依赖注入，protected 简写属性即成员属性）
  2. 每个方法标注 #[OperationLog] 和 #[Permission] 注解
  3. 简单调用 $this->_page() / _detail() / _add() 等快捷方法
  4. 入参由 FormRequest 类型注入完成格式校验（见 3.4 FormRequest 验证器）

Controller 基类快捷方法 ​

app/Http/Controllers/Controller.php 提供的通用方法：

方法用途内部调用失败场景
_page($service)分页查询Service::pageList()-
_list($service)全量列表Service::allList()-
_treeList($service)树形列表Service::treeList()-
_detail($service, $id)详情查询Service::detail($id)空数据返回 code=404
_add($service, $data)新增Service::add($data)捕获 BizException → fail(消息, code)
_update($service, $id, $data)修改Service::update($id, $data)id 缺失提示；捕获 BizException
_delete($service, $id)删除Service::delete($id)捕获 BizException；其他异常记日志后返回通用提示
_batchDelete($service, $ids)批量删除Service::batchDelete($ids)ids 为空提示；同上
_export($service)导出Service::export()捕获 BizException（如"无数据可导出"）
_import($service)导入Service::import()文件格式/大小/MIME 校验 + 通用提示

响应封装方法：$this->success($data, $msg) / $this->fail($msg, $code) / $this->paginate($result)（委托给 Support\\Result，见 5.16 统一响应与异常抛出）。

参数获取方法：getPageParams()（pageNo/pageSize，限 1~100）、getJsonBody()（JSON 请求体）、getParams()（query + body 合并）。

注解说明 ​

#[OperationLog] 操作日志注解 ​

php
#[OperationLog('示例管理-新增', OperationLog::TYPE_ADD, '新增示例：{name}')]
//                │                      │                  │
//                │                      │                  └── 描述模板（支持 {param} 占位符，替换为请求参数值）
//                │                      └── 操作类型常量（TYPE_QUERY/ADD/UPDATE/DELETE/IMPORT/EXPORT 等 30 种）
//                └── 操作标题

#[Permission] 权限注解 ​

php
#[Permission('sys:example:add', '添加示例')]
//               │                    │
//               │                    └── 权限名称（菜单管理中显示）
//               └── 权限编码（菜单表 permission 字段）

与手动构造响应的对比 ​

php
// ✅ 推荐：快捷方法（异常处理、日志、404 兜底全部内置）
public function page(): JsonResponse
{
    return $this->_page($this->exampleService);
}

// 特殊场景：手动组织响应
public function stats(): JsonResponse
{
    $data = $this->exampleService->stats();
    if (! $data) {
        return $this->fail('暂无统计数据', 404);
    }

    return $this->success($data);
}
`,21)])])}const g=s(n,[["render",k]]);export{y as __pageData,g as default};