在 api platform 中为自定义操作（如 `/cards/random`）禁用默认 `readlistener` 时，必须将该操作声明在内置 `get` 操作之前，否则框架仍会尝试执行读取逻辑并返回 404 错误。
API Platform 的 ReadListener 会在请求生命周期中根据操作类型自动触发读取逻辑（例如通过 ID 加载实体）。当你定义一个非标准的 itemOperation（如 random），即使显式设置了 "read" => false，如果该操作位于内置 'get' 之后，API Platform 仍可能因路由匹配或操作解析顺序问题，错误地将其识别为需执行读取的 item 操作，从而调用 ReadListener 并因无法解析 {id} 而抛出 Not Found（404）。
根本原因在于：API Platform 对 itemOperations 的处理存在隐式优先级——当路径形如 /cards/random 且未包含 {id} 占位符时，若 random 操作排在 'get' 之后，框架可能跳过对该自定义操作的精确匹配，转而尝试按 get 的规则（要求 id 参数）进行解析，最终失败。
✅ 正确做法是：将自定义操作声明在所有依赖 ID 的内置操作（如 'get', 'put', 'delete'）之前，确保其路由和配置被优先识别：
#[ApiResource(
itemOperations: [
// ✅ 自定义操作必须置于 'get' 之前
'random' => [
'method' => 'GET',
'path' => '/cards/random',
'controller' => CardRandomController::class,
'read' => false, // 明确禁用 ReadListener
'openapi_context' => [
'summary' => 'Get a random card',
'parameters' => [], // 注意：此处不应声明 "id" 参数，因路径无 {id}
],
],
'get', // ⚠️ 必须放在 custom operation 之后
'put',
'patch',
'delete',
],
denormalizationContext: ['groups' => 'card:write'],
normalizationContext: ['groups' => 'card:read'],
)]
class Card
{
// ...
}⚠️ 同时注意以下关键细节：
- openapi_context['parameters'] 中不应包含 "id" 字段（除非路径含 {id}），否则 OpenAPI 文档会错误提示必需参数；
- 清除缓存（bin/console cache:clear）是必要步骤，但顺序问题无法通过清缓存解决；
- 控制器返回值需与 normalizationContext 兼容（本例中 Card 实体需支持 card:read 序列化组）；
- 若后续需支持集合级随机操作，应使用 collectionOperations 而非 itemOperations。
总结："read" => false 本身有效，但其生效前提是 API Platform 能正确识别并路由到该自定义操作——而操作声明顺序，正是决定这一识别是否成功的隐式契约。
