mcpField
A
api-platform-filters

api-platform-filters

github.com/dev-toolings开发22781 次安装3 周前更新
代码仓库

关于 api-platform-filters

用于配置 API Platform 集合筛选器的 Symfony 开发技能，涵盖内置和自定义查询筛选、迁移到 Parameters API，以及验证与索引实践。

主要功能

  1. 01基于 QueryParameter 配置筛选器
  2. 02按版本选择内置筛选器
  3. 03实现自定义 FilterInterface 逻辑
  4. 04启用严格查询参数验证
  5. 05提供筛选索引与测试指导

适用场景

  1. 01为端点添加搜索和范围参数
  2. 02用一个参数搜索多个属性
  3. 03迁移已弃用的 ApiFilter 声明

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/dev-toolings/superpowers-symfony --skill api-platform-filters

安装后在 Claude Code 中输入/api-platform-filters确认已加载。

附带文件reference.md

详细介绍

Api Platform 过滤器（Symfony）

适用场景

  • 集合端点需要搜索、精确匹配、范围、日期、布尔值或排序查询参数。
  • 一个查询参数需要搜索多个属性。
  • 过滤器需要内置过滤器无法覆盖的自定义查询逻辑。
  • 手动将 #[ApiFilter] 声明（自 4.4 起已弃用）迁移到 Parameters API，或使用 api:upgrade-filter 迁移。

默认工作流

  1. 在操作上使用 QueryParameter 声明 parameters；仅在 3.4 代码或尚未迁移的代码中保留 #[ApiFilter]。
  2. 为每个参数选择一个过滤器类，并检查已安装的版本：ExactFilter、PartialSearchFilter、FreeTextQueryFilter、OrFilter、IriFilter（4.2+）、ComparisonFilter、SortFilter（4.3+）、StartSearchFilter、EndSearchFilter、ChainFilter（4.4+）。
  3. 对于自定义过滤器，实现 FilterInterface 并从 $context['parameter'] 读取绑定值（AbstractFilter 和 filterProperty() 自 4.4 起已弃用：在 4.3 和 3.4 代码中保留它们）。
  4. 启用 strictQueryParameterValidation，使未知查询参数返回 400。
  5. 在经过过滤的列上添加 #[ORM\Index]，然后使用匹配和不匹配的值请求端点。

防护措施

  • 保持过滤器类无状态：从 $context 获取请求数据，而不是从构造函数获取。
  • 仅公开客户端需要用于过滤的属性。
  • 对 ID 和外键使用精确匹配：部分匹配 LIKE %value% 无法使用索引。
  • 在自定义过滤器中验证值，并使用 generateParameterName() 和 setParameter() 绑定值，绝不要通过字符串拼接来绑定。

渐进式展开

  • 使用此文件了解执行方式和风险控制。
  • 需要深入了解实现细节时，打开参考资料。

输出约定

  • 每个操作的参数，包括过滤器类和接受的语法（例如 ?price[gte]=1000）。
  • 为经过过滤的列添加的索引。
  • 针对匹配结果、空结果和未知参数的测试。

参考资料

  • reference.md

评论

支持 Markdown