chinese-poetry-api README

The project's README from github.com/palemoky/chinese-poetry-api. As one markdown file: README.md.

chinese-poetry

中国古诗词 API 服务

Docker Image Docker Image Size pre-commit License

基于 Go 语言的高性能中国古诗词 API 服务，支持 REST 和 GraphQL 接口，提供简体/繁体中文、爬虫练习场等功能。

在线版：https://poetry.palemoky.com

palemoky%2Fchinese-poetry-api | Trendshift

特性

快速开始

使用 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-api (palemoky/chinese-poetry-api)

Searching Database…

3.4K ·GitHub
Chinese-poetry-api
这是什么？一个用 Go 编写的高性能中国古诗词 API 服务，同时提供 REST 和 GraphQL 接口，数据集收录了近 40 万首诗词，涵盖唐诗、宋词、元曲等。
这是一个可以嵌入的库，还是一个我自己部署的独立服务器？它是一个需要你自己部署的独立服务器（通过 Docker 或 Go 编译构建），不是可以导入到自己代码里的库。
我该怎么把它跑起来？用 Git 连同子模块一起克隆仓库以拉取诗词数据，然后用 Docker Compose 运行（推荐，配置在 docker-compose.yml 里），或者通过自带的 Makefile 编译运行。
我需要单独获取诗词数据吗？需要。诗词数据存放在一个单独的子模块仓库里（一个修正了错别字的 chinese-poetry 分支版本），所以克隆时必须带上子模块；如果已经克隆过但没带子模块，就需要再运行一次子模块更新。
对查询量有限制吗？有，它内置了按 IP 的限流机制，专门用来防止公共 API 被滥用。
Docker 镜像能在 ARM 服务器上运行吗，还是只支持 x86？Docker 镜像是多架构的，同时支持 amd64 和 arm64。
诗词数据集有多大？大约 40 万条，包括 82,744 首七言绝句、68,696 首七言律诗、21,347 首宋词、10,904 首元曲，还有《诗经》、《楚辞》等等。
这个 API 支持哪些搜索方式？默认是全文搜索（?q=月），还可以通过 type 参数使用专门的标题、内容和作者搜索模式。
能同时获取简体和繁体中文的结果吗？可以。每个接口都接受 lang 参数（zh-Hans 或 zh-Hant）来在简体和繁体中文之间切换，两者存储在同一个数据库里。
简繁转换的速度怎么样？转换针对并发做了优化，单次操作大约 300 纳秒，使用的是 gocc 库。
What are similar projects?tyk, zincsearch, typesense, pansou, reaction, dgraph, cube, claude-relay-service
Which topics is it in?rate-limiting, full-text-search, arm64, chinese-language, graphql, dataset, search, i18n, docker-compose, rest-api, backend, gplv3
Creator
palemoky
Size
12.9 MB
Stars
3.4K
Updated
CommitOct 07Releasev0.6.0Jul 04
Age
10mo
Commits · 90 Days