SafeQL项目：渐进式采用类型安全SQL查询的最佳实践

SafeQL项目：渐进式采用类型安全SQL查询的最佳实践

safeql Validate and auto-generate TypeScript types from raw SQL queries in PostgreSQL. 项目地址: https://gitcode.com/gh_mirrors/sa/safeql

什么是渐进式采用

在大型项目中引入新技术或工具时，渐进式采用(Incremental Adoption)是一种非常实用的策略。对于SafeQL这样的SQL查询类型安全工具来说，渐进式采用意味着开发者可以：

1. 从单个查询开始使用SafeQL
2. 逐步扩展到更多查询
3. 无需一次性重构整个代码库
4. 随时可以停止使用而不受限制

这种策略特别适合已有大型代码库的项目，因为它允许团队以可控的节奏进行迁移，降低风险和工作量。

实现原理

SafeQL通过ESLint插件实现SQL查询的静态类型检查。其核心机制是：

1. 创建一个类型安全的查询函数包装器（如示例中的$typedQueryRaw）
2. 配置ESLint规则来识别这个包装器
3. 在开发阶段对标记的查询进行类型检查

运行时，这个包装器与原始查询函数完全一致，不会引入任何额外开销或行为变化。

具体实施步骤

第一步：创建类型安全查询包装器

// db.ts
import { PrismaClient } from "@prisma/client";

export const prisma = new PrismaClient();
// 创建类型安全的查询函数包装器
export const $typedQueryRaw = prisma.$queryRaw;

这个包装器在运行时与原始$queryRaw完全一致，但在开发阶段会被SafeQL特殊处理。

第二步：配置ESLint规则

{
  "rules": {
    "@ts-safeql/check-sql": [
      "error",
      {
        "connections": {
          "migrationsDir": "./prisma/migrations",
          "targets": [
            {
              "tag": "$typedQueryRaw",  // 识别这个标识符
              "transform": "{type}[]"   // 类型转换规则
            }
          ]
        }
      }
    ]
  }
}

关键配置项说明：

• tag: 指定要检查的函数标识符
• transform: 定义如何转换查询结果的类型
• migrationsDir: 指定数据库迁移文件位置，用于获取最新schema

第三步：逐步替换查询

现在，你可以在代码中逐步将prisma.$queryRaw替换为$typedQueryRaw：

// 旧代码 - 无类型检查
const users = await prisma.$queryRaw`SELECT * FROM users`;

// 新代码 - 带类型检查
const users = await $typedQueryRaw`SELECT * FROM users`;

每次替换后，ESLint都会自动检查该查询是否符合数据库schema。

实际开发中的优势

1. 风险可控：可以逐个文件甚至逐个查询进行迁移
2. 即时反馈：开发时就能发现SQL与schema不匹配的问题
3. 无运行时开销：类型检查只在开发阶段进行
4. 团队协作友好：新代码使用类型安全查询，旧代码保持原样
5. 类型推断：自动推断查询返回结果的TypeScript类型

适用场景扩展

虽然示例使用了Prisma，但这种方法同样适用于：

1. 直接使用pg、mysql2等数据库客户端库
2. 使用Knex、TypeORM等其他ORM工具
3. 任何支持原始SQL查询的数据库访问层

只需调整配置中的tag指向对应的查询方法即可。

注意事项

1. 确保数据库迁移文件是最新的，这样SafeQL才能获取准确的schema
2. 团队需要统一约定哪些查询应该使用类型安全版本
3. 复杂的SQL可能需要额外的类型提示
4. 定期检查未被替换的原始查询，逐步扩大类型安全覆盖范围

通过这种渐进式方法，团队可以在不影响现有功能的前提下，逐步提升代码库的类型安全性，最终实现所有SQL查询的类型安全验证。

safeql Validate and auto-generate TypeScript types from raw SQL queries in PostgreSQL. 项目地址: https://gitcode.com/gh_mirrors/sa/safeql