企业官网建设流程全解析

如何在一秒内从40万首诗里找到任意一字？chinese-poetry-api全文搜索与飞花令实战指南

【免费下载链接】chinese-poetry-api📜 诗泉：高性能中国古诗词 API 服务项目地址: https://gitcode.com/gh_mirrors/ch/chinese-poetry-api

chinese-poetry-api（诗泉）是一个基于 Go 的高性能中国古诗词 API 服务，收录了近 40 万首唐诗、宋词、元曲。它内置全文搜索与飞花令单字检索功能，无论你要找"静夜思"还是包含"月"字的任意诗句，请求都能在亚秒级返回。本文带你用零门槛的方式玩转这两个核心搜索能力。

一、为什么 40 万首诗也能"一秒出结果"？🔍

想象一下：在 40 万行数据里逐行找"床前明月光"，就像在图书馆里一本本翻书。chinese-poetry-api 没有这么做，它在 SQLite 里建了一张FTS5 全文索引表，并选用了trigram（三元组）分词器。

这个选择很关键：

• 普通分词器对中文按词切分，单字、双字查询（比如只搜一个"月"字）经常搜不到；
• trigram 索引把文本切成连续三字片段，天然支持任意长度子串匹配，连单字查询都能走索引，而不是全表扫描。

所以?q=月这种"搜任意一字"的请求，和搜整句一样快。索引在数据库迁移阶段自动创建，并由触发器在增删改诗词时自动同步，源码见 migrate.go。

二、一键启动诗词服务：Docker 最快配置方法

最快的启动方式就是一条 Docker 命令，镜像支持 amd64/arm64 多架构：

docker run -d -p 1279:1279 palemoky/chinese-poetry-api:latest

启动后访问http://localhost:1279/api/v1/health确认服务存活即可。更完整的编排配置可参考 docker-compose.yml。

💡 如果你想从源码构建，可以克隆仓库（数据通过 Git Submodules 管理，建议加上--recurse-submodules --depth=1）：git clone --recurse-submodules --depth=1 https://gitcode.com/gh_mirrors/ch/chinese-poetry-api

三、全文搜索实战：q 参数 + 4 种搜索类型 ✨

核心接口只有一个：GET /api/v1/poems/search?q=关键词，配合type参数切换搜索范围：

几个常用示例：

# 搜所有含"月"的诗（默认搜全部字段） curl "http://localhost:1279/api/v1/poems/search?q=月" # 只在标题里找"庐山" curl "http://localhost:1279/api/v1/poems/search?q=庐山&type=title"

搜索结果自带分页（page、page_size），响应里包含total总数，方便前端翻页。搜索逻辑集中在 repository_poems.go 的SearchPoems方法中，四种类型分别走标题索引、内容索引或作者表。

四、飞花令玩法：char 参数一秒抽中任意一字 🎲

飞花令的规则是：轮流说出含指定字的诗句。chinese-poetry-api 为这个场景专门设计了参数：

curl "http://localhost:1279/api/v1/poems/random?char=春"

它会从所有正文含"春"字的诗词中随机抽一首返回，比如"春眠不觉晓"。原理见 repository_poems.go 的GetRandomPoemByChar：先通过 FTS 内容索引统计命中数量，再用随机偏移量取一首，保证分布均匀。

两个细节值得记住：

1. char 必须是单个汉字，传"春天"会直接返回 400 错误；
2. char 只能与lang参数组合（如?char=春&lang=zh-Hant抽繁体诗句），不能叠加作者/体裁/朝代过滤，接口会明确拒绝——这也是服务端写死的契约，见 poem.go。

想体验完整参数组合，可以打开项目内置的 HTTP 请求集 requests.http，里面把飞花令的正常请求、预期报错的请求都写好了，用 VS Code REST Client 插件直接点运行即可。

五、进阶小贴士：繁体切换与 GraphQL 双接口

• 双语免费：所有搜索接口都支持?lang=zh-Hant，同一份数据库同时存简体和繁体，切换零成本；
• GraphQL 等价能力：/graphql端点提供searchPoems(query, searchType)查询，一次拿到标题、作者、朝代等结构化字段，适合前端灵活取数。

六、小结

chinese-poetry-api 把"从 40 万首诗里找任意一字"这件听起来很贵的事，拆成了两个简单接口：

• 全文搜索/api/v1/poems/search?q=：靠FTS5 trigram 索引扛住单字到整句的任意子串匹配；
• 飞花令/api/v1/poems/random?char=：同一份内容索引 + 随机偏移，一键出诗句。

数据规模参考 README.md 中的数据集分布：七绝/七律 15.4 万首、五绝/五律 9 万首、宋词 2.1 万首、元曲 1 万首……索引建好之后，这些量级都只是一次亚秒级的索引查询。📜

【免费下载链接】chinese-poetry-api📜 诗泉：高性能中国古诗词 API 服务项目地址: https://gitcode.com/gh_mirrors/ch/chinese-poetry-api