Kysely框架中CamelCasePlugin插件的使用限制与解决方案

问题背景

Kysely是一个类型安全的SQL查询构建器，它提供了CamelCasePlugin插件来自动将数据库中的蛇形命名(snake_case)转换为JavaScript中更常见的驼峰命名(camelCase)。这个功能在大多数情况下非常有用，但在处理特定类型的列数据时可能会带来问题。

核心问题

当开发者使用JSON或JSONB类型的列存储结构化数据时，CamelCasePlugin会递归地转换所有嵌套对象的键名。这在某些场景下是不希望的，特别是当：

1. JSON对象中的键名本身就是业务数据的一部分
2. 键名需要保持原样用于后续处理
3. 键名遵循特定命名约定(如包含特定前缀或后缀)

现有解决方案的局限性

Kysely当前版本提供了maintainNestedObjectKeys选项，可以完全禁用对嵌套对象的键名转换。但这种全局性的设置过于粗糙，无法满足以下需求：

• 仅对特定列禁用转换
• 根据数据类型选择性禁用转换
• 在查询级别动态控制转换行为

自定义解决方案实现

通过继承CamelCasePlugin类，我们可以实现更细粒度的控制。以下是一个改进后的实现方案：

import { CamelCasePlugin, CamelCasePluginOptions, UnknownRow } from 'kysely';
import isPlainObject from 'lodash/isPlainObject';

export class CustomCamelCasePlugin extends CamelCasePlugin {
    private excludedColumns: string[];
    
    constructor({ excludeColumns = [], ...opt }: CamelCasePluginOptions & { excludeColumns?: string[] } = {}) {
        super(opt);
        this.excludedColumns = excludeColumns;
    }
    
    protected mapRow(row: UnknownRow): UnknownRow {
        return Object.keys(row).reduce((obj: Record<string, any>, key) => {
            let value = row[key];
            
            if (this.excludedColumns.includes(key)) {
                // 跳过排除列的转换
                obj[key] = value;
            } else if (Array.isArray(value)) {
                // 处理数组类型
                value = value.map((it) => 
                    (this.canMap(it, this.opt) ? this.mapRow(it) : it)
                );
            } else if (this.canMap(value, this.opt)) {
                // 处理可映射对象
                value = this.mapRow(value as UnknownRow);
            }
            
            // 应用驼峰转换
            obj[this.camelCase(key)] = value;
            return obj;
        }, {});
    }
    
    private canMap(obj: any, opt: any) {
        return isPlainObject(obj) && !opt?.maintainNestedObjectKeys;
    }
}

使用示例

import { PostgresDialect } from 'kysely';
import { Pool } from 'pg';
import { Database } from 'kysely';
import { CustomCamelCasePlugin } from './camel-case-plugin';

const db = new Database({
    dialect: new PostgresDialect({
        pool: new Pool({
            // 数据库连接配置
        }),
    }),
    plugins: [
        new CustomCamelCasePlugin({
            excludeColumns: ['custom_fields', 'metadata'],
        }),
    ],
});

实现原理分析

这个自定义插件通过以下方式工作：

1. 接受一个额外的excludeColumns参数，指定需要跳过转换的列名
2. 在mapRow方法中检查当前处理的列是否在排除列表中
3. 对于排除列，直接保留原始值不做任何转换
4. 对于非排除列，保持原有的驼峰转换逻辑

注意事项

1. 列名匹配是基于原始数据库列名，而不是转换后的驼峰命名
2. 排除列设置是全局性的，会影响所有查询
3. 数组和嵌套对象的处理逻辑保持不变
4. 需要确保排除列名的大小写与数据库中的实际列名完全一致

未来改进方向

虽然这个解决方案解决了当前问题，但仍有改进空间：

1. 支持基于数据类型的排除(如所有JSON/JSONB列)
2. 支持查询级别的动态控制
3. 提供更灵活的匹配模式(如正则表达式)
4. 支持基于列的前缀/后缀排除

结论

在Kysely中使用CamelCasePlugin时，对于需要保持原始键名的JSON/JSONB列，可以通过自定义插件实现细粒度的控制。这种解决方案既保留了驼峰命名的便利性，又确保了特定业务数据的完整性。开发者可以根据实际需求调整实现细节，平衡命名规范与业务需求。