4. 定义索引映射（Mapping）：使用 NestJS 装饰器或手动定义 Mapping，字段类型声明的最佳实践

索引映射（Mapping）是搜索引擎中定义字段名称、类型、分析器及索引选项的核心结构。在 Elasticsearch 中，Mapping 决定了文档如何被索引和搜索。本章将深入探讨在 NestJS 生态中，如何通过装饰器驱动或手动定义的方式声明 Mapping，并给出字段类型声明的最佳实践。

4.1 Mapping 的核心组成与类型体系

一个完整的 Mapping 定义包含以下关键维度：

4.2 NestJS 装饰器驱动 Mapping 声明

NestJS 生态中，@nestjs/elasticsearch 配合 @elastic/elasticsearch 客户端并不直接提供装饰器级别的 Mapping 声明。但社区最佳实践是通过自定义装饰器与元数据反射机制，将 Mapping 定义与实体类绑定。以下是一个成熟的实现模式：

// search-mapping.decorator.ts
import { SetMetadata } from '@nestjs/common';

export const MAPPING_FIELD_METADATA = 'mapping_field_metadata';

export interface MappingFieldOptions {
  type: string;
  analyzer?: string;
  index?: boolean;
  docValues?: boolean;
  fields?: Record<string, { type: string; analyzer?: string }>;
  format?: string;
  ignoreAbove?: number;
}

export function MappingField(options: MappingFieldOptions): PropertyDecorator {
  return (target: object, propertyKey: string | symbol) => {
    const existing =
      Reflect.getMetadata(MAPPING_FIELD_METADATA, target.constructor) || {};
    existing[propertyKey] = options;
    SetMetadata(MAPPING_FIELD_METADATA, existing)(target.constructor);
  };
}

// product.entity.ts
import { MappingField } from './search-mapping.decorator';

export class ProductEntity {
  @MappingField({ type: 'keyword' })
  id: string;

  @MappingField({
    type: 'text',
    analyzer: 'ik_max_word',
    fields: {
      keyword: { type: 'keyword' },
    },
  })
  title: string;

  @MappingField({ type: 'text', analyzer: 'standard' })
  description: string;

  @MappingField({ type: 'double' })
  price: number;

  @MappingField({ type: 'date', format: 'yyyy-MM-dd HH:mm:ss' })
  createdAt: Date;

  @MappingField({ type: 'integer' })
  stock: number;

  @MappingField({ type: 'boolean' })
  isActive: boolean;
}

4.3 手动定义 Mapping 的场景与策略

尽管装饰器模式优雅，但在以下场景中，手动定义 Mapping 更为合适：

• 动态字段：当文档结构不固定，需要启用 dynamic: true 或 dynamic_templates 时。
• 复杂嵌套：涉及 nested 类型或 join 类型时，手动定义更清晰。
• 跨语言共享：当 Mapping 需要被多个微服务或非 Node.js 服务共享时，JSON 文件更通用。
• 性能调优：需要精细控制 number_of_shards、number_of_replicas 等索引级别参数时。

// manual-mapping.ts
import { Client } from '@elastic/elasticsearch';

const client = new Client({ node: 'http://localhost:9200' });

const createIndexWithMapping = async () => {
  await client.indices.create({
    index: 'products_v2',
    body: {
      settings: {
        number_of_shards: 3,
        number_of_replicas: 1,
        analysis: {
          analyzer: {
            ik_smart_analyzer: {
              type: 'custom',
              tokenizer: 'ik_smart',
            },
          },
        },
      },
      mappings: {
        dynamic: 'strict',
        properties: {
          id: { type: 'keyword' },
          title: {
            type: 'text',
            analyzer: 'ik_smart_analyzer',
            fields: {
              keyword: { type: 'keyword' },
            },
          },
          description: { type: 'text', analyzer: 'standard' },
          price: { type: 'double' },
          tags: { type: 'keyword' },
          createdAt: { type: 'date', format: 'yyyy-MM-dd HH:mm:ss' },
          specifications: {
            type: 'nested',
            properties: {
              key: { type: 'keyword' },
              value: { type: 'keyword' },
            },
          },
        },
      },
    },
  });
};

4.4 字段类型声明的最佳实践清单

4.5 字段类型演进兼容策略

随着业务发展，字段类型可能需要变更。Elasticsearch 对 Mapping 修改有严格限制，以下策略可帮助平滑演进：

• 新增字段：允许直接添加新字段，不影响已有数据。
• 修改字段类型：不允许直接修改已有字段类型。推荐创建新索引（如 products_v3），使用 Reindex API 迁移数据。
• 别名索引：使用索引别名（Alias）对外暴露统一名称，内部切换索引版本。
• 多版本共存：在 Mapping 中保留旧字段，新增字段使用不同名称，通过应用层逻辑兼容。

4.6 动态模板与运行时字段

对于日志、事件等半结构化数据，动态模板（Dynamic Templates）可以自动为未知字段匹配类型规则，避免手动声明所有字段：

// dynamic-template-mapping.ts
const mappingWithDynamicTemplates = {
  dynamic: true,
  dynamic_templates: [
    {
      strings_as_keyword: {
        match_mapping_type: 'string',
        mapping: {
          type: 'keyword',
          ignore_above: 256,
        },
      },
    },
    {
      long_as_integer: {
        match_mapping_type: 'long',
        mapping: {
          type: 'integer',
        },
      },
    },
    {
      date_detection: {
        match: 'date_*',
        mapping: {
          type: 'date',
          format: 'yyyy-MM-dd',
        },
      },
    },
  ],
};

4.7 字段类型声明检查清单

• ✅ 每个字段都明确声明类型，避免依赖 Elasticsearch 自动类型推断。
• ✅ 字符串字段优先使用 text + keyword 多字段模式，兼顾搜索与聚合。
• ✅ 日期字段指定 format，确保跨时区解析一致。
• ✅ 嵌套对象使用 nested 而非 object，保证数组内对象独立查询。
• ✅ 对 keyword 字段设置 ignore_above，防止超长字符串导致索引失败。
• ✅ 使用索引别名管理版本，支持零停机 Mapping 升级。
• ✅ 在 CI 中集成 Mapping 校验，确保代码与 Elasticsearch 集群配置一致。