# 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]);
}
```