想要在应用里接入中国古诗词？诗泉是开源高性能古诗词 API 服务，Go 语言编写，支持 REST 和 GraphQL 双接口、近40万首诗词、简繁切换、Docker 一键部署。诗词背诵 App、古风游戏、语文学习工具的背后数据源，2,155 Stars 社区验证。
🎤 引言
做一个诗词背诵 App，或者古风游戏，需要大量古诗词数据支撑——自己爬、自己整理不仅费时，数据的准确性和版权问题也让人头疼。
诗泉（chinese-poetry-api）是一个开源的中国古诗词 API 服务，基于 Go 语言高性能实现，提供 REST 和 GraphQL 双接口，数据库收录了唐诗、宋词、元曲等近 40 万首诗词，支持简繁体中文切换、Docker 一键部署。开发者拿来接自己的项目，数据层面基本不用操心。2,155 Stars 的社区认可度说明这条路走得通。
⭐ 核心功能
📚 近40万首诗词
收录了唐诗、宋词、元曲、诗经、乐府等经典体裁，数据库直接用 Git Submodules 管理，官方建议 git clone --recurse-submodules 完整拉取。数据更新跟着官方诗词库走，不用担心版本落后。
⚡ 高性能 Go 实现
Go 语言编写，性能优化到位——简繁转换约 300ns/次，单次查询延迟极低。适合需要高并发的场景，比如在线诗词接龙、飞花令等小游戏，多用户同时访问也不容易卡。
🌏 简繁体双语支持
所有接口通过 ?lang= 参数无缝切换：
| 参数值 | 说明 |
|---|---|
zh-Hans | 简体中文（默认） |
zh-Hant | 繁体中文 |
两岸三地的用户看到的诗词文本可以完全适配，不用自己做简繁转换。
🔍 强大搜索能力
- 全文搜索：
/poems/search?q=静夜思 - 按作者随机：
/poems/random?author=李白 - 按体裁随机：
/poems/random?type=五言绝句 - 飞花令专用（单字查询）：
/poems/random?char=春 - 组合过滤：同时指定朝代 + 作者 + 体裁
📡 REST + GraphQL 双接口
同一个数据库同时提供 REST API 和 GraphQL 接口，开发者可以根据自己的技术栈选合适的：
# REST 风格
curl "http://localhost:1279/api/v1/poems/random?author=李白&type=五言绝句"
# REST 搜索
curl "http://localhost:1279/api/v1/poems/search?q=床前明月光"REST 接口覆盖健康检查、统计、作者列表、朝代、体裁等常见需求，GraphQL 接口则适合需要灵活字段选择的场景。
🚀 Docker 一键部署
docker run -d -p 1279:1279 palemoky/chinese-poetry-api:latest一条命令跑起来，支持 amd64 和 arm64 架构，树莓派也能跑。自建服务完全免费，不依赖任何第三方付费 API。
⏱️ 限流保护
内置 IP 限流机制，防止个别用户频繁请求影响服务稳定，适合公开 API 场景。如果自己部署，可以根据需求调整限流阈值。
📥 快速上手
在线体验（无需部署）
- 🌐 在线地址：https://poetry.palemoky.com（即开即用）
- 📦 Docker Hub：https://hub.docker.com/r/palemoky/chinese-poetry-api
本地部署（Docker Compose）
# 克隆仓库
git clone --recurse-submodules --depth=1 \
https://github.com/palemoky/chinese-poetry-api.git
cd chinese-poetry-api
# 启动服务
docker compose up -d
# 服务地址
# REST: http://localhost:1279/api/v1/常用 API 示例
# 健康检查
curl "http://localhost:1279/api/v1/health"
# 随机一首诗
curl "http://localhost:1279/api/v1/poems/random"
# 李白·五言绝句
curl "http://localhost:1279/api/v1/poems/random?author=李白&type=五言绝句"
# 搜索含"月"的诗
curl "http://localhost:1279/api/v1/poems/search?q=月"
# 繁体模式
curl "http://localhost:1279/api/v1/poems/random?lang=zh-Hant"
# 作者列表
curl "http://localhost:1279/api/v1/authors?page=1&page_size=20"
# 朝代列表
curl "http://localhost:1279/api/v1/dynasties"
# 诗词体裁列表
curl "http://localhost:1279/api/v1/types"🎯 适用场景
1. 诗词背诵 App / 小程序开发
随机抽查背诵、错题本、进度统计——这些功能背后都需要一个诗词数据库支撑。直接调诗泉 API，比自己爬数据省事得多，而且数据质量有保障。
2. 古风游戏（飞花令、诗词接龙）
飞花令要求快速根据一个字找到所有含该字的诗句，诗泉的 ?char= 参数专门为此设计。诗词接龙的随机推送也很简单，/poems/random 即可。
3. 语文学习工具
按朝代、作者、体裁筛选，适合做诗词学习路线图。比如"唐诗三百首精选"、"苏轼词全集"等专题，用户可以按维度自主学习。
4. 古风内容创作（文案、自媒体）
写古风文案时需要引用经典诗句，随机 API 可以当"诗句生成器"用，给创作找灵感。
🔍 对比 / 替代方案
| 方案 | 类型 | 数据量 | 接口 | 性能 | 部署 | 备注 |
|---|---|---|---|---|---|---|
| 诗泉 | 开源 API | ~40万首 | REST + GraphQL | ~300ns/简繁转换 | Docker 一键 | 2,155 Stars |
| 古诗词·中文联盟 | 在线 API | ~10万首 | REST | 一般 | 需申请 | 老牌，数据权威 |
| github.com/chinese-poetry | 数据集 | ~26万首 | 无（直接下数据） | — | — | 数据集，非 API |
| 自建爬虫 | 自建 | 不确定 | 自定义 | 低 | 耗时 | 数据质量不稳定 |
对比要点：
- vs 古诗词·中文联盟：联盟是老牌权威数据源，但部分接口需要申请；诗泉开源免费，自建更灵活。
- vs GitHub 数据集：chinese-poetry 是纯数据仓库，没有 API，需要自己写解析代码；诗泉直接提供 HTTP 接口。
- vs 自建爬虫：自己爬取数据耗时、数据更新维护成本高；诗泉开箱即用，有社区维护数据质量。
⚠️ 注意事项
- IP 限流：公开部署时注意限流配置，高并发场景建议加一层 API Gateway（如 Nginx 限流）。
- 数据版权：诗词本身属于公共领域，但整理的版本可能有版权，商用前建议确认所用数据源的具体协议。
- Docker 多架构支持：amd64 和 arm64 都支持，但如果在树莓派或 Mac M 系列上运行，建议确认 arm64 镜像可用性。
- Submodules 克隆：数据通过 Git Submodules 管理，克隆时记得加
--recurse-submodules，否则数据目录是空的。 - GraphQL vs REST：GraphQL 更灵活但配置略复杂，如果只是简单查询 REST 就够了，不用强行上 GraphQL。
- 无用户认证：当前版本没有用户级别认证，适合内部项目或加了一层 Gateway 的场景。
✅ 总结
诗泉是目前最值得关注的开源中国古诗词 API 方案——Go 高性能 + Docker 一键部署 + REST/GraphQL 双接口 + 简繁切换，几乎涵盖了一个诗词类应用需要的所有基础设施。
优点：高性能、数据量大、简繁双语、Docker 零成本部署、开源免费
缺点：无原生用户认证、GraphQL 文档较少
适合：诗词背诵 App、飞花令游戏、古风内容创作、语文学习工具
给古风项目找一个可靠的数据后端，诗泉是目前最省心的开源选择。
⭐ GitHub Stars：2,155（截至 2026-07）
📦 技术栈：Go + REST + GraphQL + Docker
🌐 在线体验：poetry.palemoky.com
🔗 GitHub：github.com/palemoky/chinese-poetry-api