在Express应用中为Firestore文档生成自定义递增ID的教程

新闻中心 NEWS CENTER

您当前位置：首页 > 新闻中心 > 网络学院

在Express应用中为Firestore文档生成自定义递增ID的教程

2025-11-12

浏览次数：次

返回列表

在express应用中为firestore文档生成自定义递增id的教程

本教程将指导您如何在Express后端应用中为Firestore文档生成自定义的、具有特定格式的递增ID，而不是依赖Firestore的自动生成ID或使用现有字段。我们将通过维护一个计数器文档并利用Firestore事务来确保ID生成的唯一性和原子性，同时提供具体的代码实现和注意事项。

理解Firestore文档ID

Firestore中的每个文档都必须有一个唯一的ID。您可以选择以下几种方式来指定文档ID：

Firestore自动生成ID： 当您调用 collectionRef.add(data) 或 collectionRef.doc().set(data) 时，Firestore会自动生成一个唯一的、随机的字符串作为文档ID。这种ID通常是20个字符的Base64编码字符串，保证全球唯一性，但可读性较差。
```
// 示例：Firestore自动生成ID
const menteeDb = db.collection('mentee');
const response = await menteeDb.add(menteeJson); // ID将自动生成
// 或者
// const response = await menteeDb.doc().set(menteeJson); // ID将自动生成
```
手动指定ID： 您可以通过 collectionRef.doc(yourId).set(data) 方法来指定文档ID。这个ID可以是任何字符串，但必须在集合内是唯一的。
```
// 示例：使用请求体中的NAME字段作为ID
const id = req.body.NAME;
const menteeDb = db.collection('mentee');
const response = await menteeDb.doc(id).set(menteeJson);
```
这种方式虽然简单，但如果 NAME 字段不保证唯一性，可能会导致数据覆盖；如果 NAME 字段发生变化，ID也会随之变化，不利于数据管理。

自定义递增ID的需求与挑战

在某些业务场景中，我们可能需要特定格式的文档ID，例如：

具有业务含义的前缀（如 'B' 代表学员）。
固定长度。
递增的数字部分，便于排序或识别创建顺序。

例如，目标ID格式为 'B' 加上 5 位递增数字（如 'B00001', 'B00002', ..., 'B99999'）。

生成这种递增ID的主要挑战在于：

并发性： 在多用户或高并发环境下，多个请求可能同时尝试获取并生成下一个ID，这可能导致ID重复或跳号。
原子性： 获取当前计数器、生成新ID和更新计数器这三个操作必须作为一个原子单元执行，以避免竞态条件。

解决方案：基于Firestore计数器与事务

为了解决上述挑战，我们可以在Firestore中维护一个专门的“计数器”文档，并利用Firestore的事务功能来确保ID生成的原子性和一致性。

核心思路：

创建一个特殊的集合（例如 _counters），并在其中为每种需要自定义ID的文档类型创建一个计数器文档（例如 _counters/menteeId）。
计数器文档中存储下一个可用的数字序列。
当需要生成新ID时，在一个Firestore事务中：
- 读取计数器文档的当前值。
- 递增该值。
- 使用递增后的值格式化新的文档ID。
- 更新计数器文档为新的值。
- 使用新生成的ID创建目标文档。
- 如果事务中的任何一步失败，整个事务将重试或回滚，从而保证数据一致性。

1. 初始化计数器文档

首先，在您的Firestore中手动或通过代码创建 _counters/menteeId 文档，并设置一个初始值（例如 currentValue: 0）。

// Firestore文档路径: _counters/menteeId
{
  "currentValue": 0
}

2. 实现ID生成逻辑

创建一个异步函数来处理ID的生成，该函数将封装在Firestore事务中。

// 假设 db 已经通过 admin SDK 初始化
const admin = require('firebase-admin');
const serviceAccount = require('./path/to/your/serviceAccountKey.json'); // 替换为您的服务账号密钥路径

admin.initializeApp({
  credential: admin.credential.cert(serviceAccount),
  // databaseURL: "https://your-project-id.firebaseio.com" // 如果需要实时数据库
});

const db = admin.firestore();

/**
 * 生成自定义递增的Firestore文档ID
 * @param {string} counterName 计数器文档的名称 (例如 'menteeId')
 * @param {string} prefix ID前缀 (例如 'B')
 * @param {number} length 数字部分的长度 (例如 5)
 * @returns {Promise<string>} 生成的文档ID
 */
async function generateCustomIncrementingId(counterName, prefix, length) {
  const counterRef = db.collection('_counters').doc(counterName);

  return db.runTransaction(async (transaction) => {
    const counterDoc = await transaction.get(counterRef);

    let nextNumber;
    if (!counterDoc.exists) {
      // 如果计数器不存在，初始化为0
      transaction.set(counterRef, { currentValue: 0 });
      nextNumber = 1;
    } else {
      nextNumber = counterDoc.data().currentValue + 1;
    }

    // 更新计数器
    transaction.update(counterRef, { currentValue: nextNumber });

    // 格式化ID
    const formattedNumber = String(nextNumber).padStart(length, '0');
    return `${prefix}${formattedNumber}`;
  });
}

3. 集成到Express路由

现在，将这个ID生成函数集成到您的Express POST 路由中。

Tanka

具备AI长期记忆的下一代团队协作沟通工具

146 查看详情 Tanka

const express = require('express');
const app = express();
app.use(express.json()); // 确保Express可以解析JSON请求体

// ... (Firebase Admin SDK 初始化代码如上所示) ...

// 创建 Mentee
app.post('/create', async (req, res) => {
  try {
    console.log(req.body);

    // 1. 生成自定义ID
    const customMenteeId = await generateCustomIncrementingId('menteeId', 'B', 5);

    const menteeJson = {
      ID: customMenteeId, // 可以在文档内部也存储ID
      NAME: req.body.NAME,
      LOCATION: req.body.LOCATION,
      SUBDISTRICT: req.body.SUBDISTRICT,
      LATITUDE: req.body.LATITUDE,
      LONGITUDE: req.body.LONGITUDE,
      createdAt: admin.firestore.FieldValue.serverTimestamp() // 记录创建时间
    };

    const menteeDb = db.collection('mentee');
    // 2. 使用生成的ID设置文档
    const response = await menteeDb.doc(customMenteeId).set(menteeJson);

    res.status(201).send({
      message: 'Mentee created successfully',
      id: customMenteeId,
      response: response
    });

  } catch (error) {
    console.error('Error creating mentee:', error);
    res.status(500).send({
      message: 'Failed to create mentee',
      error: error.message
    });
  }
});

const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
  console.log(`Server is running on port ${PORT}`);
});

注意事项与最佳实践

错误处理： 在实际应用中，务必对 generateCustomIncrementingId 函数和 menteeDb.doc().set() 操作进行全面的错误处理。
计数器初始化： 确保 _counters/menteeId 文档在首次使用前已存在并包含 currentValue 字段。如果计数器不存在，上述 generateCustomIncrementingId 函数会尝试初始化它，但最好在部署时手动设置一个起始值。

计数器文档的安全性： 配置Firestore安全规则，确保只有您的后端服务（通过服务账号）才能读取和写入 _counters 集合，防止客户端直接篡改计数器。

rules_version = '2';
service firebase.storage {
  match /b/{bucket}/o/{allPaths=**} {
    allow read, write: if request.auth != null;
  }
}
service cloud.firestore {
  match /databases/{database}/documents {
    // 允许后端服务（通过Admin SDK）访问所有文档
    match /{document=**} {
      allow read, write: if request.auth == null; // 假设Admin SDK请求没有request.auth
    }

    // 更严格的计数器规则示例：
    // 确保只有特定服务账户（如果您的规则允许区分）或无auth请求（来自Admin SDK）可以写入计数器
    match /_counters/{counterId} {
      allow read, update: if request.auth == null;
      allow create: if request.auth == null;
    }
    // 对于其他集合，例如 'mentee'，可以根据您的认证逻辑设置规则
    match /mentee/{menteeId} {
      allow read: if true; // 示例：所有人可读
      allow create, update, delete: if request.auth != null; // 示例：认证用户可写
    }
  }
}

注意： request.auth == null 通常用于判断请求是否来自Firebase Admin SDK。请根据您的具体安全模型调整。

性能考虑： 计数器文档可能会成为高并发写入的瓶颈。对于绝大多数应用，这种方法是可行的。如果您的应用需要每秒处理数千甚至上万次写入，并且每次写入都需要一个递增ID，您可能需要考虑更高级的分布式计数器解决方案或重新评估是否真的需要严格递增的ID。
ID长度和格式： 确保 length 参数足够大，以容纳预期的最大数字。如果超出 99999，B00001 这种格式将无法表示，需要调整长度或设计新的格式。
替代方案： 如果您不需要严格的递增顺序，而只需要一个可读性好、唯一性强的自定义ID，可以考虑使用像 nanoid 或 uuid 这样的库来生成短而独特的随机字符串，并结合前缀。
```
const { nanoid } = require('nanoid');
// ...
const customMenteeId = 'B' + nanoid(5); // 例如 'B' + 'abcde'
```
这种方式不需要事务和计数器，实现更简单，性能更高，但ID是随机的，不具备递增特性。