视频系统 on 方糖猫Blog

视频系统 DDD 实战：巴西 IPTV 项目的领域拆分

Fri, 23 Aug 2024 17:00:00 +0800

视频系统 DDD 实战：巴西 IPTV 项目的领域拆分

2021 年到 2025 年，我负责面向巴西市场的 IPTV 视频点播系统。这是一个用户量过百万、业务持续演进的系统。在几次大的产品迭代中，我们引入了领域驱动设计（DDD）来控制系统复杂度。这篇文章会完整复盘当时的领域拆分过程。

一、项目背景

系统核心功能：

视频上传：支持 tus / FTP / 网盘 / m3u8 等多种来源
视频转码：h264 / h265 多码率输出
DRM 加密：永新 / 自研加密方案
元数据管理：同步 IMDb / TMDB / PP 等外部数据源
播放列表：专题、分类、推荐
播放鉴权：用户权限、设备管理、防盗链

服务用户：200 万+，峰值日活 40 万。

二、为什么需要 DDD？

2.1 早期的问题

系统最初是一个单体应用，模块按技术分层组织：

controller/
service/
dao/
entity/

这种结构在业务简单时没问题，但随着功能增加，开始出现：

一个需求改动涉及多个「层」，改哪里不确定
业务逻辑散落在 Service 中，相似功能重复实现
转码、鉴权、元数据互相耦合，改一个模块影响多个模块
新成员上手慢，需要全局理解才敢改代码

2.2 DDD 带来的改变

DDD 不是银弹，但它帮我们做了两件事：

按业务边界组织代码，而不是按技术分层
显式定义领域概念，让业务逻辑有明确的归属

三、领域划分

3.1 核心域识别

我们先识别出系统的核心业务域：

flowchart TD
    content["内容域 (Content)<br/>媒资管理、视频文件、转码任务、DRM 加密"]
    metadata["元数据域 (Metadata)<br/>影片信息、演员、分类、标签、外部数据源同步"]
    playback["播放域 (Playback)<br/>播放鉴权、播放地址生成、防盗链、码率适配"]
    user["用户域 (User)<br/>用户账户、订阅、设备、播放历史"]
    recommendation["推荐域 (Recommendation)<br/>播放列表、专题、个性化推荐"]
    billing["计费域 (Billing)<br/>套餐、订单、支付、用量统计"]
    content --- metadata --- playback --- user --- recommendation --- billing

3.2 域间关系

flowchart LR
    playback["播放域"] -- 依赖 --> content["内容域"]
    playback -- 依赖 --> user["用户域"]
    recommendation["推荐域"] -- 依赖 --> metadata["元数据域"]
    recommendation -- "依赖（获取热门数据）" --> playback
    billing["计费域"] -- 依赖 --> user
    metadata -- 依赖 --> external["外部数据源"]

依赖方向尽量保持单向，避免循环依赖。

四、内容域详细设计

内容域是最复杂的域之一，我们以它为例展开。

4.1 聚合根设计

flowchart TD
    root["MediaAsset（媒资聚合根）"]
    file["MediaFile（视频文件）"]
    raw["原始文件"]
    transcoded["转码后文件（多码率）"]
    drmfile["DRM 加密文件"]
    job["TranscodingJob（转码任务）"]
    license["DrmLicense（DRM 许可证信息）"]
    root --> file
    file --> raw
    file --> transcoded
    file --> drmfile
    root --> job
    root --> license

MediaAsset 是聚合根，外部系统只能通过它访问内部实体。

4.2 关键领域事件

内容域会产生大量领域事件，其他域可以订阅：

事件	含义	订阅方
`MediaAssetUploaded`	媒资上传完成	转码服务
`TranscodingCompleted`	转码完成	内容域自身、播放域
`DrmEncryptionCompleted`	DRM 加密完成	播放域
`MetadataSynced`	元数据同步完成	推荐域
`MediaAssetPublished`	媒资发布上线	推荐域、搜索服务

4.3 状态流转

媒资从上传到发布的状态机：

flowchart TD
    UPLOADED --> PENDING_TRANSCODE --> TRANSCODING --> PENDING_DRM --> DRM_ENCRYPTED --> PENDING_METADATA --> METADATA_READY --> FINAL["PUBLISHED / REJECTED"]

每个状态变更都通过领域事件触发下一步操作。

五、分层架构

每个领域内部采用 DDD 经典四层架构：

flowchart TD
    ui["用户接口层<br/>REST Controller / DTO"]
    app["应用层<br/>Application Service / 用例编排"]
    domain["领域层<br/>Entity / Value Object / Domain Service / Repository Interface / Domain Event"]
    infra["基础设施层<br/>Repository Impl / MQ Client / External API Client / DB / Cache"]
    ui --- app --- domain --- infra

5.1 领域层示例

public class MediaAsset {
    private MediaAssetId id;
    private String title;
    private MediaStatus status;
    private List<MediaFile> files;
    private List<TranscodingJob> transcodingJobs;

    public void upload(MediaFile file) {
        this.files.add(file);
        this.status = MediaStatus.UPLOADED;
        registerEvent(new MediaAssetUploadedEvent(this.id));
    }

    public void completeTranscoding(TranscodingJob job) {
        this.transcodingJobs.add(job);
        this.status = MediaStatus.TRANSCODING_COMPLETED;
        registerEvent(new TranscodingCompletedEvent(this.id, job.getOutputFiles()));
    }
}

5.2 防腐层设计

与外部系统（IMDb / TMDB / PP）对接时，使用防腐层（Anti-Corruption Layer）：

public interface MetadataSourceClient {
    ExternalMetadata fetch(String externalId);
}

// IMDb 适配器
public class ImdbClientAdapter implements MetadataSourceClient {
    private final ImdbApiClient imdbClient;

    @Override
    public ExternalMetadata fetch(String externalId) {
        ImdbResponse response = imdbClient.fetch(externalId);
        return MetadataConverter.fromImdb(response);
    }
}

这样外部 API 的数据结构变化不会直接影响到我们内部的元数据模型。

六、微服务拆分过程

6.1 第一次拆分：按技术边界

早期我们按技术栈拆：

upload-service
transcoding-service
metadata-service
playback-service

结果导致一个业务操作要跨多个服务，分布式事务复杂。

6.2 第二次拆分：按领域边界

调整后按 DDD 领域拆分：

content-service（内容域）
metadata-service（元数据域）
playback-service（播放域）
user-service（用户域）
recommendation-service（推荐域）
billing-service（计费域）

每个服务有清晰的业务边界和聚合根。

6.3 服务间通信

场景	通信方式	说明
领域事件传播	RocketMQ	异步、最终一致
同步查询	HTTP / gRPC	强一致查询
配置/字典数据	Redis 缓存	高频读取

七、领域事件实现

7.1 事件定义

public class TranscodingCompletedEvent extends DomainEvent {
    private final MediaAssetId mediaAssetId;
    private final List<FileUrl> outputFiles;
    private final Instant completedAt;
}

7.2 事件发布

领域层只负责注册事件，应用层统一发布：

@Transactional
public void handleTranscodingCallback(TranscodingJobId jobId, List<FileUrl> outputs) {
    MediaAsset asset = mediaAssetRepository.findByJobId(jobId);
    asset.completeTranscoding(new TranscodingJob(jobId, outputs));

    mediaAssetRepository.save(asset);
    eventPublisher.publish(asset.getDomainEvents());
    asset.clearDomainEvents();
}

7.3 事件消费

@Component
public class PlaybackEventListener {

    @RocketMQMessageListener(topic = "content-events", selectorExpression = "TranscodingCompleted")
    public class Listener implements RocketMQListener<TranscodingCompletedEvent> {
        @Override
        public void onMessage(TranscodingCompletedEvent event) {
            playbackService.preparePlayUrls(event.getMediaAssetId(), event.getOutputFiles());
        }
    }
}

八、几次关键演进

8.1 从单体到领域化单体

第一步不是拆微服务，而是先在单体内部按领域组织代码包：

com.ftmao.iptv.content
com.ftmao.iptv.metadata
com.ftmao.iptv.playback

这样可以在不引入分布式复杂度的前提下，先验证领域划分是否合理。

8.2 从同步调用到事件驱动

转码完成后，原本播放域通过接口轮询内容域查询状态。后来改为内容域发布 TranscodingCompleted 事件，播放域订阅。

收益：

内容域和播放域解耦
新增订阅方不需要改内容域
系统扩展性更好

8.3 引入 CQRS 处理播放查询

播放接口对性能要求很高，我们单独做了读模型：

写模型：MediaAsset 聚合根
读模型：Redis 中的播放信息缓存

当内容发布或更新时，通过事件同步更新读模型。

九、踩过的坑

9.1 领域划分过细

早期我们划分了 10 多个领域，导致服务数量爆炸，运维成本剧增。

教训：领域数量要匹配团队规模。小团队 4-6 个领域足够。

9.2 领域事件丢失

消息队列配置不当，出现过领域事件丢失，导致播放域看不到新发布的内容。

教训：关键领域事件必须持久化，支持重放和补偿。

9.3 贫血领域模型

很多「DDD」项目最后变成了 Transaction Script 套壳，实体只有 getter/setter。

教训：要把业务规则和状态变更放在领域对象里，而不是 Service 里。

9.4 过度设计聚合根

一开始想把所有内容相关的东西都放到 MediaAsset 聚合根里，结果聚合根过大，事务边界混乱。

教训：聚合根要小而聚焦，跨聚合用领域事件协作。

十、效果与反思

10.1 量化效果

指标	优化前	优化后
新需求平均改动文件数	40 个	20 个
线上因耦合导致的 Bug	10 次/月	2 次/月
新成员独立上手时间	3 周	1 周

10.2 核心反思

DDD 不是先拆分微服务，而是先拆清楚业务边界。微服务是结果，不是起点。
领域事件是域间协作的核心，但事件丢失和顺序问题必须重视。
不要追求完美的领域模型，先有一个可用的模型，再迭代优化。
DDD 需要团队共识，不是架构师一个人画几张图就行的。

十一、总结

巴西 IPTV 项目让我对 DDD 有了真实的体感。它不是教科书上的概念，而是解决复杂业务系统演化问题的工程方法。

对于视频系统这类业务复杂、流程长、多团队协作的系统，DDD 能带来的最大价值是：

让每个业务概念都有清晰的归属
让系统变更的影响范围可控
让新成员能更快理解业务

如果你也在做 DDD 实践，欢迎在评论区交流领域划分和事件驱动的经验。

Elasticsearch 从原理到 IPTV 媒资搜索实战：基于 ftmao-meta 项目的完整复盘

Sat, 28 Aug 2021 14:00:00 +0800

Elasticsearch 从原理到 IPTV 媒资搜索实战：基于 ftmao-meta 项目的完整复盘

以我们线上运行的 IPTV 媒资元数据服务 ftmao-meta 为样本，讲清楚一个真实的 ES（实际为 AWS 托管 OpenSearch）应用是怎么设计索引、同步数据、支撑搜索和下游订阅的。所有配置、代码、索引设计均来自项目本身，踩过的坑也一并奉上。

一、项目背景：这是一个什么系统

ftmao-meta 是一个面向多地区运营的 IPTV/OTT 视频内容平台的媒资元数据微服务，Spring Boot 3.3 + Java 21，单模块 Gradle 工程，包结构 gtt.ftmao.meta，分 api / app / bean / core 四层。它管理的数据包括：

影视元数据：电影、剧集、季、集、短视频的多语言标题、简介、海报、演职员、分级、票房；
演职人员：多语言姓名、热度值（pgcHot / ugcHot / imdbHot）、代表作；
物料：剧照海报（artwork）、预告片（trailer）；
C 端搜索：全文检索 + 输入自动补全。

这些数据量巨大（千万级文档）、多语言（英语/西语/葡语，服务拉美市场）、多租户（多家运营商公司共用），而且需要被下游多个服务增量订阅。MySQL 是事实源（Source of Truth），ES 承担所有读路径的检索。

技术选型上的关键事实：

后端是 AWS 托管 OpenSearch，客户端用官方 opensearch-java 2.8.1（org.opensearch.client.opensearch.OpenSearchClient），没有用 spring-data-elasticsearch，也没有 RestHighLevelClient；
全文检索与自动补全能力封装在公司内部库 searchengine-api/core/sync 里，业务代码只调用 SearchApi / SearchSync 门面；
数据同步不走 MQ（Kafka 依赖在启动类里被显式排除），而是"MySQL 任务表 + 定时轮询 + 分布式锁"。

graph TB
    subgraph 上游["上游数据来源"]
        BOSS["运营后台 / 内容录入"]
        PP["PP 开放平台<br/>（REST 拉取外部媒资）"]
    end

    subgraph META["ftmao-meta 服务"]
        API["REST API 层"]
        SVC["业务 Service<br/>MetaService / ArtworkService ..."]
        JOB["定时 Job<br/>PpMetaSyncJob 每 15s"]
        LOCK["分布式锁<br/>AsyncJobExecutorManager"]
    end

    subgraph STORE["存储层"]
        MYSQL[("MySQL<br/>事实源 + 同步任务表")]
        subgraph OS["AWS OpenSearch"]
            DETAIL["meta_detail_index<br/>媒资详情（重索引）"]
            PERSON["meta_person_index<br/>人物详情"]
            ART["meta_artwork_index<br/>剧照物料"]
            TRAILER["meta_trailer_index<br/>预告片"]
            SEARCH["search_engine_index<br/>C端搜索（轻索引）"]
        end
    end

    subgraph DOWN["下游消费方"]
        PORTAL["门户/推荐服务"]
        SUB["增量订阅方<br/>（时间水位拉取变更）"]
    end

    BOSS --> SVC
    PP --> JOB
    SVC -->|"事务内：先写库，再直写 ES"| MYSQL
    SVC --> DETAIL
    SVC --> SEARCH
    JOB --> LOCK --> MYSQL
    JOB -->|"批量灌入"| SEARCH
    API -->|"全文搜索/补全"| SEARCH
    API -->|"mget 回查详情"| DETAIL
    API --> PERSON & ART & TRAILER
    DETAIL -->|"lastModifiedIndicator 水位"| SUB
    SEARCH --> PORTAL

二、先补原理：理解后面设计决策的三个支点

在进入项目细节前，用三句话回顾《Elasticsearch in Action》里最重要的原理，后面每个设计决策都会用到它们。

2.1 倒排索引与分词

ES 搜索快的根本原因是倒排索引：term → 文档列表。而文本进入倒排索引前要经过分析链：

graph LR
    A["原始文本<br/>O Auto da Compadecida"] --> B["Character Filter<br/>变音符号映射 á→a"]
    B --> C["Tokenizer<br/>standard 分词"]
    C --> D["Token Filter<br/>lowercase + stopword + stemmer"]
    D --> E["词项 Term<br/>auto / compadecida"]

一个字段建索引时用哪个 analyzer、搜索时用哪个 analyzer，直接决定了"搜不搜得到"。这就是为什么 mapping 必须在灌数据之前设计好——改 analyzer 意味着重建索引。

2.2 近实时（NRT）与 refresh

文档写入后先进内存缓冲区，默认 1 秒后 refresh 生成 segment 才可被搜索。批量灌数据时调大 refresh_interval、或显式控制 refresh 时机，是写入性能优化的第一手段——后面会看到项目里批量写入怎么用它。

2.3 Query 与 Filter 的区别

Query：算相关性得分 _score，用于全文匹配排序；
Filter：只判断 yes/no，不算分、结果可被缓存，用于精确过滤。

项目里几乎所有查询都是"filter 套 query"的 bool 结构：关键词进 must，租户、类型、软删除标记进 filter。

三、索引设计：一个搜索索引 + 四个详情索引

3.1 索引清单

项目中没有任何 @Document 注解或 mapping JSON 文件，索引 DDL 采用类似 Liquibase 的 changelog 形式管理（changelog/elasticsearch/*.yaml，HTTP method + path + body，由外部部署工具执行），别名字段统一管理：

代码中的别名	实体索引	分片	存什么
`meta_detail_index`	`ftmao-meta-detail-1`	6 主 2 副	媒资详情全集
`meta_person_index`	`ftmao-meta-person-detail`	6 主 2 副	演职人员详情
`meta_artwork_index`	`ftmao-meta-media-artwork`	6 主 2 副	剧照物料
`meta_trailer_index`	`ftmao-meta-media-trailer`	6 主 2 副	预告片
`search_engine_index`	`ftmao-meta-search-engine`	1 分片	C 端搜索/补全

别名与文档类的映射集中在一个枚举里（OpenSearchIndexEnum），业务代码只认别名——这是"换索引不改代码"的基本功，比如 ftmao-meta-detail-1 后面出现 -2，只需要 reindex 后切别名。

3.2 详情索引：重存储、轻检索

meta_detail_index 的 mapping 有个鲜明特征：几乎所有字段都是 keyword，标题、剧情简介都是 keyword + nested，不参与分词检索，大量 nested 对象（displayTitles / plots / posters / casts）配 dynamic: false。

为什么？因为详情索引的职责是**“按 ID/结构化条件精确取数”**，不是全文搜索。keyword 不做分词，聚合、terms 过滤、精确匹配都快；dynamic: false 防止上游数据乱塞字段把 mapping 撑爆（mapping explosion 是生产事故常客）。

3.3 搜索索引：整个项目最精彩的部分

search_engine_index 只有 1 个分片（轻量、追求查询 RT），但它的 analysis 配置是整个项目技术含量最高的地方。以主搜索字段 mainTitle 为例：

# 摘自 changelog（简化）
mainTitle:
  type: text
  store: true
  term_vector: with_positions_offsets   # 为 fast-vector-highlighter 高亮做准备
  analyzer: en_es_pt                     # 英/西/葡三语混合分词器
  fields:
    cut_word:    { analyzer: en_es_pt }              # 正常分词匹配
    all_letters: { analyzer: N_gram(4-15) }          # 长 ngram：前缀/模糊匹配
    word_letters:{ analyzer: N_gram(2-10) }          # 短 ngram：更激进的模糊匹配
    origin:      { type: keyword, normalizer: lowercase }  # 精确匹配/排序

配套自定义组件：

多语分析器 en_es_pt：standard tokenizer + 英语/西语/葡语三套 stopword + stemmer；
变音符号 char_filter：把 áéíóúàèç 等西葡变音符号映射为 ASCII——拉美用户搜 compadecida 也能命中 Compadecida，对多语言市场这是体验生死线；
ngram tokenizer 一批（1–10、4–15 等不同窗口），max_ngram_diff=14；
completion suggester：suggest 字段配 suggester_trigram 分析器，带 3 个 category context（markCate / tenantCate / comboCate）——自动补全可以按内容类型和租户隔离，A 运营商的用户不会看到 B 运营商专有的片名提示。

设计启示：一个"能搜"的字段，实际需要四层子字段分工——正常分词管召回、长 ngram 管前缀联想、短 ngram 管纠错、keyword 管精确和排序。这也正是《Elasticsearch in Action》里"多字段映射"思想的生产级演绎。

3.4 双索引架构：为什么搜索和详情要分开

graph LR
    subgraph 写入["写入侧"]
        D["MetaDetail 完整文档<br/>（几十 KB，含 nested 海报/演员/多语言）"] --> DETAIL["详情索引<br/>6分片 重存储"]
        D -->|"裁剪：docId + mainTitle +<br/>suggest + 过滤字段 + 租户"| SEARCH["搜索索引<br/>1分片 轻量"]
    end
    subgraph 查询["查询侧"]
        U["用户搜索 'auto'"] -->|"① matchSearch 命中<br/>返回 docId 列表"| SEARCH
        SEARCH -->|"② 按 docId mget"| DETAIL
        DETAIL -->|"组装完整详情返回"| U
    end

搜索索引里不存详情，只有：docId、mainTitle（及 ngram 子字段）、suggest、40+ 个 keyword 过滤字段（ext-field-to-index-map 里配置，如媒资类型、地区、年份、分级）、租户字段。好处有三个：

搜索索引小，1 个分片 + 内存友好，C 端 QPS 扛得住；
详情变更不用动搜索索引——海报换了只 update 详情索引；搜索索引只在标题/过滤字段变化时更新；
两类索引可以独立扩缩容、独立重建。

代价也很明显：多一次 mget 回查、数据一致性要维护两份。这个项目用下一节的同步机制来兜底。

四、数据同步：MySQL → ES 的三条路径

ES 是"读模型"，MySQL 才是事实源。项目没用 Canal/MQ，而是自己实现了一套事务内直写 + 任务表轮询的混合方案：

flowchart TD
    A["业务写请求<br/>MetaService.save()"] --> B{"@Transactional"}
    B --> C["① 写 MySQL 业务表"]
    B --> D["② 写 MySQL 同步任务表<br/>MixedMetaSyncTask"]
    B --> E["③ 同事务内直写详情索引<br/>bulkOperationByBatch(refresh=True)"]
    B --> F["④ saveMetaToSearchEngine<br/>同步搜索索引"]
    E --> G{"ES 写失败?"}
    G -->|"是，事务回滚或留下任务"| H["任务表残留记录"]
    D --> I["PpMetaSyncJob<br/>@Scheduled 每 15s"]
    H --> I
    I --> J["分布式锁<br/>executeWithLock"]
    J --> K["MetaTaskProcessService<br/>分批 Lists.partition(batchSize)"]
    K -->|"searchSync.save(batch)"| L["搜索索引"]
    M["失败重试 Job<br/>每小时"] --> J

三条路径各有分工：

同事务直写（主路径）：保证"后台保存完，前台立刻能搜到"。写入时统一刷新 updateTime 和 lastModifiedIndicator（格式：时间戳_docId 的版本游标，下一节详述）；
任务表 + 定时轮询（兜底路径）：15 秒一轮，分布式锁防多实例并发，分批灌入；
失败重试 Job（保险）：每小时扫描失败任务重放。

为什么不纯用 MQ？ 这个系统的写入量级不大（媒资是低频高价值数据，不是日志），事务内直写的一致性收益远大于引入 MQ 的复杂度。这是"按场景选方案"而不是"按潮流选方案"的好例子。

4.1 批量写入的性能细节

工具类 OpenSearchUtil.bulkUpsertDocuments 里有两个值得抄的实践：

// 按配置的 bulkSize（默认 200）分批，避免单个 bulk 过大压垮集群
// 每批显式 refresh(WaitFor)：写完后“等 refresh 完成再返回”，
// 保证同步接口的调用方“写完立即可见”，同时比 refresh=true（每文档刷新）省资源

对照第 2.2 节的 NRT 原理：refresh=WaitFor 是吞吐和可见性之间的甜点——批量场景不要无脑 refresh=true。

五、查询实战：从业务代码反推 ES 用法

5.1 一切查询的起点：软删除过滤

项目里文档不物理删除，而是软删除——所有读路径都要叠一层 isDeleted=0：

// OpenSearchUtil.getUndeletedQuery：所有查询都要过这层包装
Query undeletedQuery = openSearchUtil.getUndeletedQuery(boolQueryBuilder.build()._toQuery());
// 底层就是 bool.filter(terms(isDeleted, [0]))，可能再叠加 status=1（已发布）

业务侧的典型用法（ArtworkService，按媒资 ID 查剧照）：

Query metaIdQuery = Query.of(q -> q.terms(t -> t.field("metaId")
    .terms(tv -> tv.value(Stream.of(request.getMetaId())
        .map(FieldValue::of).toList()))));
boolQueryBuilder.filter(metaIdQuery);
Query undeletedQuery = openSearchUtil.getUndeletedQuery(boolQueryBuilder.build()._toQuery());
SortOptions sortOption = SortOptions.of(s -> s.field(
    f -> f.field("pos").order(SortOrder.Asc)));
List<MediaArtwork> artworks = openSearchUtil.searchDoc(
    OpenSearchIndexEnum.MEDIA_ARTWORK.getIndexName(),
    undeletedQuery, MediaArtwork.class,
    request.getPageId(), request.getPageSize(),
    Collections.singletonList(sortOption), totalCount);

这正是第 2.3 节"filter 不算分、可缓存"原理的落地：结构化条件全部进 filter。

5.2 软删除的实现：updateByQuery + Painless 脚本

删除不是 delete，而是 updateByQuery 打标记：

String script = " ctx._source.isDeleted = 1;"
      + "ctx._source.updateTime = params.currentTime;"
      + "ctx._source.lastModifiedIndicator = params.indicatorPrefix + '_' + ctx._id";
UpdateByQueryRequest request = new UpdateByQueryRequest.Builder()
    .index(indexName).query(query)
    .script(s -> s.inline(i -> i.source(finalScript)
        .params("currentTime", JsonData.of(currentTime))
        .params("indicatorPrefix", JsonData.of(String.valueOf(modifyTime)))))
    .build();

注意脚本里同时更新了 lastModifiedIndicator——软删除也是一次"变更"，必须让下游订阅方感知到（下游才能同步删）。这个细节是订阅体系能闭环的关键。

5.3 两阶段全文搜索

C 端搜索入口 SearchService.searchMedia 的分流逻辑：

if (StringUtils.isNotEmpty(fuzzyMatchingParams.getKeyword())) {
    // 有关键词：内部库全文检索 → 返回 docId + mark（类型）
    resp = searchApi.matchSearch(keyword, marks, pageId, pageSize, tenantIds, params);
} else {
    // 无关键词：纯结构化筛选（找片页、分类浏览）
    resp = searchApi.find(marks, pageId, pageSize, tenantIds, params);
}
// 按 mark 分流 person / meta，回查详情索引取完整数据
openSearchUtil.batchGetDocuments(PERSON_DETAIL.getIndexName(), personDocIds, PersonDetail.class);
openSearchUtil.batchGetDocuments(META_DETAIL.getIndexName(), metaDocIds, MetaDetail.class);

查询条件从哪来？API 层收的是 SQL 风格的 where 模板（MetaQuery.whereTemplate + parameters），WhereClauseUtil 用正则把 in (:x)、between and、JSON_CONTAINS_ALL/ANY 解析成 ES 的 Condition（IN / GREATER_THAN 等），字段名经 FieldNameMappingEnum 做外部名→索引字段名映射。

这个设计的好处：对前端/上游服务来说，查询语法是稳定的数据库风格，不暴露 ES DSL；ES mapping 改名、换引擎，外部无感。

5.4 自动补全：completion suggester + 租户隔离

// SearchService.suggest
List<Prompt> prompts = searchApi.getPromptList(keyword, marks, true, companyId, size, uuid);
// 底层 = 搜索索引 suggest 字段的 completion suggester，
// context 里带 tenantCate=companyId → 补全结果按运营商隔离
// 拿到 docId 后再回查详情索引组装标题和海报

举例如"用户输入 int"：

sequenceDiagram
    participant U as 用户(运营商A)
    participant S as SearchService
    participant SE as 搜索索引 suggester
    participant D as 详情索引
    U->>S: suggest("int", companyId=A)
    S->>SE: completion suggest<br/>context: tenantCate=A
    SE-->>S: ["Interestelar", "Intocáveis"]<br/>+ docId 列表
    S->>D: mget(docIds)
    D-->>S: 标题 + 海报 URL
    S-->>U: 补全列表（带封面）

5.5 一个常被忽略的性能点：只取 ID 就别加载 _source

// fastGetDocumentById：判断文档存在/取 ID 时
// storedFields("_id") + size(1) + trackTotalHits(false)
// 注释原话：类似 MySQL 的 LIMIT 1

trackTotalHits(false)：不精确统计总数（默认只算到 10000），省掉一次全量计数；
storedFields("_id")：不加载 _source，网络传输量从几十 KB 降到几十 B。

列表页"先查 ID 再回查"的场景，这两招能把响应时间砍掉一个量级。

六、增量订阅：ES 作为"变更数据源"

下游服务（推荐、缓存、其他中台）需要感知媒资变更。项目没有用 CDC 或 MQ 广播，而是让下游基于水位游标主动拉取 ES：

sequenceDiagram
    participant SUB as 下游订阅方
    participant Q as SubqueryService
    participant ES as 详情索引

    Note over SUB: 记录上次水位 W0<br/>（lastModifiedIndicator 字符串）
    SUB->>Q: querySubQuery(from=W0, size=500)
    Q->>ES: range(lastModifiedIndicator: gt W0, lt 当前时间-2s)<br/>+ 按 lastModifiedIndicator 升序
    ES-->>Q: 本批变更文档（含软删除的）
    Q-->>SUB: 文档 + 新水位 W1
    SUB->>SUB: 落库/更新缓存，记录 W1
    Note over Q,ES: 对账：subQueryCount 用 count + sort desc + size(1)<br/>取区间最大水位，生产方/消费方核对数量

几个工程细节值得细说：

水位是字符串而非时间戳：lastModifiedIndicator = 时间戳 + "_" + docId。纯时间戳会在同一毫秒内有多个文档时漏数；拼上 docId 后字典序唯一，range gt 翻页不会漏、不会重。这是项目用手写游标替代 search_after 的原因——行为完全可控，且不依赖 ES 的 PIT（point in time）上下文。
lt 当前时间 - 2s 的回调偏移：规避"刚写入还没 refresh 可见"的窗口（第 2.2 节 NRT 原理的直接应用），宁可晚 2 秒，不可漏数据。
软删除文档也带着新水位出现，下游据此删除本地副本——和第 5.2 节的脚本闭环。

七、多租户设计：docId 里藏着租户

// OpenSearchUtil.getDocId：文档 ID = companyId + "#" + metaId
// 例："1001#mv_8848123"、"public#mv_8848123"（公共库）

同一部影片，A 运营商和 B 运营商是两份文档（各自的标题、定价、上架状态可能不同），天然物理隔离；
sourceType 字段区分 PRIVATE（私有）/ PUBLIC（公共）/ MIXED（混合），公共内容用 public# 前缀，查询时按租户策略合并；
所有查询 filter 里都带 companyId / tenant_id，补全用 context 隔离（第 5.4 节）。

经验：多租户搜索系统，把租户编进 docId 比单纯加过滤字段更稳——docId 冲突本身就是一道防串租户的保险。

八、回到原理：这个项目验证了哪些书里的论断

书中原理	项目里的体现
Mapping 先行，改 analyzer 要重建索引	索引 DDL 用 changelog 版本化管理，上线流程化
Filter 不算分、可缓存	租户/类型/软删除/状态全部进 filter，只有关键词算分
多字段映射解决"一个字段多种搜法"	mainTitle 四层子字段：分词/长ngram/短ngram/keyword
NRT 的 refresh 是性能旋钮	批量写入用 `refresh=WaitFor`；订阅端留 2s 偏移
深度翻页要避免 from+size 深分页	手写 `lastModifiedIndicator` 游标替代 search_after
聚合昂贵，慎用	项目几乎零聚合；取最大值用 sort+size(1) 替代 max agg
分片数创建时定死，规划要前置	详情索引 6 分片按数据增长预估；搜索索引刻意 1 分片

九、总结

如果把这套架构压缩成一张图：

graph LR
    W["写路径<br/>MySQL 事务<br/>+ 任务表兜底"] --> ES
    subgraph ES["OpenSearch"]
        S["搜索索引<br/>小而快：ngram+suggester<br/>+租户 context"]
        D["详情索引<br/>大而全：keyword+nested<br/>dynamic:false"]
    end
    ES --> R1["读路径 ①<br/>搜索/补全 → docId"]
    R1 --> R2["读路径 ②<br/>mget 详情组装"]
    ES --> R3["订阅路径<br/>水位游标增量拉取"]

三条核心经验：

索引按"查询模式"而不是"数据表"来设计：搜索索引和详情索引分开，一个为召回优化（ngram、suggester、多语分析器），一个为取数优化（keyword、nested、禁动态字段）；
一致性靠机制不靠运气：事务内直写是主路径，任务表 + 定时 Job + 失败重试是兜底，水位游标让下游最终一致——三层防护各管一段；
所有"黑科技"都是基本原理的应用：refresh 偏移、filter 缓存、storedFields 取 ID、游标翻页……吃透《Elasticsearch in Action》那套原理，生产方案都是它的排列组合。

参考资料：Radu Gheorghe, Matthew Lee Hinman, Roy Russo. 《Elasticsearch in Action》. Manning Publications, 2015；ftmao-meta 项目源码（OpenSearchConfig / OpenSearchUtil / SearchService / SubqueryService / changelog/elasticsearch）。