NestJs与Couchbase集成方案咨询及代码示例需求

一、直接使用 Couchbase Node.js SDK #

这种方式适合需要完全控制 Couchbase 底层操作的场景，无需额外 ODM 封装，直接调用官方 SDK 接口。

1. 安装依赖 #

npm install couchbase

2. 创建 Couchbase 核心模块 #

创建 src/couchbase/couchbase.module.ts，封装集群连接与 Bucket 实例：

import { Module, Global, Provider } from '@nestjs/common';
import { Cluster, Bucket } from 'couchbase';

// 集群配置参数
const COUCHBASE_CONFIG = {
  connectionString: 'couchbase://localhost',
  username: 'Administrator',
  password: 'password',
  bucketName: 'my-bucket',
};

// 提供集群连接实例
const clusterProvider: Provider = {
  provide: 'COUCHBASE_CLUSTER',
  useFactory: async () => {
    return await Cluster.connect(
      COUCHBASE_CONFIG.connectionString,
      { username: COUCHBASE_CONFIG.username, password: COUCHBASE_CONFIG.password }
    );
  },
};

// 提供 Bucket 实例
const bucketProvider: Provider = {
  provide: 'COUCHBASE_BUCKET',
  useFactory: async (cluster: Cluster) => {
    const bucket = cluster.bucket(COUCHBASE_CONFIG.bucketName);
    await bucket.waitUntilReady(5000);
    return bucket;
  },
  inject: ['COUCHBASE_CLUSTER'],
};

@Global()
@Module({
  providers: [clusterProvider, bucketProvider],
  exports: ['COUCHBASE_CLUSTER', 'COUCHBASE_BUCKET'],
})
export class CouchbaseModule {}

3. 封装数据操作服务 #

创建 src/couchbase/couchbase.service.ts，封装基础 CRUD 与 N1QL 查询：

import { Injectable, Inject } from '@nestjs/common';
import { Bucket, Collection } from 'couchbase';

@Injectable()
export class CouchbaseService {
  private collection: Collection;

  constructor(@Inject('COUCHBASE_BUCKET') private bucket: Bucket) {
    this.collection = bucket.defaultCollection();
  }

  // 获取单条文档
  async getDocument<T>(id: string): Promise<T> {
    try {
      const result = await this.collection.get(id);
      return result.content as T;
    } catch (error) {
      if (error.code === 13) throw new Error('目标文档不存在');
      throw error;
    }
  }

  // 插入新文档
  async insertDocument<T>(id: string, doc: T): Promise<void> {
    await this.collection.insert(id, doc);
  }

  // 更新/插入文档（不存在则创建）
  async upsertDocument<T>(id: string, doc: Partial<T>): Promise<void> {
    await this.collection.upsert(id, doc);
  }

  // 删除文档
  async deleteDocument(id: string): Promise<void> {
    await this.collection.remove(id);
  }

  // 执行 N1QL 查询
  async runQuery<T>(query: string, params?: Record<string, any>): Promise<T[]> {
    const result = await this.bucket.cluster.query(query, { parameters: params });
    return result.rows as T[];
  }
}

4. 在业务模块中使用 #

以用户模块为例，src/user/user.module.ts：

import { Module } from '@nestjs/common';
import { CouchbaseModule } from '../couchbase/couchbase.module';
import { UserService } from './user.service';

@Module({
  imports: [CouchbaseModule],
  providers: [UserService],
  exports: [UserService],
})
export class UserModule {}

用户服务 src/user/user.service.ts：

import { Injectable } from '@nestjs/common';
import { CouchbaseService } from '../couchbase/couchbase.service';

interface User {
  id: string;
  name: string;
  email: string;
}

@Injectable()
export class UserService {
  constructor(private readonly couchbaseService: CouchbaseService) {}

  async createUser(user: User) {
    await this.couchbaseService.insertDocument(user.id, user);
  }

  async getUserById(id: string): Promise<User> {
    return this.couchbaseService.getDocument<User>(id);
  }

  async getUsersByEmail(email: string): Promise<User[]> {
    const query = 'SELECT * FROM `my-bucket` WHERE email = $email';
    return this.couchbaseService.runQuery<User>(query, { email });
  }
}

二、使用 Ottoman ODM（Couchbase 官方ODM） #

Ottoman 是 Couchbase 官方推出的对象文档映射工具，提供 schema 校验、模型封装、查询简化等功能，类似 Mongoose 对 MongoDB 的作用。

1. 安装依赖 #

npm install ottoman@v2  # v2 版本适配最新 Couchbase SDK

2. 配置 Ottoman 模块 #

创建 src/ottoman/ottoman.module.ts：

import { Module, Global, Provider } from '@nestjs/common';
import { Ottoman } from 'ottoman';

const OTTOMAN_INSTANCE = 'OTTOMAN_INSTANCE';

const ottomanProvider: Provider = {
  provide: OTTOMAN_INSTANCE,
  useFactory: async () => {
    const ottoman = new Ottoman({
      connectionString: 'couchbase://localhost',
      bucketName: 'my-bucket',
      username: 'Administrator',
      password: 'password',
      scopeName: '_default',
      collectionName: '_default',
    });

    await ottoman.start();
    return ottoman;
  },
};

@Global()
@Module({
  providers: [ottomanProvider],
  exports: [OTTOMAN_INSTANCE],
})
export class OttomanModule {}

3. 定义数据模型 #

创建 src/user/user.schema.ts：

import { Schema, model } from 'ottoman';

const UserSchema = new Schema({
  name: { type: String, required: true },
  email: { type: String, required: true, unique: true },
  age: { type: Number, min: 18 },
  createdAt: { type: Date, default: Date.now },
});

export const UserModel = model('User', UserSchema);

4. 封装业务服务 #

创建 src/user/user.service.ts：

import { Injectable } from '@nestjs/common';
import { UserModel } from './user.schema';
import { FindOptions } from 'ottoman';

@Injectable()
export class UserService {
  async createUser(userData: { name: string; email: string; age?: number }) {
    const user = new UserModel(userData);
    await user.save();
    return user;
  }

  async getUserById(id: string) {
    return UserModel.findById(id);
  }

  async findUsers(filter: any, options?: FindOptions) {
    return UserModel.find(filter, options);
  }

  async updateUser(id: string, updateData: Partial<{ name: string; age: number }>) {
    return UserModel.updateById(id, updateData);
  }

  async deleteUser(id: string) {
    return UserModel.removeById(id);
  }
}

5. 在模块中注册模型 #

修改 src/user/user.module.ts，确保模型被加载注册：

import { Module } from '@nestjs/common';
import { OttomanModule } from '../ottoman/ottoman.module';
import { UserService } from './user.service';
import './user.schema'; // 引入模型完成自动注册

@Module({
  imports: [OttomanModule],
  providers: [UserService],
  exports: [UserService],
})
export class UserModule {}

内容的提问来源于stack exchange，提问作者Fabrice G.