用途:为 UnoPim 扩展或修改 REST API v1(AdminApi)端点,路径位于 /api/v1/rest。该 API 由 packages/Webkul/AdminApi 提供,使用 Passport 密码授权令牌、api-acl 权限树,以及负责分页、过滤与响应封装的列表引擎 ApiDataSource;它不是 Laravel routes/api.php + apiResource + JsonResource::collection 的写法,动笔前应先参照已有端点结构。
主要能力与用法:先判断端点是否已存在(git grep -n "admin.api.<entity>" -- packages,并阅读所属包的全部 Routes/ 文件)。核心实体路由放在 admin-api.php 引入的 V1/*-routes.php;插件实体用插件自身 Routes/api.php,在 Route::prefix('api')->middleware('api') 下加载,中间件栈从 admin-api.php 拷贝,插件不得改 AdminApi。路由命名 admin.api.{entity}.{index|get|store|update|patch|delete},用 get 而非 show。同一变更中必须添加 api-acl 条目(该 ACL 为 fail-closed)。列表用 ApiDataSource 子类,不要手写 paginate/count/数据包装;写入用继承 ApiFormRequest 的 FormRequest、仓库调用,并触发与后台控制器相同的 Event::dispatch('….before'/'….after'),以保证历史、webhook、索引监听生效;响应使用 ApiResponse 辅助方法(successResponse、modelNotFoundResponse、validateErrorResponse、storeExceptionLog)配合 trans() 消息。测试用 ApiHelperTrait 请求头,并覆盖权限拒绝路径。
限制与陷阱:未映射路由对所有密钥返回 403;拆分权限会剥夺已有密钥的访问,需要数据迁移回填。limit 被限制在 1–100,sort 固定为 $sortColumn,search_after 需要单调递增的数值 $primaryColumn,联表后需加表限定(products.id)。旧式 =/IN/NOT IN 过滤以 orWhere 组合,>/</BETWEEN 以 AND 组合;datetime 过滤需在 addFilter() 传 'datetime' 类型。$structureCacheGroup 仅用于变化缓慢的结构数据并须接好失效逻辑,禁止用于商品或无法失效的插件数据。DataSource 有状态,须用 app(XDataSource::class) 每次解析,不能绑定为单例。Elasticsearch 不在此路径上,商品列表走数据库查询。此外需先阅读 unopim-standards、unopim-exec、unopim-verify;插件脚手架参考 unopim-plugin-development;验证时用 vendor/bin/pest packages/Webkul/AdminApi/tests 及所属包测试,在 MySQL 与 PostgreSQL 上运行。