一个基于 Go 语言的高性能中国古诗词 API 服务

标签: 开源项目 / Go语言 / API服务 / 古诗词
原文: 微信公众号「码农先森」https://mp.weixin.qq.com/s/LpkAuDwzUVUNxOhoe7MQLA
GitHub: https://github.com/palemoky/chinese-poetry-api

核心亮点

一个基于 Go 语言的高性能中国古诗词 API 服务，支持 REST 和 GraphQL 双接口，提供简体/繁体中文双语支持，包含近 40 万首诗词数据。

为什么需要这个项目？

古诗词数据集在网上有不少，但：

• 数据分散：唐诗在一处、宋词在另一处，格式不统一
• 缺少 API：大多是静态数据，没有现成的查询接口
• 性能问题：Python 写的 API 并发能力弱，高并发场景撑不住
• 简繁问题：港澳台用户需要繁体，大陆用户需要简体，一套数据很难同时满足

chinese-poetry-api 把这些痛点一次性解决。

核心特性

5 秒快速启动

方式一：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    # 启动服务

克隆仓库（包含 Submodules）

本项目使用 Git Submodules 管理诗词数据：

# 完整克隆（包含 submodules）
git clone --recurse-submodules --depth=1 https://github.com/palemoky/chinese-poetry-api.git

# 如果已经克隆了仓库，可以单独更新 submodules
git submodule update --init

API 使用详解

多语言支持

所有接口支持 lang 参数切换简繁体：

REST API 示例

# 简体中文（默认）
curl "http://localhost:1279/api/v1/poems"

# 繁体中文
curl "http://localhost:1279/api/v1/poems?lang=zh-Hant"

# 搜索诗词（全文搜索）
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?author=李白&type=五言绝句"
curl "http://localhost:1279/api/v1/poems/random?author=李白&dynasty=唐"

# 作者列表（分页）
curl "http://localhost:1279/api/v1/authors?page=1&page_size=20"

# 朝代列表
curl "http://localhost:1279/api/v1/dynasties"

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
    }
  }
}

搜索功能详解

数据集统计

本项目基于 chinese-poetry 数据集，包含：

总计：近 40 万首

性能表现

Go 语言的并发优势在这个项目里发挥得很充分：

典型使用场景

部署建议

最低配置

CPU: 1 核
内存: 512MB
磁盘: 1GB（数据文件约 800MB）

Docker Compose 部署

version: '3.8'
services:
  poetry-api:
    image: palemoky/chinese-poetry-api:latest
    ports:
      - "1279:1279"
    restart: unless-stopped
    # 可选：限制内存
    deploy:
      resources:
        limits:
          memory: 512M

与其他方案对比

快速验证部署是否成功

# 1. 检查服务是否启动
curl -I http://localhost:1279/api/v1/poems/random

# 2. 获取一首随机诗词
curl "http://localhost:1279/api/v1/poems/random" | jq .

# 3. 切换繁体
curl "http://localhost:1279/api/v1/poems/random?lang=zh-Hant" | jq .

项目结构（简要）

chinese-poetry-api/
├── cmd/server          # 服务入口
├── internal/           # 内部逻辑（handler, service, repository）
├── data/               # 诗词数据（submodule）
├── api/                # GraphQL schema 定义
├── Dockerfile
├── docker-compose.yml
├── Makefile
└── README.md

贡献与反馈

• GitHub Issues：bug 反馈、功能建议
• Pull Requests：欢迎贡献代码
• 数据集来源：chinese-poetry

写在最后

如果你在做一个古诗词相关的 APP、小程序、或者需要一个稳定的诗词数据源，这个项目可以直接用。

三行命令跑起来：

git clone --recurse-submodules https://github.com/palemoky/chinese-poetry-api.git
cd chinese-poetry-api
docker-compose up -d

然后访问 http://localhost:1279/api/v1/poems/random 就能拿到随机诗词了。

近 40 万首诗词，REST + GraphQL 双接口，简繁双语支持 —— 该有的都有了。

本文整理自微信公众号「码农先森」，原文链接：https://mp.weixin.qq.com/s/LpkAuDwzUVUNxOhoe7MQLA
*GitHub 项目地址：<ADDRESS_REDACTED>