157 lines
4.9 KiB
Markdown
157 lines
4.9 KiB
Markdown
# API Scaffold — 代码模板与异常体系
|
||
|
||
> 主流程见 SKILL.md，本文档为 Controller/Service/FormRequest/路由 的完整代码模板。
|
||
|
||
## Hyperf 分层目录约定
|
||
|
||
| 文件 | 路径 |
|
||
|------|------|
|
||
| Controller | `app/Controller/Admin/<Resource>Controller.php` |
|
||
| Service | `app/Service/<Module>/<Resource>Service.php` |
|
||
| FormRequest | `app/Request/<Module>/Create<Resource>Request.php` |
|
||
| Model | `app/Model/<Module>/<Resource>.php`（如不存在） |
|
||
| Route | `app/Http/Admin/Router/<resource>.php` |
|
||
|
||
## Controller 模板
|
||
|
||
```php
|
||
<?php
|
||
declare(strict_types=1);
|
||
namespace App\Controller\Admin;
|
||
|
||
use App\Request\{{Module}}\Create{{Resource}}Request;
|
||
use App\Service\{{Module}}\{{Resource}}Service;
|
||
use Hyperf\Di\Annotation\Inject;
|
||
|
||
#[Controller(prefix: '/admin/{{route-path}}')]
|
||
class {{Resource}}Controller extends AbstractController
|
||
{
|
||
#[Inject]
|
||
protected {{Resource}}Service $service;
|
||
|
||
#[RequestMapping(path: '', methods: ['GET'])]
|
||
public function list(RequestInterface $request): ResponseInterface {
|
||
$params = $request->all();
|
||
$result = $this->service->getPageList($params);
|
||
return $this->success($result);
|
||
}
|
||
|
||
#[RequestMapping(path: '{id:\d+}', methods: ['GET'])]
|
||
public function detail(int $id): ResponseInterface {
|
||
$result = $this->service->getById($id);
|
||
return $this->success($result);
|
||
}
|
||
|
||
#[RequestMapping(path: '', methods: ['POST'])]
|
||
public function create(Create{{Resource}}Request $request): ResponseInterface {
|
||
$data = $request->validated();
|
||
$result = $this->service->create($data);
|
||
return $this->success($result, 201);
|
||
}
|
||
|
||
#[RequestMapping(path: '{id:\d+}', methods: ['PUT'])]
|
||
public function update(int $id, Create{{Resource}}Request $request): ResponseInterface {
|
||
$data = $request->validated();
|
||
$result = $this->service->update($id, $data);
|
||
return $this->success($result);
|
||
}
|
||
|
||
#[RequestMapping(path: '{id:\d+}', methods: ['DELETE'])]
|
||
public function delete(int $id): ResponseInterface {
|
||
$this->service->delete($id);
|
||
return $this->success(null, message: 'Deleted');
|
||
}
|
||
}
|
||
```
|
||
|
||
## Service 模板
|
||
|
||
```php
|
||
<?php
|
||
namespace App\Service\{{Module}};
|
||
|
||
use App\Model\{{Module}}\{{Resource}};
|
||
use App\Exception\BusinessException;
|
||
use Hyperf\DbConnection\Db;
|
||
|
||
class {{Resource}}Service
|
||
{
|
||
public function getPageList(array $params): array {
|
||
$query = {{Resource}}::query();
|
||
if (!empty($params['status'])) $query->where('status', $params['status']);
|
||
$page = (int) ($params['page'] ?? 1);
|
||
$pageSize = (int) ($params['page_size'] ?? 10);
|
||
$total = $query->count();
|
||
$items = $query->orderByDesc('id')->offset(($page - 1) * $pageSize)->limit($pageSize)->get();
|
||
return ['items' => $items, 'total' => $total];
|
||
}
|
||
|
||
public function getById(int $id): {{Resource}} {
|
||
$record = {{Resource}}::find($id);
|
||
if (!$record) throw new BusinessException(404, '{{Resource}} not found');
|
||
return $record;
|
||
}
|
||
|
||
public function create(array $data): {{Resource}} {
|
||
return Db::transaction(fn () => {{Resource}}::create($data));
|
||
}
|
||
|
||
public function update(int $id, array $data): {{Resource}} {
|
||
$record = $this->getById($id);
|
||
return Db::transaction(function () use ($record, $data) {
|
||
$record->update($data);
|
||
return $record->refresh();
|
||
});
|
||
}
|
||
|
||
public function delete(int $id): void {
|
||
$record = $this->getById($id);
|
||
$record->delete();
|
||
}
|
||
}
|
||
```
|
||
|
||
## FormRequest 模板
|
||
|
||
```php
|
||
<?php
|
||
namespace App\Request\{{Module}};
|
||
|
||
use Hyperf\Validation\Request\FormRequest;
|
||
|
||
class Create{{Resource}}Request extends FormRequest
|
||
{
|
||
public function authorize(): bool { return true; }
|
||
public function rules(): array {
|
||
return [ /* Define validation rules based on resource fields */ ];
|
||
}
|
||
}
|
||
```
|
||
|
||
## 路由注册
|
||
|
||
```php
|
||
// app/Http/Admin/Router/{{resource}}.php
|
||
use App\Controller\Admin\{{Resource}}Controller;
|
||
use Hyperf\HttpServer\Router\Router;
|
||
|
||
Router::addGroup('/admin/{{route-path}}', function () {
|
||
Router::get('', [{{Resource}}Controller::class, 'list']);
|
||
Router::get('/{id:\d+}', [{{Resource}}Controller::class, 'detail']);
|
||
Router::post('', [{{Resource}}Controller::class, 'create']);
|
||
Router::put('/{id:\d+}', [{{Resource}}Controller::class, 'update']);
|
||
Router::delete('/{id:\d+}', [{{Resource}}Controller::class, 'delete']);
|
||
}, ['middleware' => [AccessTokenMiddleware::class, PermissionMiddleware::class]]);
|
||
```
|
||
|
||
## 统一响应格式
|
||
|
||
```php
|
||
protected function success(mixed $data = null, int $code = 200, string $message = 'ok'): ResponseInterface {
|
||
return $this->response->json(['code' => $code, 'message' => $message, 'data' => $data]);
|
||
}
|
||
protected function error(string $message, int $code = 500, mixed $data = null): ResponseInterface {
|
||
return $this->response->json(['code' => $code, 'message' => $message, 'data' => $data]);
|
||
}
|
||
```
|