中国古诗词 API 服务
基于 Go 语言的高性能中国古诗词 API 服务，支持 REST 和 GraphQL 接口，提供简体/繁体中文、爬虫练习场等功能。
在线版：https://poetry.palemoky.com
特性
- 高性能: Go 语言编写，支持并发处理，性能优化（简繁转换 ~300ns/op）
- 海量数据: 包含唐诗、宋词、元曲等近 40 万首诗词
- 强大搜索: 支持全文搜索、标题/内容/作者分类搜索
- 双语支持: 同一数据库同时存储简体和繁体中文，通过
?lang=参数切换 - 多种接口: REST API 和 GraphQL 双接口支持
- 限流保护: 内置 IP 限流，防止滥用
- 容器化: Docker 镜像开箱即用，支持多架构（amd64/arm64）
- 智能分类: 按朝代、作者、诗词类型自动分类
快速开始
使用 Docker（推荐）
docker run -d -p 1279:1279 palemoky/chinese-poetry-api:latest
完整配置参见 docker-compose.yml。
使用 Makefile
make help # 查看所有可用命令 make build # 构建项目 make process-data # 处理数据 make run-server # 启动服务
克隆仓库
本项目使用 Git Submodules 管理诗词数据，推荐使用以下命令快速克隆：
# 完整克隆（包含 submodules）
git clone --recurse-submodules --depth=1 https://github.com/palemoky/chinese-poetry-api.git如果已经克隆了仓库，可以单独更新 submodules：
git submodule update --init --depth 1
API 使用
多语言支持
所有接口支持 lang 参数切换简繁体：
| 参数值 | 说明 |
|---|---|
zh-Hans |
简体中文（默认） |
zh-Hant |
繁体中文 |
REST API
# 健康检查 curl "http://localhost:1279/api/v1/health" # 统计信息 curl "http://localhost:1279/api/v1/stats" # 简体中文（默认） curl "http://localhost:1279/api/v1/poems" # 繁体中文 curl "http://localhost:1279/api/v1/poems?lang=zh-Hant" # 诗词列表（带过滤，与 /poems/random 使用同一组参数） curl "http://localhost:1279/api/v1/poems?dynasty=唐" curl "http://localhost:1279/api/v1/poems?author=李白&page=2&page_size=50" curl "http://localhost:1279/api/v1/poems?dynasty_id=1&type_id=11&type_id=12" # 多个 type_id 为「或」关系 # 游标翻页：把上一页 pagination.next_cursor 的值回传给 after。 curl "http://localhost:1279/api/v1/poems?page_size=50&after=cG9lbTo0MjA" # 搜索诗词 curl "http://localhost:1279/api/v1/poems/search?q=静夜思" # 随机诗词 curl "http://localhost:1279/api/v1/poems/random" # 随机诗词（带过滤） curl "http://localhost:1279/api/v1/poems/random?author=李白" curl "http://localhost:1279/api/v1/poems/random?type=五言绝句" curl "http://localhost:1279/api/v1/poems/random?char=春" # 飞花令等单字场景 curl "http://localhost:1279/api/v1/poems/random?author=李白&type=五言绝句" curl "http://localhost:1279/api/v1/poems/random?author=李白&type=五言绝句&dynasty=唐" curl "http://localhost:1279/api/v1/poems/random?author=李白&dynasty=唐&type=五言绝句&type=七言绝句&type=五言律诗" # 作者列表 curl "http://localhost:1279/api/v1/authors?page=1&page_size=20" # 作者详情 curl "http://localhost:1279/api/v1/authors/1" # 朝代列表 curl "http://localhost:1279/api/v1/dynasties" # 朝代详情 curl "http://localhost:1279/api/v1/dynasties/1" # 诗词体裁列表 curl "http://localhost:1279/api/v1/types" # 诗词体裁详情 curl "http://localhost:1279/api/v1/types/10"
GraphQL API
端点：http://localhost:1279/graphql
# 繁体中文查询 query { poems(lang: ZH_HANT, pageSize: 10) { edges { node { title content author { name } } } totalCount } } # 搜索诗词 query { searchPoems(query: "静夜思", searchType: TITLE) { edges { node { title author { name } } } } } # 统计信息 query { statistics { totalPoems totalAuthors poemsByDynasty { dynasty { name } count } } }
搜索功能
| 类型 | 说明 | 示例 |
|---|---|---|
all |
全文搜索（默认） | ?q=月 |
title |
标题搜索 | ?q=静夜思&type=title |
content |
内容搜索 | ?q=床前明月光&type=content |
author |
作者搜索 | ?q=李白&type=author |
数据集
本项目基于 chinese-poetry 数据集，使用的是修正了错字、朝代与作者等问题的 palemoky/chinese-poetry（fix-typo 分支），包含：
| 分类 | 数量 | 分类 | 数量 | 分类 | 数量 | 分类 | 数量 |
|---|---|---|---|---|---|---|---|
| 五言绝句 | 16,860 | 七言绝句 | 82,744 | 五言律诗 | 59,681 | 七言律诗 | 68,696 |
| 乐府诗 | 6,714 | 五代词 | 543 | 宋词 | 21,347 | 元曲 | 10,904 |
| 诗经 | 305 | 楚辞 | 65 | 论语 | 20 | 四书五经 | 14 |
| 其他 | 76,077 |
pie title 收录数据分布概览 (忽略极小值) "七绝/七律" : 151440 "五绝/五律" : 76541 "宋词/五代词" : 21890 "元曲" : 10904 "乐府诗" : 6714 "其他" : 76077
致谢
- 数据来源：chinese-poetry
- 简繁转换：gocc