使用 MongoDB Atlas Search 构建 Java 分面全文搜索 API

git clone https://github.com/luketn/atlas-search-coco 
cd atlas-search-coco
docker compose up java-app

/search?vehicle=car&text=red 

import java.util.Date;
import java.util.List;

public record Image(
       int _id,
       // 说明文字描述了图像的内容，可以使用全文搜索进行检索
       String caption,
       String url,
       int height,
       int width,
       Date dateCaptured,
       String licenseName,
       String licenseUrl,
       // 如果图像中包含人物，则为 true
       boolean hasPerson,
       // 以下字段为“超类”
       // 列表中的每一项都是一个类别
       // 图像中存在该类别下的一个或多个对象
       List<String> accessory,
       List<String> animal,
       List<String> appliance,
       List<String> electronic,
       List<String> food,
       List<String> furniture,
       List<String> indoor,
       List<String> kitchen,
       List<String> outdoor,
       List<String> sports,
       List<String> vehicle
) { }

public record Category(
       int _id,
       String superCategory,
       String name
) { }

docker run -d --name mongodb-atlas -p 27017:27017 mongodb/mongodb-atlas-local:8.2.6

mongodb://localhost:27017/?directConnection=true 

{
 "mappings": {
   "fields": {
     "caption": [{"type": "string"}],
     "hasPerson": {"type": "boolean"},
     "accessory": [{"type": "token"}, {"type": "stringFacet"}],
     "animal": [{"type": "token"}, {"type": "stringFacet"}],
     "appliance": [{"type": "token"}, {"type": "stringFacet"}],
     "electronic": [{"type": "token"}, {"type": "stringFacet"}],
     "food": [{"type": "token"}, {"type": "stringFacet"}],
     "furniture": [{"type": "token"}, {"type": "stringFacet"}],
     "indoor": [{"type": "token"}, {"type": "stringFacet"}],
     "kitchen": [{"type": "token"}, {"type": "stringFacet"}],
     "outdoor": [{"type": "token"}, {"type": "stringFacet"}],
     "sports": [{"type": "token"}, {"type": "stringFacet"}],
     "vehicle": [{"type": "token"}, {"type": "stringFacet"}]
   }
 }
}

"caption": [{"type": "string"}],

"hasPerson": {"type": "boolean"},

"accessory": [{"type": "token"}, {"type": "stringFacet"}],
...

[
 {
   "$search": {
     "facet": {
       "operator": {
         "compound": {
           "filter": [
             {
               "text": {
                 "path": "caption",
                 "query": "frisbee"
               }
             },
             {
               "equals": {
                 "path": "animal",
                 "value": "dog"
               }
             }
           ]
         }
       },
       "facets": {
         "animal": {
           "type": "string",
           "path": "animal",
           "numBuckets": 10
         },
         "sports": {
           "type": "string",
           "path": "sports",
           "numBuckets": 10
         }
       }
     },
     "count": {
       "type": "total"
     }
   }
 },
 {
   "$facet": {
     "docs": [],
     "meta": [
       {
         "$replaceWith": "$$SEARCH_META"
       },
       {
         "$limit": 1
       }
     ]
   }
 }
]

{
 "docs": [
   {
     "_id": 394,
     "caption": "A dog is holding a frisbee standing on grass.",
     ...
   },
   ...
 ],
 "meta": [
   {
     "count": { "total": { "$numberLong": "366" } },
     "facet": {
       "sports": {
         "buckets": [
           { "_id": "frisbee", "count": { "$numberLong": "364" } },
           ...
         ]
       },
       "animal": {
         "buckets": [
           { "_id": "dog", "count": { "$numberLong": "366" } }
         ]
       }
     }
   }
 ]
}
```## 3. Java 服务实现

好了！现在我们来实现 Java 服务类。我们直奔主题：Atlas Search 的语法非常复杂，特别是当你涉及多个复合子句和条件时。分面（Faceting）增加了额外的复杂性，而要在一次查询中同时获取搜索结果和分面数据，则进一步加剧了这种复杂性。我认为 MongoDB Java 驱动程序以及 Java 语言本身在几个方面有助于降低这种复杂性：

* **强类型**：一旦确定了数据模型，就可以轻松将其定义为不可变的 Java Record 类型，驱动程序将负责序列化/反序列化。有了这一基础，你就能确信业务逻辑代码是正确且安全的。
* **流式构建器语法**：Atlas Search 中需要使用的大多数操作都有辅助方法，可以帮助你组合搜索操作并构建查询。
* **出色的测试**：在用 NodeJS 和 Python 构建过类似的解决方案后，我发现 Java 在测试解决方案以及代码覆盖率和测试完整性的严谨性方面更容易实现，且支持更好。围绕搜索代码构建一套全面的测试对于明确代码意图、演练正常路径和边缘情况以及防止回归至关重要。

从基础开始，我们创建一个 `EntryPoint` 类，初始化 MongoDB 连接，并返回一些数据：

首先，在 Maven 的 `pom.xml` 中添加 MongoDB、JSON 序列化器（Jackson）以及一个简单的日志框架的依赖：

```xml
<dependencies>
   <dependency>
       <groupId>org.mongodb</groupId>
       <artifactId>mongodb-driver-sync</artifactId>
       <version>5.2.0</version>
   </dependency>
   <dependency>
       <groupId>com.fasterxml.jackson.core</groupId>
       <artifactId>jackson-databind</artifactId>
       <version>2.17.2</version>
   </dependency>
   <dependency>
       <groupId>org.slf4j</groupId>
       <artifactId>slf4j-simple</artifactId>
       <version>2.0.13</version>
   </dependency>
</dependencies>

package com.mycodefu;

import com.fasterxml.jackson.databind.ObjectMapper;
import com.mongodb.client.MongoClient;
import com.mongodb.client.MongoClients;
import com.mongodb.client.MongoCollection;
import com.mongodb.client.MongoDatabase;
import com.sun.net.httpserver.HttpServer;

import java.io.IOException;
import java.net.InetSocketAddress;
import java.net.URLDecoder;
import java.nio.charset.StandardCharsets;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.List;
import java.util.Map;
import java.util.stream.Collectors;

public class Main {

   public static void main(String[] args) throws IOException {

       String connectionString = "mongodb://localhost:27017";
       MongoClient mongoClient = MongoClients.create(connectionString);
       MongoDatabase database = mongoClient.getDatabase("atlasSearchCoco");
       MongoCollection<Category> categoryCollection = database.getCollection("category", Category.class);
       MongoCollection<Image> imageCollection = database.getCollection("image", Image.class);

       ObjectMapper objectMapper = new ObjectMapper();

       HttpServer httpServer = HttpServer.create(new InetSocketAddress("0.0.0.0", 8080), 0);

       httpServer.createContext("/categories", exchange -> {
           List<Category> categories = categoryCollection.find().into(new ArrayList<>());
           String categoriesJson = objectMapper.writeValueAsString(categories);
           byte[] categoriesJsonBytes = categoriesJson.getBytes();

           exchange.sendResponseHeaders(200, categoriesJsonBytes.length); 
           exchange.getResponseBody().write(categoriesJsonBytes);
           exchange.close();
       });

       httpServer.createContext("/images", exchange -> {
           Map<String, List<String>> params = Arrays.stream(exchange.getRequestURI().getQuery().split("&"))
                   .map(param -> param.split("=", 2))
                   .map(pair -> new String[]{
                           URLDecoder.decode(pair[0], StandardCharsets.UTF_8),
                           URLDecoder.decode(pair[1], StandardCharsets.UTF_8)
                   })
                   .collect(Collectors.groupingBy(
                           pair -> pair[0],
                           Collectors.mapping(
                                   pair -> pair[1],
                                   Collectors.toList()
                           )
                   ));

           //TODO: 根据查询参数实现图片搜索。目前我们只返回第一张图片。
           List<Image> images = imageCollection.find().limit(1).into(new ArrayList<>());
           //----------------

           String imagesJson = objectMapper.writeValueAsString(images);
           byte[] imagesJsonBytes = imagesJson.getBytes();

           exchange.sendResponseHeaders(200, imagesJsonBytes.length);
           exchange.getResponseBody().write(imagesJsonBytes);
           exchange.close();
       });

       httpServer.start();

       System.out.println("服务器启动于 http://localhost:8080");
       System.out.println("尝试访问分类列表: http://localhost:8080/categories");
       System.out.println("尝试搜索图片: http://localhost:8080/images?caption=motorcycle");
   }
}

       String connectionString = "mongodb://localhost:27017";
       MongoClient mongoClient = MongoClients.create(connectionString);
       MongoDatabase database = mongoClient.getDatabase("atlasSearchCoco");
       MongoCollection<Category> categoryCollection = database.getCollection("category", Category.class);
       MongoCollection<Image> imageCollection = database.getCollection("image", Image.class);

       HttpServer httpServer = HttpServer.create(new InetSocketAddress("0.0.0.0", 8080), 0);

       httpServer.createContext("/categories", exchange -> {
           List<Category> categories = categoryCollection.find().into(new ArrayList<>());
           String categoriesJson = objectMapper.writeValueAsString(categories);
           byte[] categoriesJsonBytes = categoriesJson.getBytes();

           exchange.sendResponseHeaders(200, categoriesJsonBytes.length);
           exchange.getResponseBody().write(categoriesJsonBytes);
           exchange.close();
       });
…
       httpServer.start();

httpServer.createContext("/images", exchange -> {
   Map<String, List<String>> params = Arrays.stream(exchange.getRequestURI().getQuery().split("&"))
           .map(param -> param.split("=", 2))
           .map(pair -> new String[]{
                   URLDecoder.decode(pair[0], StandardCharsets.UTF_8),
                   URLDecoder.decode(pair[1], StandardCharsets.UTF_8)
           })
           .collect(Collectors.groupingBy(
                   pair -> pair[0],
                   Collectors.mapping(
                           pair -> pair[1],
                           Collectors.toList()
                   )
           ));

   //TODO: 根据查询参数实现图片搜索。目前我们只返回第一张图片。
   List<Image> images = imageCollection.find().limit(1).into(new ArrayList<>());
   //----------------

   String imagesJson = objectMapper.writeValueAsString(images);
   byte[] imagesJsonBytes = imagesJson.getBytes();

   exchange.sendResponseHeaders(200, imagesJsonBytes.length);
   exchange.getResponseBody().write(imagesJsonBytes);
   exchange.close();
});

import java.util.List;

public record ImageSearchResult(List<Image> docs, List<ImageMeta> meta) {
   public record ImageMeta (ImageMetaTotal count, ImageMetaFacets facet) { }
   public record ImageMetaTotal (long total) { }
   public record ImageMetaFacets (
           ImageMetaFacet accessory,
           ImageMetaFacet animal,
           ImageMetaFacet appliance,
           ImageMetaFacet electronic,
           ImageMetaFacet food,
           ImageMetaFacet furniture,
           ImageMetaFacet indoor,
           ImageMetaFacet kitchen,
           ImageMetaFacet outdoor,
           ImageMetaFacet sports,
           ImageMetaFacet vehicle
   ) { }
   public record ImageMetaFacet (List<ImageMetaFacetBucket> buckets) { }
   public record ImageMetaFacetBucket (String _id, long count) { }
}

private static ImageSearchResult search(MongoCollection<Image> imageCollection, String caption, Integer page, Boolean hasPerson, List<String> accessory, List<String> animal, List<String> appliance, List<String> electronic, List<String> food, List<String> furniture, List<String> indoor, List<String> kitchen, List<String> outdoor, List<String> sports, List<String> vehicle) {
   int skip = 0;
   int pageSize = 5;
   if (page != null) {
       skip = page * pageSize;
   }

   List<SearchOperator> clauses = new ArrayList<>();
   if (caption != null) {
       clauses.add(SearchOperator
               .text(
                       fieldPath("caption"),
                       caption
               )
       );
   }
   if (hasPerson != null) {
       clauses.add(equals("hasPerson", hasPerson));
   }
   BiConsumer<String, List<String>> addConditional = (String category, List<String> values) -> {
       if (values != null) {
           for (String value : values) {
               clauses.add(equals(category, value));
           }
       }
   };
   addConditional.accept("accessory", accessory);
   addConditional.accept("animal", animal);
   addConditional.accept("appliance", appliance);
   addConditional.accept("electronic", electronic);
   addConditional.accept("food", food);
   addConditional.accept("furniture", furniture);
   addConditional.accept("indoor", indoor);
   addConditional.accept("kitchen", kitchen);
   addConditional.accept("outdoor", outdoor);
   addConditional.accept("sports", sports);
   addConditional.accept("vehicle", vehicle);

   List<StringSearchFacet> facets = List.of(
           stringFacet("accessory", fieldPath("accessory")).numBuckets(10),
           stringFacet("animal", fieldPath("animal")).numBuckets(10),
           stringFacet("appliance", fieldPath("appliance")).numBuckets(10),
           stringFacet("electronic", fieldPath("electronic")).numBuckets(10),
           stringFacet("food", fieldPath("food")).numBuckets(10),
           stringFacet("furniture", fieldPath("furniture")).numBuckets(10),
           stringFacet("indoor", fieldPath("indoor")).numBuckets(10),
           stringFacet("kitchen", fieldPath("kitchen")).numBuckets(10),
           stringFacet("outdoor", fieldPath("outdoor")).numBuckets(10),
           stringFacet("sports", fieldPath("sports")).numBuckets(10),
           stringFacet("vehicle", fieldPath("vehicle")).numBuckets(10)
   );

   List<Bson> aggregateStages = List.of(
           Aggregates.search(
                   SearchCollector.facet(
                           SearchOperator.compound().filter(clauses),
                           facets
                   ), SearchOptions.searchOptions().count(SearchCount.total())),
           Aggregates.skip(skip),
           Aggregates.limit(pageSize),
           Aggregates.facet(
                   new Facet("docs", List.of()),
                   new Facet("meta", List.of(
                           Aggregates.replaceWith("$$SEARCH_META"),
                           Aggregates.limit(1)
                   ))
           )
   );

   ImageSearchResult imageSearchResult = imageCollection.aggregate(aggregateStages, ImageSearchResult.class).first();

   return imageSearchResult;
}

private static SearchOperator equals(String fieldName, Object value) {
   return SearchOperator.of(
           new Document("equals", new Document()
                   .append("path", fieldName)
                   .append("value", value)
           ));
}

ImageSearchResult images = search(imageCollection,
       params.containsKey("caption") ? params.get("caption").getFirst() : null,
       params.containsKey("page") ? Integer.parseInt(params.get("page").getFirst()) : null,
       params.containsKey("hasPerson") ? Boolean.parseBoolean(params.get("hasPerson").getFirst()) : null,
       params.get("accessory"),
       params.get("animal"),
       params.get("appliance"),
       params.get("electronic"),
       params.get("food"),
       params.get("furniture"),
       params.get("indoor"),
       params.get("kitchen"),
       params.get("outdoor"),
       params.get("sports"),
       params.get("vehicle")
);

[
 {
   $search: {
     facet: {
       operator: {
         compound: {
           filter: [ <在此处放入过滤子句！> ]
         }
       },
       facets: { <列出我们希望返回的分面> }
     }
   }
 }, 
 <分页>
 {"$skip": 0},{"$limit": 5},
 <返回结构 - 文档页 + 元数据（分面计数）>
 {$facet: {docs: [], meta: [...]}}
]

   int skip = 0;
   int pageSize = 5;
   if (page != null) {
       skip = page * pageSize;
   }

   List<SearchOperator> clauses = new ArrayList<>();
   // ... (代码见上文)

   List<StringSearchFacet> facets = List.of(
           stringFacet("accessory", fieldPath("accessory")).numBuckets(10),
           // ... (其他分面)
   );

// ... (代码见上文)