Controller

Controller 只调 Service：收参、校验、组响应。校验规则写在控制器的私有方法里；$this->validate() 的返回值就是写库白名单，禁止把原始请求体直接交给 Service。

依赖注入与权限注解

每个需要鉴权的方法必须标 #[Permission('x.y.z')]；公开或仅登录即可的方法标 #[PermissionSkip]。两者都没有时，AdminPermissionMiddleware 默认 403。

依赖用 #[\DI\Attribute\Inject] 注入 Service：

use core\permission\Permission;
use core\permission\PermissionSkip;
use DI\Attribute\Inject;

class RoleController extends Controller
{
    #[Inject]
    protected RoleService $roleService;

    #[Permission('system.role.create')]
    public function store(Request $request): Response
    {
        $data = $this->validate($this->body($request), $this->storeRules(), $this->messages());

        $result = $this->roleService->createRole($data);

        return $this->success($result, lang('messages.create_success'));
    }

    #[PermissionSkip]
    public function options(): Response
    {
        return $this->success($this->roleService->getAllRoleOptions(), lang('messages.get_success'));
    }

    /** @return array<string, string> */
    private function storeRules(): array
    {
        return [
            'name'  => 'required|string|min:2|max:50|alpha_dash:ascii',
            'title' => 'required|string|min:2|max:100',
            // …
        ];
    }
}

上例来自 app\adminapi\controller\system\RoleController。

校验与白名单

• 规则放在 storeRules() / updateRules() 等私有方法（或统一的 rules($scene)）。
• $this->validate($data, $rules, $messages) 校验通过后只返回规则里出现过的字段；写库只用这份返回值。
• $this->body($request) 只作校验输入，不要透传给 Service。

分页入参

列表接口用基类 $this->pageParams($request)，读取 page / limit（兼容 page_no / page_size），再交给 Service。