用途
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 在会话期间缓存在内存中。
工作流程
- 发现(首次运行自动执行):扫描实体文件、构建 schema 模型、缓存结果
- 生成:解析自然语言请求、识别目标实体、确定所需 JOIN、应用项目约定、输出最终查询
- 输出:打印到 stdout 或保存为 .sql 文件,包含参数占位符和注释
提示
- 细化请求:包含实体名(如 "Products" 而非 "items")
- 使用自然语言:"Get active Users with Admin roles" 或 "Show Orders pending approval"
- 指定 JOIN:"Applications with workflow stages" 会自动连接相关实体
- Schema 缓存:首次运行较慢(100ms-2s),后续运行即时
许可
开源 - 属于 ACMS 生态系统的一部分。