用途
query-agent 是一个面向 Rails 应用的 AI 技能,核心目标是实践 Query Object(查询对象)模式。它把复杂的数据库查询逻辑从模型、控制器和视图中抽离出来,封装进独立、可复用、可测试的类,从而让代码更清晰、更易维护。该技能适用于构建报表、仪表盘、聚合查询,以及需要可组合作用域的场景。
主要能力
- 创建和修改查询对象,存放于 app/queries/ 目录。
- 编写配套的 RSpec 测试,存放于 spec/queries/ 目录。
- 优化查询,避免 N+1 问题和不必要的数据库访问,使用 includes、preload、eager_load,并考虑 Rails 8+ 的 strict_loading。
- 遵循单一职责原则(SRP),保持查询聚焦。
- 对用户输入进行清洗,使用参数化查询,防止 SQL 注入。
- 返回 ActiveRecord 关系,保持查询可链式调用。
- 可读取 app/models/、app/controllers/、app/services/ 以理解使用上下文,并可读取和修改 spec/factories/ 中的 FactoryBot 工厂。
使用方式
该技能定义了明确的工作边界:
- 始终:编写查询测试、返回 ActiveRecord 关系、使用 includes 防止 N+1。
- 先询问:在编写原生 SQL、添加复杂 join 之前。
- 绝不:在查询中修改数据、跳过边界情况测试、忽视查询性能。
可用的命令包括:
测试:
- 全部查询:bundle exec rspec spec/queries/
- 特定查询:bundle exec rspec spec/queries/entities/search_query_spec.rb
- 特定行:bundle exec rspec spec/queries/entities/search_query_spec.rb:25
- 详细格式:bundle exec rspec --format documentation spec/queries/
代码检查:
- 检查查询:bundle exec rubocop -a app/queries/
- 检查测试:bundle exec rubocop -a spec/queries/
验证:
- Rails 控制台:bin/rails console(手动测试查询)
- SQL 日志:在控制台启用 SQL 日志以验证查询
适用场景
适合使用查询对象的情况:
- 包含多个条件的复杂查询
- 在多个地方使用的查询
- 包含业务逻辑的查询
- 搜索和过滤逻辑
- 报表查询
- 需要独立测试的查询
- 需要可组合的查询
不适合使用查询对象的情况:
- 简单的一行查询(使用 scope)
- 只使用一次的查询
- 基本关联
限制
- 查询对象只封装查询逻辑,不包含业务逻辑(业务逻辑应放在 service 中)。
- 不要创建没有测试的查询。
- 不要在 SQL 中使用字符串插值。
- 不要返回数组(应返回关系以支持链式调用)。
- 不要创建无法测试的查询。
- 不要创建“上帝查询对象”。
- 涉及原生 SQL、复杂子查询或修改 ApplicationQuery 时需先确认。
技术栈与架构
技术栈:Ruby 3.3、Rails 8.1、PostgreSQL、RSpec、FactoryBot。
架构约定:
- app/queries/ – 查询对象(创建和修改)
- app/models/ – ActiveRecord 模型(读取)
- app/controllers/ – 控制器(读取以理解用法)
- app/services/ – 业务服务(读取)
- spec/queries/ – 查询测试(创建和修改)
- spec/factories/ – FactoryBot 工厂(读取和修改)
参考资料
- patterns.md – ApplicationQuery 基类和 7 种查询对象实现(搜索、报表、join、全文检索、地理位置、分页)
- testing.md – 查询对象的 RSpec 测试,包括 N+1 预防测试和优化技巧
其他资源:Active Record Query Interface、Rails SQL Injection Guide、Bullet Gem(检测 N+1 查询)、Query Objects Pattern。