Spring Data MongoDB：为子对象中单个String字段实现加密转换器

针对你提到的MongoDB单个子对象字段加密需求，最优方案肯定是用MongoDB官方的客户端字段级加密（CSFLE），完全不用写整个文档的自定义写入器，刚好贴合你的场景。下面详细说下实现方式和备选方案：

一、最优方案：客户端字段级加密（CSFLE） #

这是MongoDB官方专为字段级加密设计的功能，支持自动对指定字段加密存储、解密读取，安全性经过验证，还能避免自己实现加密带来的安全漏洞。核心是通过配置客户端，指定需要加密的字段路径，剩下的加密逻辑由客户端自动处理。

实现步骤（以Node.js官方驱动为例） #

1. 准备加密密钥与KMS
   首先需要创建数据加密密钥（DEK），以及对应的密钥管理服务（KMS）——测试阶段可以用本地密钥，生产环境建议用AWS KMS、Azure Key Vault这类专业服务。
2. 配置客户端加密规则
   指定要加密的字段路径（比如你的subObject.secret）、字段类型、加密算法等。
3. 使用加密客户端操作集合
   初始化带加密配置的客户端，之后的读写操作会自动处理加密解密。

const { MongoClient } = require('mongodb');
const { ClientEncryption } = require('mongodb-client-encryption');

// 初始化基础客户端，用于创建加密密钥
const baseClient = new MongoClient('mongodb://localhost:27017');
await baseClient.connect();

// 配置加密客户端
const encryption = new ClientEncryption(baseClient, {
  keyVaultNamespace: 'encryption.__keyVault', // 存储加密密钥的集合
  kmsProviders: {
    local: {
      key: Buffer.from('your-32-byte-local-encryption-key', 'utf8') // 本地测试密钥，生产替换为KMS配置
    }
  }
});

// 创建数据加密密钥（DEK）
const dataEncryptionKey = await encryption.createDataKey('local');

// 定义加密字段映射：指定哪个集合的哪个字段需要加密
const encryptedFieldsMap = {
  'your_database.your_collection': {
    fields: [
      {
        path: 'subObject.secret', // 你的子对象secret字段路径
        bsonType: 'string',
        keyId: [dataEncryptionKey],
        encryptionAlgorithm: 'AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic' // 确定性加密支持明文查询
      }
    ]
  }
};

// 初始化带自动加密的客户端
const encryptedClient = new MongoClient('mongodb://localhost:27017', {
  autoEncryption: {
    keyVaultNamespace: 'encryption.__keyVault',
    kmsProviders: { local: { key: Buffer.from('your-32-byte-local-encryption-key', 'utf8') } },
    encryptedFieldsMap
  }
});

// 操作集合示例
await encryptedClient.connect();
const db = encryptedClient.db('your_database');
const coll = db.collection('your_collection');

// 插入文档：subObject.secret会自动加密存储
await coll.insertOne({
  name: 'sample',
  subObject: {
    secret: 'my-sensitive-info'
  }
});

// 查询文档：subObject.secret会自动解密
const doc = await coll.findOne({ name: 'sample' });
console.log(doc.subObject.secret); // 输出明文 my-sensitive-info

await encryptedClient.close();
await baseClient.close();

这个方案的优势很明显：官方维护、安全合规、自动处理加密解密，还支持基于明文的字段查询（用确定性加密算法的话），完全不需要自己写复杂的转换器逻辑。

二、备选：自定义字段转换器（仅特殊场景使用） #

如果因为MongoDB版本过低或其他限制无法使用CSFLE，那可以在客户端层面为单个字段实现自定义的加密/解密转换器。比如用Mongoose的Schema字段set和get方法，或者在业务代码里手动处理。

用Mongoose实现单个字段转换器 #

这里以Mongoose为例，给subObject.secret字段配置自动加密的写入逻辑和解密的读取逻辑：

const mongoose = require('mongoose');
const crypto = require('crypto');

// 加密解密工具函数：注意密钥要安全存储，绝对不能硬编码在代码里！
const ENCRYPTION_KEY = Buffer.from(process.env.ENCRYPTION_KEY, 'utf8'); // 从环境变量读取密钥
const IV_LENGTH = 16; // AES块大小

// 加密函数
function encryptPlainText(text) {
  const iv = crypto.randomBytes(IV_LENGTH);
  const cipher = crypto.createCipher('aes-256-cbc', ENCRYPTION_KEY);
  let encrypted = cipher.update(text);
  encrypted = Buffer.concat([encrypted, cipher.final()]);
  return `${iv.toString('hex')}:${encrypted.toString('hex')}`;
}

// 解密函数
function decryptCipherText(text) {
  const [ivHex, encryptedHex] = text.split(':');
  const iv = Buffer.from(ivHex, 'hex');
  const encryptedText = Buffer.from(encryptedHex, 'hex');
  const decipher = crypto.createDecipher('aes-256-cbc', ENCRYPTION_KEY);
  let decrypted = decipher.update(encryptedText);
  decrypted = Buffer.concat([decrypted, decipher.final()]);
  return decrypted.toString();
}

// 定义Schema，给subObject.secret配置转换器
const yourSchema = new mongoose.Schema({
  name: String,
  subObject: {
    secret: {
      type: String,
      set: encryptPlainText, // 写入数据库时自动加密
      get: decryptCipherText // 读取时自动解密
    }
  }
});

// 创建Model
const YourModel = mongoose.model('YourCollection', yourSchema);

// 使用示例
async function runExample() {
  await mongoose.connect('mongodb://localhost:27017/your_database');
  
  // 插入文档
  const doc = new YourModel({
    name: 'test',
    subObject: { secret: 'my-secret-data' }
  });
  await doc.save(); // 存储时secret字段是加密后的字符串
  
  // 查询文档
  const savedDoc = await YourModel.findOne({ name: 'test' });
  console.log(savedDoc.subObject.secret); // 输出明文 my-secret-data
  
  await mongoose.disconnect();
}

runExample();

自定义转换器的注意事项 #

• 密钥管理是重中之重：绝对不能把密钥硬编码在代码里，要放在环境变量、密钥管理服务（比如HashiCorp Vault）中。
• 安全风险：自己实现加密容易出现逻辑漏洞，比如IV重复、算法选择不当等，尽量使用经过安全验证的加密算法。
• 查询限制：自定义加密后，无法用明文对secret字段进行查询，只能用加密后的字符串查询；而CSFLE的确定性加密支持明文查询。

总结 #

优先选择客户端字段级加密（CSFLE），这是MongoDB官方提供的最优解，完全贴合你的需求，不用写整个文档的自定义写入器；如果因为特殊限制无法使用CSFLE，再考虑自定义字段转换器，但一定要做好安全和密钥管理。

内容的提问来源于stack exchange，提问作者Sam