FastAPI + Elasticsearch 实战：BOSS 类招聘项目的职位搜索（从建索引到 bool 查询）

摘要本文从真实项目fastApiProject4FastAPI Tortoise ORM Elasticsearch出发梳理「职位搜索」功能的完整链路ES 异步客户端单例 → 依赖注入 → 索引 mapping 设计 → 全量同步旧版逐条写入 vs 优化版 async_bulk 批量幂等写入→ bool 查询搜索接口并复盘几个真实踩坑。代码均来自项目可直接对照学习。一、为什么用 Elasticsearch招聘项目的「职位搜索」是典型的全文检索 多维筛选 排序场景按关键词Java、前端、五险一金搜职位名/描述再叠加城市、学历、经验、行业、公司规模、融资阶段、状态等精确条件最后按相关度或发布时间排序。关系型数据库MySQL做LIKE %关键词%既慢又无法算相关度因此引入 Elasticsearchtext字段 ik_max_word中文分词做全文检索keyword字段做精确匹配 / 聚合 / 筛选bool查询把「关键词算分」与「硬性筛选」解耦mustvsfilter。本项目中 ES 只承担检索职位源数据仍在 MySQLTortoise ORM通过「全量同步」把数据冗余进 ES 宽表。二、ES 异步客户端单例app/core/es_client.pyfrom elasticsearch import AsyncElasticsearch import os from app.core.logging import logger ​ ES_HOST os.getenv(ES_HOST, http://localhost:9200) es_client: AsyncElasticsearch | None None ​ async def get_es_client() - AsyncElasticsearch: 获取 ES 异步客户端单例 global es_client if es_client is None: es_client AsyncElasticsearch(ES_HOST) logger.info(ES 客户端初始化成功) return es_client ​ async def close_es_client(): 关闭 ES 客户端连接 global es_client if es_client is not None: await es_client.close() es_client None要点用AsyncElasticsearchFastAPI 是异步框架全程await避免阻塞事件循环。单例整个进程共用一个客户端省连接开销global缓存。host 可配置通过环境变量ES_HOST注入本地默认http://localhost:9200生产改成集群地址。在应用启动时初始化main.pyfrom contextlib import asynccontextmanager from fastapi import FastAPI from tortoise import Tortoise from app.core.es_client import get_es_client from app.apis.es_data_api import es_data_router ​ asynccontextmanager async def lifespan(app: FastAPI): await Tortoise.init(configTORTOISE_ORM, _enable_global_fallbackTrue) # ...缓存预热... await get_es_client() # 启动即建立 ES 连接 yield await Tortoise.close_connections() ​ app FastAPI(lifespanlifespan) # ... app.include_router(es_data_router)把get_es_client()放进lifespan启动阶段保证第一个请求到来前客户端已就绪也可在请求内首次调用时惰性创建单例逻辑已支持。依赖注入app/core/depends.pyfrom elasticsearch import AsyncElasticsearch from app.core.es_client import get_es_client ​ async def es_client_depend() - AsyncElasticsearch: return await get_es_client()所有 ES 接口用Depends(es_client_depend)拿到同一个客户端实例无需每个请求新建。三、索引 Mapping 设计索引名boss_job_index_v2优化版与旧版boss_job_index隔离便于对比。核心字段类型选择字段类型用途job_name/job_desc/duty_require/enterprise_name/industry_nametextik_max_word中文全文检索work_location/edu_require/exp_require/recruit_num/job_tagskeyword精确匹配、筛选薪资是字符串含「面议」用 keywordstatus/department_id/ 各enterpriseInfo_*枚举integer数值精确筛选与 IntEnum 对应publish_time/enterprise_create_time等date时间范围 / 排序enterprise_id/industry_id等long关联 id 筛选关键经验中文必须 ik 分词text字段配analyzer: ik_max_word否则默认standard分词会按字切搜「前端」匹配不到「前端工程师」。薪资用 keyword 而非 integer模型里薪资是字符串可能「面议」强行 integer 会写入失败。枚举存 intcompany_scale/financing_stage等 IntEnum 存 int便于精确term筛选。宽表冗余把「职位 企业主表 企业详情 行业」拍平成一份文档搜索时一次命中避免 ES 内的 join。创建索引关键片段from elasticsearch import AsyncElasticsearch from app.core.depends import es_client_depend ​ es_data_router.post(/create-index-v2, summary创建索引(优化版)) async def create_index_v2(es_client: AsyncElasticsearch Depends(es_client_depend)): settings {number_of_shards: 1, number_of_replicas: 0} mappings { properties: { job_id: {type: long}, job_name: {type: text, analyzer: ik_max_word}, work_location: {type: keyword}, min_salary: {type: keyword}, max_salary: {type: keyword}, status: {type: integer}, publish_time: {type: date}, enterprise_name: {type: text, analyzer: ik_max_word}, enterpriseInfo_company_scale: {type: integer}, enterpriseInfo_financing_stage: {type: integer}, industry_name: {type: text, analyzer: ik_max_word}, # ...其余字段省略参见项目源码... } } if await es_client.indices.exists(indexBOSS_JOB_INDEX_NAME_V2): return {code: 1, message: 索引已存在, data: {index: BOSS_JOB_INDEX_NAME_V2}} await es_client.indices.create(indexBOSS_JOB_INDEX_NAME_V2, settingssettings, mappingsmappings) return {code: 1, message: 索引创建成功, data: {index: BOSS_JOB_INDEX_NAME_V2}}四、全量同步旧版 vs 优化版同步就是把 MySQL 里的职位 关联企业数据写进 ES 索引。项目里保留了「旧版」和「优化版」两套正好对比学习。4.1 旧版逐条写入有坑es_data_router.post(/insert-data, summary同步数据) async def insert_data(es_client: AsyncElasticsearch Depends(es_client_depend)): jobs await Job.all() for job in jobs: enterprise await Enterprise.get_or_none(idjob.enterprise_id).prefetch_related(city) enterpriseInfo await EnterpriseInfo.get_or_none(enterprise_idjob.enterprise_id).prefetch_related(industry) job_info { ... } # 手工拼字段且 datetime/Enum 未序列化 await es_client.index(indexBOSS_JOB_INDEX_NAME, documentjob_info) # 逐条写入 return 数据同步成功问题N1 查询每个职位都单独查一次企业、一次详情数据量大时极慢。不幂等没指定_id每次同步都新增文档重复调用会越插越多、数据翻倍。序列化隐患datetime/IntEnum直接写依赖 ES 客户端隐式转换mapping 类型对不上时写入失败。企业缺失即崩enterprise为None时访问.enterprise_name直接抛异常整批中断。4.2 优化版批量 幂等 容错优化思路批量预加载解决 N1 → 指定_id实现幂等 →async_bulk批量写 → 脏数据跳过不中断 → 统一序列化。序列化辅助from enum import Enum from datetime import date, datetime ​ def _to_es_value(value): ORM 字段值 → ES 友好类型datetime/date→ISOEnum→value其余原样 if value is None: return None if isinstance(value, (datetime, date)): return value.isoformat() if isinstance(value, Enum): return value.value return value批量预加载 组装解决 N1jobs await Job.all() enterprise_ids list({job.enterprise_id for job in jobs if job.enterprise_id is not None}) ​ # 一次查出全部相关企业 / 详情内存建 mapO(1) 关联避免 N1 enterprises await Enterprise.filter(id__inenterprise_ids).prefetch_related(city) enterprise_map {e.id: e for e in enterprises} enterprise_infos await EnterpriseInfo.filter(enterprise_id__inenterprise_ids).prefetch_related(industry) enterprise_info_map {info.enterprise_id: info for info in enterprise_infos} ​ actions [] skip_count 0 for job in jobs: enterprise enterprise_map.get(job.enterprise_id) enterprise_info enterprise_info_map.get(job.enterprise_id) if enterprise is None: # 企业缺失 → 跳过并记录不中断整批 skip_count 1 logger.warning(f同步跳过职位 id{job.id} 关联企业不存在) continue document _build_job_document(job, enterprise, enterprise_info) # 宽表拼装 actions.append({ _index: BOSS_JOB_INDEX_NAME_V2, _id: str(job.id), # 幂等关键重复同步覆盖旧文档 _source: document, })批量写入from elasticsearch.helpers import async_bulk ​ success_count, errors await async_bulk( clientes_client, actionsactions, raise_on_errorFalse ) error_count len(errors) if isinstance(errors, list) else 0 return { code: 1, message: 数据同步完成, data: {job_total: len(jobs), success: success_count, skip: skip_count, error: error_count}, }_idstr(job.id)是幂等的关键再次同步同一职位会覆盖旧文档而非新增。raise_on_errorFalse让单条失败不整体抛异常用返回值统计成功/失败条数。五、搜索接口bool 查询/es-data/search是职位搜索核心入参覆盖关键词 多种筛选 分页 排序。5.1 查询构建思路must_clauses [] # 关键词参与算分 filter_clauses [] # 硬性条件不参与算分 # 1关键词multi_match 打在多个 text 字段职位名加权 if keyword and keyword.strip(): must_clauses.append({ multi_match: { query: keyword.strip(), fields: [job_name^3, job_desc^2, duty_require, enterprise_name, industry_name], type: best_fields, operator: and, } }) # 2硬筛选全部进 filter不影响相关度 if status is not None: filter_clauses.append({term: {status: status}}) if work_location: filter_clauses.append({term: {work_location: work_location}}) if edu_require: filter_clauses.append({term: {edu_require: edu_require}}) if industry_id is not None: filter_clauses.append({term: {industry_id: industry_id}}) if company_scale is not None: filter_clauses.append({term: {enterpriseInfo_company_scale: company_scale}}) # ... financing_stage / exp_require 同理 ... # 3组装 bool bool_query {} if must_clauses: bool_query[must] must_clauses if filter_clauses: bool_query[filter] filter_clauses query {bool: bool_query} if bool_query else {match_all: {}}关键设计mustvsfilter分离关键词放must参与相关度打分城市/学历/状态放filter只过滤不干扰排序——这是 ES 搜索性能与效果的核心套路。^3/^2权重职位名命中比描述命中更重要用job_name^3提升权重。operator: and关键词分词后需全部命中召回更精准想更宽可改or。5.2 排序与分页# 有关键词且 sortscore → 按相关度否则按发布时间倒序 if sort score and keyword: sort_clause [_score, {publish_time: {order: desc, missing: _last}}] else: sort_clause [{publish_time: {order: desc, missing: _last}}] from_ (page - 1) * page_size source_fields [job_id, job_name, work_location, min_salary, status, publish_time, enterprise_name, industry_name] # 只取列表需要的字段 resp await es_client.search( indexBOSS_JOB_INDEX_NAME, queryquery, sortsort_clause, from_from_, sizepage_size, sourcesource_fields, track_total_hitsTrue, )分页用from/sizeES 原生非 MySQL 的offset/limit。source裁剪列表页只取卡片字段减小传输与解析开销。track_total_hitsTrue拿到准确total否则深翻页total可能不准。missing: _last字段缺失的文档排到最后避免排序报错。5.3 返回结构hits resp.get(hits, {}) total_count hits.get(total, {}).get(value, 0) lists [] for hit in hits.get(hits, []): item hit.get(_source) or {} item[_score] hit.get(_score) # 相关度便于调试 lists.append(item) return { code: 1, message: success, data: { lists: lists, page_info: { page: page, page_size: page_size, total_count: total_count, total_page: (total_count page_size - 1) // page_size, }, }, }返回约定与项目其他接口一致code/message/data前端可直接复用拦截器。六、真实踩坑与经验中文分词必须装 IK 插件text字段analyzer: ik_max_word依赖 ES 已安装analysis-ik否则创建索引报analyzer [ik_max_word] not found。字段类型要对齐写入值mapping 是date写入却传datetime对象没问题ES 客户端会转但IntEnum必须.value成 int否则写入失败——这就是_to_es_value存在的原因。mapping 漏字段 → 写入静默失败/被忽略旧版 mapping 漏了enterpriseInfo_business_scope同步却写它优化版显式补齐。建议同步前先indices.exists校验索引mapping 与写入字段用同一份定义。同步要幂等务必指定_id否则重复同步数据翻倍配合indices.exists防重复建索引。避免 N1同步时先按id__in批量取出关联表内存建 map绝不在循环里逐条查库。must/filter分离筛选条件放filter不污染相关度想让「状态招聘中」之类默认生效就在filter里加默认status1。七、本地联调步骤# 1. 启动带 IK 插件的 ESDocker 示例 docker run -d --name es -p 9200:9200 -p 9300:9300 \ -e discovery.typesingle-node \ elasticsearch:8.x # 安装 IK进容器执行 bin/elasticsearch-plugin install ...ik... # 2. 后端配置 ES_HOST默认 http://localhost:9200 export ES_HOSThttp://localhost:9200 # 3. 启动 FastAPIlifespan 会自动初始化 ES 客户端 uvicorn main:app --reload # 4. 调用流程 curl -X POST http://localhost:8000/es-data/create-index-v2 # 建索引 curl -X POST http://localhost:8000/es-data/insert-data-v2 # 全量同步 curl http://localhost:8000/es-data/search?keywordJavawork_location上海page1page_size10 # 搜索八、总结一个可用的职位搜索链路是ES 异步客户端单例启动初始化→ 依赖注入进接口 → 设计 mappingtext/keyword/integer/date 各司其职 IK 分词→ 全量同步批量预加载 幂等_id async_bulk→ bool 查询搜索must 算分 / filter 筛选 / from-size 分页。优化版相对旧版解决了 N1、幂等、序列化、容错四个核心问题是生产可用的写法。关键词 / 标签Elasticsearch、FastAPI、AsyncElasticsearch、bool 查询、IK 分词、async_bulk、索引 Mapping、职位搜索、Tortoise ORM