NoSQL 与搜索 / 系统课时
搜索服务接口设计
搜索服务接口设计
搜索功能一旦直接返回 Elasticsearch 的查询与命中对象,业务层就会被客户端版本、索引字段和查询 DSL 绑定。本课将设计请求对象、结果对象与访问层边界,并用可运行示例验证业务模块只依赖稳定的领域接口。
学习目标
- 设计不泄漏 Elasticsearch 类型的搜索请求与结果对象
- 划分应用服务、搜索网关和基础设施适配器的职责
- 通过映射层隔离索引字段、分页和排序细节
先确定接口边界
业务调用方通常只需要关键词、筛选条件、分页参数和业务排序,不需要知道 BoolQuery、SearchResponse 或索引名称。接口应表达“要搜索什么”,而不是“如何拼装 Elasticsearch 请求”。
| 边界 | 可以暴露 | 不应暴露 |
|---|---|---|
| 业务请求 | 关键词、分类、页码、每页数量 | Query DSL、索引名、客户端对象 |
| 业务结果 | 业务 ID、展示字段、总数 | _source、SearchHit、分片信息 |
| 基础设施层 | 查询构造、字段映射、客户端调用 | 直接进入控制器或领域对象 |

这条边界让索引改名、字段重构或客户端升级集中在适配器内部。业务层只要请求与结果语义不变,就不需要跟随底层实现调整。
定义稳定的请求与结果
下面的单文件示例定义业务请求、分页结果、领域视图、搜索网关和应用服务。FakeSearchGateway 代替真实 Elasticsearch 适配器,因此代码可直接编译运行,同时清楚展示对象转换位置。
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);
}
}预期输出:
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 请求。