SuperAPI AI 工具集

query-agent

编程与开发

查看项目

更新于 10-16 06:57

技能介绍

用途

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。