Spring Data Elasticsearch 将索引映射的声明从JSON配置文件搬进了Java实体类。这种做法的最大好处是编译期就能发现字段名拼写错误，重构代码时映射关系同步更新，不需要再维护一份独立的JSON映射文件。下面围绕注解配置的细节展开讨论。

核心注解：@Document、@Id 与 @Field

@Document 标注在类级别，用来声明当前实体类对应的索引信息。它最常用的属性包括 indexName、createIndex 和 replicas。indexName 指定索引名称，支持 SpEL 表达式动态拼接，比如在多租户场景中可以根据当前上下文生成不同的索引名。createIndex 默认为 true，表示应用启动并建立连接后，框架会检查索引是否存在，不存在则自动创建。replicas 和 shards 分别控制副本数量和主分片数量，不过分片数在索引创建后无法修改，这一点需要提前规划好。

@Id 注解用于标识文档的唯一键，对应 Elasticsearch 中的 _id 字段。框架会自动将带有 @Id 注解的字段值映射为文档 ID，不需要在 @Field 中重复配置。需要注意，@Id 字段的类型通常使用 String 或 Long，如果使用其他类型，框架会调用 toString 方法转成字符串。另外，@Id 字段不会作为普通字段写入 _source，如果你想在查询结果中同时拿到文档 ID，需要额外在实体类中声明一个字段并用 @Field 标注，然后在映射转换时手动赋值。

@Field 是映射配置的核心，标注在字段级别，控制该字段在索引中的类型和行为。它有一个 type 属性，取值来自 FieldType 枚举，包括 Text、Keyword、Long、Integer、Date、Float、Double、Boolean、Object、Nested 等。如果实体类中的字段没有标注 @Field，框架会尝试根据 Java 类型自动推断映射类型，但自动推断的结果有时并不理想，特别是 String 类型，默认会被映射为 Text 并且同时生成 Keyword 子字段，这在只需要精确匹配的场景下会浪费存储空间。

Field 注解中常用映射参数详解

index 参数控制字段是否参与索引。默认值为 true，表示字段会被索引并可以被搜索。设为 false 后，该字段只存储但不建立倒排索引，无法参与查询条件。这个参数在实际业务中经常被忽略，比如商品的详情描述原文、文章的正文内容，如果只需要展示不需要搜索，就可以设置 index = false 来减少索引体积。但要注意，index = false 与 type = Object 混用时，如果对象内部还有字段需要检索，不能简单地在对象字段上加 index = false，否则整个对象都不会被索引。

store 参数决定字段的原始值是否单独存储。在 Elasticsearch 中，默认情况下所有字段的值都保存在 _source 中，查询结果可以直接从 _source 解析出来，所以 store 默认是 false。只有当你的查询场景需要频繁获取某个大字段而其他字段很少用到时，将 store 设置为 true 可以避免每次解析整个 _source。不过这种优化收益有限，因为解析 _source 的开销通常小于单独读取存储字段的随机 IO 开销，因此除非有明确的性能数据支撑，否则建议保持默认值。

analyzer 和 searchAnalyzer 这两个参数只对 Text 类型字段有意义。analyzer 指定索引时分词器，决定文本在写入索引时如何被切分成词项。searchAnalyzer 指定查询时分词器，决定搜索关键词如何被切分。通常情况下两者保持一致即可，但在某些场景下需要设置不同的分词器。比如索引时使用 ik_max_word 做细粒度切分，查询时使用 ik_smart 做粗粒度切分，这样可以在召回率和精确率之间取得平衡。如果没有显式指定 searchAnalyzer，查询时会默认使用 analyzer 指定的分词器。

format 参数用于 Date 类型字段，指定日期字符串的解析格式。Elasticsearch 支持多种日期格式，可以同时指定多个格式用 || 分隔，例如 format = DateFormat.custom, pattern = "yyyy-MM-dd HH:mm:ss||yyyy-MM-dd||epoch_millis"。这里强调一下，Java 中的 LocalDateTime 或 Date 类型字段默认会被映射为 Date 类型，但框架自动配置的格式可能不满足业务需要，因此显式指定 pattern 是一个好习惯。

嵌套对象与复杂结构的映射处理

当实体类中包含另一个自定义对象时，映射关系会自动形成 object 类型。object 类型在存储时会将内部字段扁平化处理，即内部字段与外层字段在同一层级。这种扁平化带来一个问题：如果内部对象是集合类型，并且需要保持每个对象的内部字段之间的关联关系，object 类型就无法满足。举个例子，一个订单文档中包含多个商品，每个商品有名称和数量两个属性。如果使用 object 类型，查询“名称为苹果且数量大于10”的条件会错误匹配到“名称为苹果但数量为3、另一个商品名称为梨但数量为20”的文档，因为名称和数量之间的关联丢失了。

解决这个问题需要使用 Nested 类型。在 @Field 注解中设置 type = FieldType.Nested，Elasticsearch 会为每个嵌套对象创建独立的文档进行索引，查询时通过 nested 查询语句可以精确匹配每个对象内部的字段关系。但 Nested 类型有明显代价：嵌套对象越多，底层文档数量越大，写入和查询性能都会下降。因此在设计映射时，如果内部对象不需要独立查询或者字段关联性不强，尽量使用 object 类型。只有明确存在“对象内部多条件组合查询”的需求时，才考虑 Nested。

@Document(indexName = "order_index", replicas = 1)
public class Order {
    @Id
    private String id;
    @Field(type = FieldType.Keyword)
    private String orderNo;
    @Field(type = FieldType.Nested)
    private List<OrderItem> items;
    @Field(type = FieldType.Date, format = DateFormat.custom,
           pattern = "yyyy-MM-dd HH:mm:ss")
    private LocalDateTime createTime;
    public static class OrderItem {
        @Field(type = FieldType.Keyword)
        private String itemName;
        @Field(type = FieldType.Integer)
        private Integer quantity;
    }
}

上面的代码展示了嵌套对象的映射声明方式。需要注意的是，OrderItem 作为静态内部类，框架能够正确解析其字段。如果内部类没有被 static 修饰，反射处理时会出现实例化问题，因此在实体类中的嵌套对象类建议都声明为 static。

注解配置与 JSON 映射的取舍

注解配置的最大优势在于类型安全和代码内聚。字段名变更时，映射同步更新，无需搜索 JSON 文件中对应的字段路径。对于大多数业务场景，注解配置足够覆盖需求。但有几种情况注解配置会显得力不从心。第一种是需要使用 Elasticsearch 高级特性但注解没有暴露对应属性时，比如字段的 term_vector、eager_global_ordinals、dynamic 策略等。第二种是索引需要精细控制映射，团队中负责索引管理的角色与编写 Java 代码的角色分离，直接维护 JSON 文件更符合工作流。第三种是索引映射需要复用，多个服务共享同一套索引定义，使用 JSON 文件比复制注解配置更可靠。

对于 JSON 映射的灵活控制需求，Spring Data Elasticsearch 也提供了对应的机制。可以通过 @Mapping 注解关联外部 JSON 文件，或者在应用启动时用 RestHighLevelClient 或 ElasticsearchClient 手动执行 put_mapping 请求。推荐的做法是：先用注解完成大部分映射，对于注解无法表达的细节，在索引创建完成后通过脚本或初始化代码补充设置。这样既保了类型安全，也兼顾了灵活性。

实际开发中还有一个容易被忽视的问题：当实体类字段与索引中已有映射不一致时，框架的自动创建不会覆盖已有索引的映射。如果字段类型发生变化，需要手动删除索引后重建，或者使用 reindex 流程迁移数据。因此在生产环境修改映射前，务必检查索引生命周期管理策略，避免数据丢失。

动态映射与字段命名策略

Elasticsearch 默认开启动态映射，即索引中出现未预先声明的字段时会自动推断类型。在 Spring Data Elasticsearch 中，这一行为可以通过 @Mapping 中的 dynamic 参数控制，但 @Document 注解本身没有直接暴露 dynamic 属性。如果你希望禁止动态映射，避免未声明的字段被自动索引导致映射膨胀，可以在创建索引时通过设置 dynamic = false 或 dynamic = strict 来限制。strict 模式最严格，文档中只要包含未声明的字段，写入操作就会报错。

字段命名策略影响 Java 属性名与索引字段名的对应关系。默认情况下，框架使用驼峰命名作为字段名，例如 Java 字段 createTime 对应索引中的 createTime。如果 Elasticsearch 索引中习惯使用下划线命名，可以设置 FieldNamingStrategy 为 SNAKE_CASE，这样 createTime 会映射为 create_time。这个配置可以通过 @Document 的 fieldNamingStrategy 属性来声明。需要注意的是，一旦修改了命名策略，已有的查询语句和聚合语句中的所有字段名都要同步调整，否则会查询不到数据。

@Document(indexName = "product_index", fieldNamingStrategy = FieldNamingStrategy.SNAKE_CASE)
public class Product {
    @Id
    private String id;
    @Field(type = FieldType.Text, analyzer = "ik_max_word")
    private String productName;
    @Field(type = FieldType.Keyword)
    private String category;
    @Field(type = FieldType.Double)
    private BigDecimal price;
    @Field(type = FieldType.Date, format = DateFormat.custom,
           pattern = "yyyy-MM-dd HH:mm:ss")
    private LocalDateTime updatedAt;
}

在上述示例中，productName 会被映射为 product_name，updatedAt 会被映射为 updated_at。search 查询构建时需要使用映射后的字段名，而不是 Java 属性名。Spring Data Elasticsearch 的 Criteria 查询和 NativeSearchQuery 查询对字段名的处理方式略有不同，使用 NativeSearchQuery 编写原生 JSON 查询时务必使用映射后的字段名。

总结起来，使用 Spring Data Elasticsearch 注解配置映射参数的核心在于理解 @Field 注解各属性对底层索引行为的影响。合理地使用 index、store、analyzer、format 等参数，可以在不大幅增加开发复杂度的情况下获得较好的查询性能和存储效率。对于注解无法覆盖的场景，保留 JSON 映射作为补充手段，形成一套既灵活又可控的索引映射管理方案。