chinese-poetry-api：40万首古诗词 API，Go高性能 REST+GraphQL双接口

来源：微信公众号

做小程序、博客、教育工具时，想加古诗词板块总踩坑：公开第三方 API 限流收费、自己爬取工程量巨大、简繁转换还要额外写工具。

chinese-poetry-api 解决这个痛点——Go 语言高性能驱动，内置近 40 万首古典诗词，REST+GraphQL 双接口，Docker 一行命令启动。

项目档案

核心功能

1. 海量完整诗词数据集

内置近 40 万首诗词，包含五绝、七律、宋词、元曲、诗经、楚辞、乐府等全品类古典文献，基于 chinese-poetry 数据集。无需手动爬取、清洗、存储，省去数天数据处理工作量。

适用场景：诗词学习 APP、诗词打卡小程序、博客每日诗句模块。

2. REST+GraphQL 双接口

同时提供传统 RESTful 接口与 GraphQL 灵活查询端点，支持分页、筛选、自定义返回字段。

• REST：适合快速简单调用
• GraphQL：避免冗余字段传输，适配复杂数据看板

# REST 随机五言绝句
curl "http://localhost:1279/api/v1/poems/random?author=李白&type=五言绝句"

# GraphQL 全文搜索
curl -X POST -H "Content-Type: application/json" \
  -d '{"query":"{ poems(search:\"月\") { title author content } }"}' \
  http://localhost:1279/graphql

3. 简繁双语切换，毫秒级性能

数据库统一存储简繁文本，请求携带 lang=zh-Hans/zh-Hant 参数一键切换，单条转换仅 300ns。

# 繁体搜索「月」
curl "http://localhost:1279/api/v1/poems/search?q=月&lang=zh-Hant"

面向港澳台、海外华人的文化站点、书法展示类产品直接复用，无需前端引入转换库。

4. 多维度精准检索

全文/标题/内容/作者四类搜索；随机接口可叠加朝代、作者、体裁多重过滤：

# 随机李白五言绝句
curl "http://localhost:1279/api/v1/poems/random?author=李白&type=五言绝句"

# 查询所有朝代列表
curl "http://localhost:1279/api/v1/dynasties"

诗词答题、诗人专题、朝代分类页面、每日限定诗句卡片快速实现。

5. Docker 容器化一键部署

# Docker 一键启动（推荐）
docker run -d -p 1279:1279 palemoky/chinese-poetry-api:latest
# 启动完成后访问 http://127.0.0.1:1279

完整克隆源码（二次开发）：

git clone --recurse-submodules --depth 1 \
  https://github.com/palemoky/chinese-poetry-api.git
cd chinese-poetry-api
make build && make run-server

6. 内置限流 + 压测脚本

自带 IP 限流防滥用，配套 k6 负载测试脚本，最高支持 3000 并发用户压测，数据库连接池自适应 CPU 核心。

适用场景

不推荐：纯闭源商业软件（GPL-3.0 强传染），仅需单条随机短句（可用公共 API），需要译文/注释/拼音（本项目仅存储原文）。

实测总结

项目文档清晰，Docker 部署零配置开箱即用；curl 调试接口直观易懂，Go 后端并发性能优秀，本地单机并发上千请求无卡顿。

优势：

• 数据体量领先：近 40 万首完整诗词
• 部署门槛极低：Docker 一行命令
• 接口设计完善：双接口、多维度筛选、简繁切换、分页统计
• 性能可控：自带限流、自适应连接池
• 数据本地存储，无第三方调用次数限制

注意：

• GPL-3.0 协议：商用闭源分发会触发协议合规风险
• 数据集仅含诗词原文，无译文、注释、拼音
• 无配套前端页面，需自行开发展示界面

总结

chinese-poetry-api 是面向开发者的私有化高性能诗词 API，依托 40 万首完整诗词数据集，双接口、简繁切换、容器化部署一应俱全。

GitHub：https://github.com/palemoky/chinese-poetry-api