极简一行 Docker 启动 40 万古诗词库！开源 chinese-poetry-api 架构拆解与应用实践

在日常开发各类技术博客、个人网站、桌面 Widget 挂件、微信小程序乃至电子墨水屏（E-ink）日历时，我们常常需要为用户提供“今日诗词”或随机名句展示功能。然而，若要开发者自行搜集唐诗、宋词、元曲、楚辞等中华经典诗词，不仅涉及庞大的原始数据清洗工作，还需要搭建复杂的全文检索与 API 服务架构。

开源项目 chinese-poetry-api（GitHub: palemoky/chinese-poetry-api）完美解决了这一困境。它基于 Go 语言开发，内置接近 40 万首完整中华古诗词数据库，原生支持 REST API 与 GraphQL 双重查询引擎，并且支持跨平台 Docker 镜像（amd64 / arm64）。本文将带大家深度拆解这一开箱即用的优质后端底座。

一、核心特性与技术优势

chinese-poetry-api 的定位是一个高性能、高容错且轻量级的古诗词数据服务接口。相比传统的静态 JSON 文件或简单的 SQLite 数据查询，它在性能与功能丰富度上具有显著优势：

1. 功能特性矩阵

二、快速部署指南

得益于容器化打包，chinese-poetry-api 的部署过程极其简单方便。

1. 一行 Docker 命令部署（快速体验）

只需在支持 Docker 的服务器上运行以下命令：

# 启动 API 服务，将容器 1279 端口映射到宿主机 1279 端口
docker run -d \
  --name chinese-poetry-api \
  --restart always \
  -p 1279:1279 \
  palemoky/chinese-poetry-api:latest

服务启动后，在浏览器访问 http://localhost:1279/ping 即可返回 {"message":"pong"} 验证服务运行状态。

2. Docker Compose 部署（推荐生产环境）

若需要自定义环境变量或配置后台守护，推荐使用 docker-compose.yml：

version: '3.8'

services:
  poetry-api:
    image: palemoky/chinese-poetry-api:latest
    container_name: chinese-poetry-api
    restart: always
    ports:
      - "1279:1279"
    environment:
      - PORT=1279
      - RATE_LIMIT_ENABLED=true
      - RATE_LIMIT_REQUESTS=100

只需执行命令 docker-compose up -d 即可在后台静默运行。

三、常用 API 接口调用示例

chinese-poetry-api 提供了极具人性化的接口设计，满足常见场景的查询需求。

1. 随机获取一首诗词（推荐用于每日一诗组件）

请求路径：GET /rand

# 请求随机诗词，并指定为繁体中文格式
curl -X GET "http://localhost:1279/rand?lang=zh-Hant"

响应 JSON 结构示例：

{
  "code": 200,
  "data": {
    "title": "靜夜思",
    "author": "李白",
    "dynasty": "唐",
    "paragraphs": [
      "床前明月光，",
      "疑是地上霜。",
      "舉頭望明月，",
      "低頭思故鄉。"
    ]
  }
}

2. 精确按关键词与作者搜素

请求路径：GET /search

# 搜索作者为“苏轼”，包含“明月”的词句
curl -X GET "http://localhost:1279/search?author=苏轼&keyword=明月"

四、生产部署边界与避坑指南

在实际将 chinese-poetry-api 部署至线上公网服务器或融入自研自动化工作流时，请务必关注以下工程注意事项：

[!IMPORTANT] Git Submodule 完整性检查：如果是从源码直接进行构建（如执行 go build 或使用源码构建镜像），项目仓库中数据文件通常通过 git submodule 托管。克隆源码时务必附带 --recursive 参数（即 git clone --recursive https://github.com/palemoky/chinese-poetry-api.git），避免因缺少底层数据导致服务启动后查询为空。

[!TIP] 防刷与公网限流：暴露在公网的服务建议保留内置的 IP 限流功能（RATE_LIMIT_ENABLED=true）。对于高并发小程序的场景，建议在入口 Nginx 处配置反向代理缓存（如缓存 GET /rand 响应 60 秒），以显著提升响应速度并降低服务器 CPU 开销。

五、总结

chinese-poetry-api 为开发者提供了一个轻量、优雅且功能完备的古诗词后端服务底座。通过简洁的 Docker 部署方式与灵活的 GraphQL/REST 接口，开发者可以在几分钟内为自己的产品添加富有文化底蕴的诗词交互功能。