SuperAPI AI 工具集

postgresql-query-generation

编程与开发

查看项目

更新于 10-16 06:07

技能介绍

用途

PostgreSQL Query Generation 是一个面向 .NET 项目的技能,用于在使用 Entity Framework Core 的项目中生成生产可用的 PostgreSQL 查询。它会自动发现项目的领域结构,并生成带有正确关系、多租户过滤、软删除过滤以及 ABP Framework 约定的优化 SQL。

主要能力

自动发现

  • 扫描 src/*/Domain/Entities/**/*.cs 中的实体类
  • 从基类(如 FullAuditedAggregateRoot、SetupEntity 等)继承属性
  • 通过 {EntityName}Id 模式检测外键
  • 识别导航属性(ICollection、T)
  • 自动将 C# 类型映射为 PostgreSQL 类型

支持的查询模式

  • 多实体 JOIN 查询
  • 通过连接表实现的多对多关系
  • 层级/自引用(递归 CTE)
  • JSONB 查询(@>、?、jsonb_path_query)
  • 窗口函数(ROW_NUMBER、FIRST_VALUE 等)
  • 带 COUNT 的分页
  • 带复杂 JOIN 的权限/安全查询
  • 聚合与 GROUP BY
  • 全文搜索(ILIKE)
  • 批量操作(带 CASE 的 INSERT/UPDATE)

项目特定模式

  • ABP Framework:自动检测 TenantId、IsDeleted、CreationTime 审计字段
  • 多租户:始终添加 TenantId = @tenantId 过滤
  • 软删除:添加 IsDeleted = false 过滤
  • JSONB 字段:针对 InitialData、FormData、JsonSchema 等优化查询
  • 命名约定:使用带引号的标识符(如 "SystemName")

使用方式

通过 Python 脚本以命令行方式调用:

# 交互模式(输出到 stdout)
python scripts/generate_query.py --interactive

# 生成查询 - 自动在当前目录保存 .sql 文件
python scripts/generate_query.py --query "get all applications with workflow stages"

# 使用自定义输出文件名生成查询
python scripts/generate_query.py --query "get all applications" --output my_query.sql

# 仅发现领域(以 JSON 输出 schema)
python scripts/generate_query.py --discover-only --output schema.json

输出文件

使用 --query 且未指定 --output 时,技能会自动在当前工作目录创建 .sql 文件,包含:

  • 基于实体名或查询关键词自动生成的文件名(如 application_workflow_instance_1678901234.sql)
  • 时间戳以确保唯一性
  • 完整、生产可用的 PostgreSQL 查询
  • 正确的参数化(@paramName 风格)
  • 自动包含 TenantId 和软删除过滤
  • 基于外键的优化 JOIN
  • 解释关键模式的注释

使用 --output 可指定自定义文件名,文件默认保存在当前工作目录,也可提供完整路径。

配置

无需配置,技能会自动适配。若项目使用自定义基类,会自动继承其属性;非标准表名会从 [Table("...")] 特性检测;不同 schema 会从 [Schema("...")] 特性检测;复合键按检测结果处理。

跨项目可移植性

适用于任何 EF Core 项目:

  • ABP Framework(FullAuditedAggregateRoot、IMultiTenant):自动添加 TenantId、IsDeleted 过滤
  • 自定义 DDD(AggregateRoot、Entity):遵循聚合边界、标准属性
  • 普通 EF Core(Entity):基础实体模式
  • 多租户(TenantId 属性):始终按 @tenantId 过滤
  • 单租户(无 TenantId):跳过租户过滤
  • 软删除(IsDeleted 属性):自动添加 IsDeleted = false
  • 无软删除(无 IsDeleted):跳过软删除过滤

适用场景

  • 为 ABP Framework 或自定义 DDD 项目快速编写复杂查询
  • 需要自动处理多租户和软删除过滤的查询
  • 涉及 JSONB、窗口函数、递归层级、权限检查等复杂 SQL 的场景
  • 希望从自然语言描述生成特定 SQL 的开发流程

限制

  • C# 解析:使用简化解析器,复杂泛型基类可能需要人工检查
  • 动态查询:不是查询构建器,只生成特定 SQL
  • 过程式代码:无法生成存储过程或函数
  • 非 EF 数据:只发现实体,不发现原始表或视图
  • 特性覆盖:支持 [Table] 和 [Column] 特性(基础)

要求

  • Python 3.8+
  • 可访问项目源代码(读取实体定义)
  • 无需依赖(使用标准库)

性能

  • 发现(500 个实体):约 500ms - 2s
  • 查询生成:约 50-200ms
  • 缓存查询:约 5-20ms

Schema 在会话期间缓存在内存中。

工作流程

  1. 发现(首次运行自动执行):扫描实体文件、构建 schema 模型、缓存结果
  2. 生成:解析自然语言请求、识别目标实体、确定所需 JOIN、应用项目约定、输出最终查询
  3. 输出:打印到 stdout 或保存为 .sql 文件,包含参数占位符和注释

提示

  • 细化请求:包含实体名(如 "Products" 而非 "items")
  • 使用自然语言:"Get active Users with Admin roles" 或 "Show Orders pending approval"
  • 指定 JOIN:"Applications with workflow stages" 会自动连接相关实体
  • Schema 缓存:首次运行较慢(100ms-2s),后续运行即时

许可

开源 - 属于 ACMS 生态系统的一部分。