281 lines
10 KiB
Markdown
281 lines
10 KiB
Markdown
# 3.6 控制器开发
|
||
|
||
:::tip 概述
|
||
控制器是 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);
|
||
}
|
||
}
|
||
```
|
||
|
||
:::tip 控制器模式
|
||
每个控制器遵循固定模式：
|
||
|
||
1. **构造函数注入 Service**（Laravel 依赖注入，`protected` 简写属性即成员属性）
|
||
2. 每个方法标注 `#[OperationLog]` 和 `#[Permission]` 注解
|
||
3. 简单调用 `$this->_page()` / `_detail()` / `_add()` 等快捷方法
|
||
4. 入参由 FormRequest 类型注入完成格式校验（见 [3.4 FormRequest 验证器](/zh/guide/validator.html)）
|
||
:::
|
||
|
||
## 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 统一响应与异常抛出](/zh/core/exception.html)）。
|
||
|
||
参数获取方法：`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 种）
|
||
// └── 操作标题
|
||
```
|
||
|
||
- 由 `log.operation` 中间件采集，响应后（terminable 阶段）落库；
|
||
- 写操作（POST/PUT/DELETE）始终记录，读操作按注解类型选择性记录。
|
||
|
||
### #[Permission] 权限注解
|
||
|
||
```php
|
||
#[Permission('sys:example:add', '添加示例')]
|
||
// │ │
|
||
// │ └── 权限名称（菜单管理中显示）
|
||
// └── 权限编码（菜单表 permission 字段）
|
||
```
|
||
|
||
- 由 `auth.jwt` 中间件反射校验：解析注解 → 比对当前用户权限列表 → 无权限返回 `code=403`；
|
||
- 超级管理员（用户 ID=1）直接放行；
|
||
- 未标注 `#[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);
|
||
}
|
||
```
|