深入理解 ts-safeql/safeql 的 API 配置

深入理解 ts-safeql/safeql 的 API 配置

项目概述

ts-safeql/safeql 是一个强大的 TypeScript SQL 查询类型检查工具，它能够在开发阶段就对 SQL 查询进行静态类型检查，确保查询语句的正确性和类型安全。本文将详细介绍该项目的 API 配置选项，帮助开发者更好地利用这一工具提升开发效率和代码质量。

核心配置方式

SafeQL 提供了两种主要的配置方式：

1. 独立配置文件：通过 safeql.config.ts 文件进行配置
2. ESLint 内联配置：直接在 ESLint 配置文件中设置

使用配置文件

{
  "useConfigFile": true
}

对应的配置文件示例：

// safeql.config.ts
import { defineConfig } from "@ts-safeql/eslint-plugin";

export default defineConfig({
  connections: {
    // 配置内容
  },
});

注意：配置文件方式和内联配置方式不能同时使用。

数据库连接配置

单数据库连接

{
  "connections": {
    "databaseUrl": "postgres://user:pass@localhost:5432/dbname",
    "targets": [{ "tag": "sql" }]
  }
}

多数据库连接

{
  "connections": [
    {
      "databaseUrl": "postgres://user:pass@localhost:5432/dbname",
      "targets": [{ "tag": "sql" }]
    },
    {
      "databaseUrl": "postgres://user:pass@localhost:5432/dbname2",
      "targets": [{ "tag": "prisma.+($queryRaw|$executeRaw)" }]
    }
  ]
}

连接参数详解

数据库URL方式

{
  "connections": {
    "databaseUrl": "postgres://user:pass@localhost:5432/dbname"
  }
}

特点：

• 直接连接到目标数据库
• 不能与迁移目录配置同时使用

迁移目录方式

{
  "connections": {
    "migrationsDir": "prisma/migrations"
  }
}

特点：

• 通过分析迁移文件获取数据库结构
• 需要配合临时数据库使用
• 支持监听模式自动更新

临时数据库配置

当使用迁移目录方式时，SafeQL 需要创建临时数据库：

{
  "connections": {
    "migrationsDir": "prisma/migrations",
    "connectionUrl": "postgres://user:pass@localhost:5432/tempdb",
    "databaseName": "my_temp_db",
    "watchMode": true
  }
}

参数说明：

• connectionUrl：连接基础数据库的URL（默认为PostgreSQL默认连接）
• databaseName：临时数据库名称（默认自动生成）
• watchMode：是否监听迁移文件变化（默认为true）

查询目标配置

SafeQL 需要知道在代码中哪些部分需要分析SQL查询，这通过targets配置实现。

标签方式

{
  "targets": [{ "tag": "sql" }]
}

适用于模板字符串标记函数：

sql`SELECT id FROM users`;

包装函数方式

{
  "targets": [{ "wrapper": "conn.query" }]
}

适用于查询执行函数：

conn.query("SELECT id FROM users");

高级目标配置

1. 最大深度：控制SQL标签查找深度

   { "maxDepth": 2 }
   

2. 结果转换：修改查询结果类型

   { "transform": "{type}[]" }
   

3. 字段名转换：自动转换字段命名风格

   { "fieldTransform": "camel" }
   

4. 跳过类型注解：禁用自动类型添加

   { "skipTypeAnnotations": true }
   

类型系统控制

字面量推断控制

{
  "inferLiterals": ["string", "number"]
}

控制哪些类型的字面量会被推断为具体类型。

类型覆盖

1. 覆盖数据库类型映射：

   {
     "overrides": {
       "types": {
         "date": "LocalDate"
       }
     }
   }
   

2. 覆盖特定列类型：

   {
     "overrides": {
       "columns": {
         "users.created_at": "LocalDateTime"
       }
     }
   }
   

最佳实践建议

1. 对于大型项目，推荐使用配置文件方式
2. 开发环境建议开启watchMode提高开发效率
3. 合理使用字段名转换保持代码风格一致
4. 对于复杂类型系统，充分利用类型覆盖功能
5. 生产环境考虑关闭keepAlive节省资源

通过合理配置这些选项，SafeQL 能够显著提升 TypeScript 项目中 SQL 查询的安全性和开发体验。