419 lines
14 KiB
Markdown
419 lines
14 KiB
Markdown
|
---
|
||
|
|
name: backend-gen-controller
|
||
|
|
description: Generate CRUD controller for madong module. Supports both app (main project) and plugin targets. Creates controller extending Crud base class with OpenAPI attributes and standard REST endpoints.
|
||
|
|
globs:
|
||
|
|
- "app/**/controller/**/*.php"
|
||
|
|
- "plugin/**/app/**/controller/**/*.php"
|
||
|
|
---
|
||
|
|
|
||
|
|
# Step 4: Generate Admin Controller
|
||
|
|
|
||
|
|
Create CRUD controller for module.
|
||
|
|
|
||
|
|
## File Location
|
||
|
|
|
||
|
|
**App (主项目):**
|
||
|
|
```
|
||
|
|
app/adminapi/controller/{module}/{Model}Controller.php
|
||
|
|
```
|
||
|
|
|
||
|
|
**Plugin (插件):**
|
||
|
|
```
|
||
|
|
plugin/{plugin}/app/adminapi/controller/{module}/{Model}Controller.php
|
||
|
|
```
|
||
|
|
|
||
|
|
## Target Variables
|
||
|
|
|
||
|
|
| 变量 | App | Plugin |
|
||
|
|
|------|-----|--------|
|
||
|
|
| `{prefix}` | `` (空) | `plugin\{Plugin}` |
|
||
|
|
| `{ns}` | `app` | `plugin\{Plugin}\app` |
|
||
|
|
| `{service_ns}` | `app\service\admin` | `plugin\{Plugin}\app\service\admin` |
|
||
|
|
|
||
|
|
## Controller Template
|
||
|
|
|
||
|
|
```php
|
||
|
|
<?php
|
||
|
|
|
||
|
|
declare(strict_types=1);
|
||
|
|
/**
|
||
|
|
*+------------------
|
||
|
|
* madong
|
||
|
|
*+------------------
|
||
|
|
* Copyright (c) https://gitee.com/motion-code All rights reserved.
|
||
|
|
*+------------------
|
||
|
|
* Author: Mr. April (405784684@qq.com)
|
||
|
|
*+------------------
|
||
|
|
*/
|
||
|
|
|
||
|
|
namespace {ns}\adminapi\controller\{module};
|
||
|
|
|
||
|
|
use app\adminapi\controller\Crud;
|
||
|
|
use app\adminapi\middleware\AccessTokenMiddleware;
|
||
|
|
use app\adminapi\middleware\OperationMiddleware;
|
||
|
|
use app\adminapi\middleware\PermissionMiddleware;
|
||
|
|
use {service_ns}\{module}\{Model}Service;
|
||
|
|
use core\tool\Json;
|
||
|
|
use madong\swagger\attribute\Permission;
|
||
|
|
use madong\swagger\annotation\response\SimpleResponse;
|
||
|
|
use OpenApi\Attributes as OA;
|
||
|
|
use support\annotation\Middleware;
|
||
|
|
use support\Request;
|
||
|
|
use WebmanTech\Swagger\DTO\SchemaConstants;
|
||
|
|
|
||
|
|
#[Middleware(AccessTokenMiddleware::class, PermissionMiddleware::class, OperationMiddleware::class)]
|
||
|
|
final class {Model}Controller extends Crud
|
||
|
|
{
|
||
|
|
|
||
|
|
public function __construct({Model}Service $service)
|
||
|
|
{
|
||
|
|
$this->service = $service;
|
||
|
|
}
|
||
|
|
|
||
|
|
#[OA\Get(
|
||
|
|
path: '/{module}/{model}',
|
||
|
|
summary: '列表',
|
||
|
|
tags: ['{Module}-{Model}'],
|
||
|
|
parameters: [
|
||
|
|
new OA\Parameter(name: "page", description: "页码", in: "query", schema: new OA\Schema(type: "integer")),
|
||
|
|
new OA\Parameter(name: "limit", description: "每页数量", in: "query", schema: new OA\Schema(type: "integer")),
|
||
|
|
],
|
||
|
|
responses: [
|
||
|
|
new OA\Response(
|
||
|
|
response: 200,
|
||
|
|
description: "成功",
|
||
|
|
content: new OA\JsonContent(properties: [
|
||
|
|
new OA\Property(property: "code", type: "integer", example: 0),
|
||
|
|
new OA\Property(property: "msg", type: "string", example: "获取成功"),
|
||
|
|
new OA\Property(property: "data", properties: [
|
||
|
|
new OA\Property(property: "total", type: "integer", example: 10),
|
||
|
|
new OA\Property(property: "list", type: "array", items: new OA\Items()),
|
||
|
|
], type: "object"),
|
||
|
|
])
|
||
|
|
),
|
||
|
|
]
|
||
|
|
)]
|
||
|
|
#[Permission("{module}:{model}:list")]
|
||
|
|
public function index(Request $request): \support\Response
|
||
|
|
{
|
||
|
|
try {
|
||
|
|
[$where, $format, $limit, $field, $order, $page] = $this->selectInput($request);
|
||
|
|
$methods = [
|
||
|
|
'select' => 'formatSelect',
|
||
|
|
'tree' => 'formatTree',
|
||
|
|
'table_tree' => 'formatTableTree',
|
||
|
|
'normal' => 'formatNormal',
|
||
|
|
];
|
||
|
|
$format_function = $methods[$format] ?? 'formatNormal';
|
||
|
|
$total = $this->service->getCount($where);
|
||
|
|
$list = $this->service->selectList($where, $field, $page, $limit, $order, [], false);
|
||
|
|
return call_user_func([$this, $format_function], $list, $total);
|
||
|
|
} catch (\Throwable $e) {
|
||
|
|
return Json::fail($e->getMessage());
|
||
|
|
}
|
||
|
|
}
|
||
|
|
|
||
|
|
#[OA\Get(
|
||
|
|
path: '/{module}/{model}/{id}',
|
||
|
|
summary: '详情',
|
||
|
|
tags: ['{Module}-{Model}'],
|
||
|
|
responses: [
|
||
|
|
new OA\Response(
|
||
|
|
response: 200,
|
||
|
|
description: "成功",
|
||
|
|
content: new OA\JsonContent(properties: [
|
||
|
|
new OA\Property(property: "code", type: "integer", example: 0),
|
||
|
|
new OA\Property(property: "msg", type: "string", example: "获取成功"),
|
||
|
|
])
|
||
|
|
),
|
||
|
|
],
|
||
|
|
x: [
|
||
|
|
SchemaConstants::X_PROPERTY_IN => 'id',
|
||
|
|
]
|
||
|
|
)]
|
||
|
|
#[Permission("{module}:{model}:read")]
|
||
|
|
public function show(Request $request): \support\Response
|
||
|
|
{
|
||
|
|
return parent::show($request);
|
||
|
|
}
|
||
|
|
|
||
|
|
#[OA\Post(
|
||
|
|
path: '/{module}/{model}',
|
||
|
|
summary: '创建',
|
||
|
|
tags: ['{Module}-{Model}'],
|
||
|
|
responses: [
|
||
|
|
new OA\Response(
|
||
|
|
response: 200,
|
||
|
|
description: "成功",
|
||
|
|
content: new OA\JsonContent(properties: [
|
||
|
|
new OA\Property(property: "code", type: "integer", example: 0),
|
||
|
|
new OA\Property(property: "msg", type: "string", example: "创建成功"),
|
||
|
|
])
|
||
|
|
),
|
||
|
|
],
|
||
|
|
)]
|
||
|
|
#[Permission("{module}:{model}:create")]
|
||
|
|
#[SimpleResponse(example: '{"code":0,"msg":"created","id":1}')]
|
||
|
|
public function store(Request $request): \support\Response
|
||
|
|
{
|
||
|
|
return parent::store($request);
|
||
|
|
}
|
||
|
|
|
||
|
|
#[OA\Put(
|
||
|
|
path: '/{module}/{model}/{id}',
|
||
|
|
summary: '更新',
|
||
|
|
tags: ['{Module}-{Model}'],
|
||
|
|
parameters: [
|
||
|
|
new OA\Parameter(name: "id", description: "ID", in: "path", required: true, schema: new OA\Schema(type: "integer")),
|
||
|
|
],
|
||
|
|
responses: [
|
||
|
|
new OA\Response(
|
||
|
|
response: 200,
|
||
|
|
description: "成功",
|
||
|
|
content: new OA\JsonContent(properties: [
|
||
|
|
new OA\Property(property: "code", type: "integer", example: 0),
|
||
|
|
new OA\Property(property: "msg", type: "string", example: "更新成功"),
|
||
|
|
])
|
||
|
|
),
|
||
|
|
]
|
||
|
|
)]
|
||
|
|
#[Permission("{module}:{model}:update")]
|
||
|
|
public function update(Request $request): \support\Response
|
||
|
|
{
|
||
|
|
return parent::update($request);
|
||
|
|
}
|
||
|
|
|
||
|
|
#[OA\Post(
|
||
|
|
path: '/{module}/{model}/export',
|
||
|
|
summary: '导出',
|
||
|
|
tags: ['{Module}-{Model}']
|
||
|
|
)]
|
||
|
|
#[Permission("{module}:{model}:list")]
|
||
|
|
#[SimpleResponse(example: ['code' => 0, 'message' => 'success', 'data' => []])]
|
||
|
|
public function export(Request $request): \support\Response
|
||
|
|
{
|
||
|
|
return parent::export($request);
|
||
|
|
}
|
||
|
|
|
||
|
|
#[OA\Delete(
|
||
|
|
path: '/{module}/{model}/{id}',
|
||
|
|
summary: '删除',
|
||
|
|
tags: ['{Module}-{Model}'],
|
||
|
|
parameters: [
|
||
|
|
new OA\Parameter(name: "id", description: "ID", in: "path", required: true, schema: new OA\Schema(type: "integer")),
|
||
|
|
],
|
||
|
|
responses: [
|
||
|
|
new OA\Response(
|
||
|
|
response: 200,
|
||
|
|
description: "成功",
|
||
|
|
content: new OA\JsonContent(properties: [
|
||
|
|
new OA\Property(property: "code", type: "integer", example: 0),
|
||
|
|
new OA\Property(property: "msg", type: "string", example: "删除成功"),
|
||
|
|
])
|
||
|
|
),
|
||
|
|
],
|
||
|
|
x: [
|
||
|
|
SchemaConstants::X_PROPERTY_IN => 'id',
|
||
|
|
]
|
||
|
|
)]
|
||
|
|
#[Permission("{module}:{model}:delete")]
|
||
|
|
public function destroy(Request $request): \support\Response
|
||
|
|
{
|
||
|
|
return parent::destroy($request);
|
||
|
|
}
|
||
|
|
|
||
|
|
#[OA\Delete(
|
||
|
|
path: '/{module}/{model}',
|
||
|
|
summary: '批量删除',
|
||
|
|
tags: ['{Module}-{Model}'],
|
||
|
|
x: [SchemaConstants::X_SCHEMA_REQUEST => \app\schema\request\BatchDeleteRequest::class],
|
||
|
|
)]
|
||
|
|
#[Permission("{module}:{model}:delete")]
|
||
|
|
public function batchDelete(Request $request): \support\Response
|
||
|
|
{
|
||
|
|
return parent::destroy($request);
|
||
|
|
}
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
## Complete Example (App)
|
||
|
|
|
||
|
|
```php
|
||
|
|
<?php
|
||
|
|
|
||
|
|
declare(strict_types=1);
|
||
|
|
/**
|
||
|
|
*+------------------
|
||
|
|
* madong
|
||
|
|
*+------------------
|
||
|
|
* Copyright (c) https://gitee.com/motion-code All rights reserved.
|
||
|
|
*+------------------
|
||
|
|
* Author: Mr. April (405784684@qq.com)
|
||
|
|
*+------------------
|
||
|
|
*/
|
||
|
|
|
||
|
|
namespace app\adminapi\controller\member;
|
||
|
|
|
||
|
|
use app\adminapi\controller\Crud;
|
||
|
|
use app\adminapi\middleware\AccessTokenMiddleware;
|
||
|
|
use app\adminapi\middleware\OperationMiddleware;
|
||
|
|
use app\adminapi\middleware\PermissionMiddleware;
|
||
|
|
use app\service\admin\member\MemberService;
|
||
|
|
use core\tool\Json;
|
||
|
|
use madong\swagger\attribute\Permission;
|
||
|
|
use madong\swagger\annotation\response\SimpleResponse;
|
||
|
|
use OpenApi\Attributes as OA;
|
||
|
|
use support\annotation\Middleware;
|
||
|
|
use support\Request;
|
||
|
|
use WebmanTech\Swagger\DTO\SchemaConstants;
|
||
|
|
|
||
|
|
#[Middleware(AccessTokenMiddleware::class, PermissionMiddleware::class, OperationMiddleware::class)]
|
||
|
|
final class MemberController extends Crud
|
||
|
|
{
|
||
|
|
|
||
|
|
public function __construct(MemberService $service)
|
||
|
|
{
|
||
|
|
$this->service = $service;
|
||
|
|
}
|
||
|
|
|
||
|
|
#[OA\Get(
|
||
|
|
path: '/member/user',
|
||
|
|
summary: '会员用户列表',
|
||
|
|
tags: ['会员用户'],
|
||
|
|
parameters: [
|
||
|
|
new OA\Parameter(name: "username", description: "用户名", in: "query", schema: new OA\Schema(type: "string")),
|
||
|
|
new OA\Parameter(name: "nickname", description: "昵称", in: "query", schema: new OA\Schema(type: "string")),
|
||
|
|
new OA\Parameter(name: "page", description: "页码", in: "query", schema: new OA\Schema(type: "integer")),
|
||
|
|
new OA\Parameter(name: "limit", description: "每页数量", in: "query", schema: new OA\Schema(type: "integer")),
|
||
|
|
],
|
||
|
|
responses: [
|
||
|
|
new OA\Response(
|
||
|
|
response: 200,
|
||
|
|
description: "成功",
|
||
|
|
content: new OA\JsonContent(properties: [
|
||
|
|
new OA\Property(property: "code", type: "integer", example: 0),
|
||
|
|
new OA\Property(property: "msg", type: "string", example: "获取成功"),
|
||
|
|
])
|
||
|
|
),
|
||
|
|
]
|
||
|
|
)]
|
||
|
|
#[Permission("member:user:list")]
|
||
|
|
public function index(Request $request): \support\Response
|
||
|
|
{
|
||
|
|
try {
|
||
|
|
[$where, $format, $limit, $field, $order, $page] = $this->selectInput($request);
|
||
|
|
$methods = [
|
||
|
|
'select' => 'formatSelect',
|
||
|
|
'tree' => 'formatTree',
|
||
|
|
'table_tree' => 'formatTableTree',
|
||
|
|
'normal' => 'formatNormal',
|
||
|
|
];
|
||
|
|
$format_function = $methods[$format] ?? 'formatNormal';
|
||
|
|
$total = $this->service->getCount($where);
|
||
|
|
$list = $this->service->selectList($where, $field, $page, $limit, $order, ['level', 'tags'], false);
|
||
|
|
return call_user_func([$this, $format_function], $list, $total);
|
||
|
|
} catch (\Throwable $e) {
|
||
|
|
return Json::fail($e->getMessage());
|
||
|
|
}
|
||
|
|
}
|
||
|
|
|
||
|
|
#[OA\Get(
|
||
|
|
path: '/member/user/{id}',
|
||
|
|
summary: '会员用户详情',
|
||
|
|
tags: ['会员用户'],
|
||
|
|
responses: [
|
||
|
|
new OA\Response(response: 200, description: "成功"),
|
||
|
|
],
|
||
|
|
x: [SchemaConstants::X_PROPERTY_IN => 'id']
|
||
|
|
)]
|
||
|
|
#[Permission("member:user:read")]
|
||
|
|
public function show(Request $request): \support\Response
|
||
|
|
{
|
||
|
|
return parent::show($request);
|
||
|
|
}
|
||
|
|
|
||
|
|
#[OA\Post(path: '/member/user', summary: '创建', tags: ['会员用户'])]
|
||
|
|
#[Permission("member:user:create")]
|
||
|
|
#[SimpleResponse(example: '{"code":0,"msg":"created","id":1}')]
|
||
|
|
public function store(Request $request): \support\Response
|
||
|
|
{
|
||
|
|
return parent::store($request);
|
||
|
|
}
|
||
|
|
|
||
|
|
#[OA\Put(path: '/member/user/{id}', summary: '更新', tags: ['会员用户'])]
|
||
|
|
#[Permission("member:user:update")]
|
||
|
|
public function update(Request $request): \support\Response
|
||
|
|
{
|
||
|
|
return parent::update($request);
|
||
|
|
}
|
||
|
|
|
||
|
|
#[OA\Delete(path: '/member/user/{id}', summary: '删除', tags: ['会员用户'])]
|
||
|
|
#[Permission("member:user:delete")]
|
||
|
|
public function destroy(Request $request): \support\Response
|
||
|
|
{
|
||
|
|
return parent::destroy($request);
|
||
|
|
}
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
## API Path Convention
|
||
|
|
|
||
|
|
| Method | Path | Description |
|
||
|
|
|--------|------|-------------|
|
||
|
|
| GET | `/{module}/{model}` | List with pagination |
|
||
|
|
| GET | `/{module}/{model}/{id}` | Get single record |
|
||
|
|
| POST | `/{module}/{model}` | Create new record |
|
||
|
|
| POST | `/{module}/{model}/export` | Export records |
|
||
|
|
| PUT | `/{module}/{model}/{id}` | Update record |
|
||
|
|
| DELETE | `/{module}/{model}/{id}` | Delete single record |
|
||
|
|
| DELETE | `/{module}/{model}` | Batch delete records |
|
||
|
|
|
||
|
|
## Permission Codes
|
||
|
|
|
||
|
|
| Action | Permission | Description |
|
||
|
|
|--------|------------|-------------|
|
||
|
|
| List | `{module}:{model}:list` | View list |
|
||
|
|
| Export | `{module}:{model}:list` | Export records |
|
||
|
|
| View | `{module}:{model}:read` | View detail |
|
||
|
|
| Create | `{module}:{model}:create` | Create new |
|
||
|
|
| Update | `{module}:{model}:update` | Update existing |
|
||
|
|
| Delete | `{module}:{model}:delete` | Delete records |
|
||
|
|
|
||
|
|
## Middleware Stack
|
||
|
|
|
||
|
|
The controller uses three middleware:
|
||
|
|
|
||
|
|
1. **AccessTokenMiddleware**: Authentication
|
||
|
|
2. **PermissionMiddleware**: Permission check
|
||
|
|
3. **OperationMiddleware**: Operation logging
|
||
|
|
|
||
|
|
## Inherited Crud Methods
|
||
|
|
|
||
|
|
The Crud base controller provides:
|
||
|
|
|
||
|
|
| Method | Description |
|
||
|
|
|--------|-------------|
|
||
|
|
| `index()` | List with pagination |
|
||
|
|
| `export()` | Export records |
|
||
|
|
| `show()` | Get single record |
|
||
|
|
| `store()` | Create record |
|
||
|
|
| `update()` | Update record |
|
||
|
|
| `destroy()` | Delete record (single and batch) |
|
||
|
|
| `selectInput()` | Parse request parameters |
|
||
|
|
| `formatSelect()` | Format for select dropdown |
|
||
|
|
| `formatTree()` | Format for tree structure |
|
||
|
|
| `formatTableTree()` | Format for table tree |
|
||
|
|
| `formatNormal()` | Format for normal list |
|
||
|
|
|
||
|
|
## Auto-generation Checklist
|
||
|
|
|
||
|
|
When generating controller:
|
||
|
|
- [ ] Set correct namespace based on target
|
||
|
|
- [ ] Import required classes (Controller, Service, Middleware, Json, etc.)
|
||
|
|
- [ ] Add Middleware attribute with three middlewares
|
||
|
|
- [ ] Extend Crud base controller
|
||
|
|
- [ ] Inject Service in constructor
|
||
|
|
- [ ] Add OpenAPI attributes for each action
|
||
|
|
- [ ] Add Permission attribute for each action
|
||
|
|
- [ ] Use proper API path convention
|