NoSQL 与搜索 / 系统课时

搜索服务接口设计

搜索服务接口设计

搜索功能一旦直接返回 Elasticsearch 的查询与命中对象,业务层就会被客户端版本、索引字段和查询 DSL 绑定。本课将设计请求对象、结果对象与访问层边界,并用可运行示例验证业务模块只依赖稳定的领域接口。

学习目标

  • 设计不泄漏 Elasticsearch 类型的搜索请求与结果对象
  • 划分应用服务、搜索网关和基础设施适配器的职责
  • 通过映射层隔离索引字段、分页和排序细节

先确定接口边界

业务调用方通常只需要关键词、筛选条件、分页参数和业务排序,不需要知道 BoolQuery、SearchResponse 或索引名称。接口应表达“要搜索什么”,而不是“如何拼装 Elasticsearch 请求”。

边界 可以暴露 不应暴露
业务请求 关键词、分类、页码、每页数量 Query DSL、索引名、客户端对象
业务结果 业务 ID、展示字段、总数 _source、SearchHit、分片信息
基础设施层 查询构造、字段映射、客户端调用 直接进入控制器或领域对象

搜索服务的分层与对象转换关系

这条边界让索引改名、字段重构或客户端升级集中在适配器内部。业务层只要请求与结果语义不变,就不需要跟随底层实现调整。

定义稳定的请求与结果

下面的单文件示例定义业务请求、分页结果、领域视图、搜索网关和应用服务。FakeSearchGateway 代替真实 Elasticsearch 适配器,因此代码可直接编译运行,同时清楚展示对象转换位置。

java
import java.util.List;
import java.util.Locale;

public class SearchServiceDemo {

    record ProductSearchRequest(String keyword, String category, int page, int size) {}

    record ProductView(String id, String name, String category) {}

    record SearchPage<T>(List<T> items, long total, int page, int size) {}

    record SearchSpec(String normalizedKeyword, String category, int from, int size) {}

    record ProductDocument(String id, String productName, String categoryCode) {}

    interface ProductSearchGateway {
        SearchPage<ProductDocument> search(SearchSpec spec);
    }

    static final class ProductSearchService {
        private final ProductSearchGateway gateway;

        ProductSearchService(ProductSearchGateway gateway) {
            this.gateway = gateway;
        }

        SearchPage<ProductView> search(ProductSearchRequest request) {
            if (request.page() < 1 || request.size() < 1 || request.size() > 100) {
                throw new IllegalArgumentException("page must be >= 1 and size must be 1..100");
            }

            String keyword = request.keyword() == null
                    ? ""
                    : request.keyword().trim().toLowerCase(Locale.ROOT);
            int from = (request.page() - 1) * request.size();

            SearchPage<ProductDocument> documents = gateway.search(
                    new SearchSpec(keyword, request.category(), from, request.size())
            );

            List<ProductView> views = documents.items().stream()
                    .map(document -> new ProductView(
                            document.id(),
                            document.productName(),
                            document.categoryCode()))
                    .toList();

            return new SearchPage<>(views, documents.total(), request.page(), request.size());
        }
    }

    static final class FakeSearchGateway implements ProductSearchGateway {
        private final List<ProductDocument> data = List.of(
                new ProductDocument("p-1", "Mechanical Keyboard", "computer"),
                new ProductDocument("p-2", "Wireless Mouse", "computer"),
                new ProductDocument("p-3", "Coffee Mug", "home")
        );

        @Override
        public SearchPage<ProductDocument> search(SearchSpec spec) {
            List<ProductDocument> matched = data.stream()
                    .filter(document -> spec.category() == null
                            || spec.category().equals(document.categoryCode()))
                    .filter(document -> document.productName()
                            .toLowerCase(Locale.ROOT)
                            .contains(spec.normalizedKeyword()))
                    .toList();

            int end = Math.min(spec.from() + spec.size(), matched.size());
            List<ProductDocument> pageItems = spec.from() >= matched.size()
                    ? List.of()
                    : matched.subList(spec.from(), end);

            return new SearchPage<>(pageItems, matched.size(), 0, spec.size());
        }
    }

    public static void main(String[] args) {
        ProductSearchService service = new ProductSearchService(new FakeSearchGateway());
        SearchPage<ProductView> result = service.search(
                new ProductSearchRequest("mouse", "computer", 1, 10)
        );

        System.out.println("total=" + result.total());
        result.items().forEach(System.out::println);
    }
}

预期输出:

text
total=1
ProductView[id=p-2, name=Wireless Mouse, category=computer]

真实适配器只需实现 ProductSearchGateway:把 SearchSpec 转换为 Elasticsearch 查询,再把命中数据映射成 ProductDocument。控制器、应用服务和业务对象都不应导入 Elasticsearch 客户端包。

处理分页、排序与高亮

分页参数应在应用服务入口统一校验,避免任意大页导致资源消耗。接口可以暴露业务排序枚举,例如 RELEVANCE、NEWEST、PRICE_ASC,再由适配器映射到底层字段;不要让调用方直接提交任意字段名。

高亮也是同样原则。业务若需要展示命中片段,可以在结果中定义 highlightText,但不要返回 Elasticsearch 的高亮字段 Map。这样即使以后改用其他搜索引擎,接口语义仍然稳定。

错误与可演进性

网关应把底层异常转换成少量稳定异常,例如“请求无效”“搜索暂不可用”和“结果解析失败”。不要把节点地址、分片异常或客户端堆栈直接暴露给业务响应;这些细节应进入日志并关联追踪 ID。

接口演进时优先增加可选筛选条件或新的结果字段,避免改变已有字段含义。索引字段名、分析器和查询权重属于适配器配置,不应成为公共 API 的一部分。

本课总结

  • 搜索接口应表达业务意图,而不是暴露查询 DSL 和客户端对象
  • 应用服务负责校验与业务映射,网关负责稳定边界,适配器负责 Elasticsearch 细节
  • 分页、排序、高亮和异常都应转换为稳定的业务语义

下一课预告

下一课将基于这一接口边界实现查询构建与结果映射,把关键词、筛选和排序转换为真实的 Elasticsearch 请求。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

搜索服务接口设计

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通