这是极简速查版，5分钟了解项目全貌。
完整架构设计（含FTS5实现细节、去重策略、限流器踩坑、部署实操）请移步：https://www.jay-r-j.top/rust-chinese-poetry-api/

一句话定位

用 Rust + Actix Web + SQLite 构建的古诗词 REST API，收录约 13.3万首 唐诗宋词，单二进制部署，几十MB内存就能跑。

作者：Jay（就是我本人），MIT 协议开源。
仓库：https://github.com/Jay-R-J/poetry_API

技术栈速查

组件 选型 用途
语言 Rust 高性能、单二进制部署
Web框架 Actix-Web 异步HTTP服务器
数据库 SQLite (rusqlite) 嵌入式，无需独立服务
全文搜索 SQLite FTS5 + trigram 中文全文索引，无需分词库
异步运行时 tokio 异步执行环境
SQL构建 SQLx (QueryBuilder) 类型安全SQL、编译时校验
数据序列化 serde JSON序列化/反序列化
缓存 moka 内存缓存（每日一诗+详情）
限流 自实现滑动窗口 内存限流，IP级别
API文档 utoipa OpenAPI + Swagger UI自动生成
繁简转换 ferrous-opencc 导入时繁体转简体
哈希去重 FNV-1a 快速去重键生成
日志 env_logger 日志记录

核心功能（8个接口）

接口 说明
列表查询 分页 + 筛选（朝代/作者/分类）+ 关键词搜索
随机一首 从全库随机返回一首诗
每日一诗 从精选集（116首带译文）按日期确定性选取
详情查询 按ID返回完整诗信息（含译文、标签）
朝代分布 统计各朝代诗作数量
作者分布 统计各作者诗作数量（Top N）
标签分布 统计各标签诗作数量（仅精选集）
Swagger文档 自动生成API交互文档

统一响应格式：

{
  "code": 0,
  "message": "ok",
  "data": { ... }
}

关键数据

项目 数量
唐诗 57,600 首
宋诗 54,779 首
宋词 21,071 首
元曲等 5 首
合计 约 13.3 万首
精选集（带译文） 116 首

全部简体、已去重。

三个技术亮点（精简版）

1. 中文全文搜索：SQLite FTS5 + trigram

不需要任何中文分词库，按3个字符切分，对中文特别友好。关键词长度 ≥3 个字符走 FTS5 索引（毫秒级），更短的关键词自动退回 LIKE。

2. 数据导入：繁转简 + 去重

  • 用 ferrous-opencc 在导入时将繁体原文统一转为简体
  • 用「标题 作者 内容」的 FNV-1a 哈希作为唯一键，导入工具可安全重复执行
  • 两层数据结构：全量语料（13.3万首）用于搜索/随机，精选集（116首带译文）用于每日一诗

3. 限流器：滑动窗口 + 两个坑

内存限流，按 IP 记录请求时间窗口。两个关键设计：

  • 全局清扫：定期清理只访问一次的IP条目，防止内存泄漏
  • 代理感知：部署在Nginx后面时，从 X-Forwarded-For 取真实IP，而不是拿Nginx的IP

架构速览

客户端
  → 中间件层（CORS / gzip / 限流 / API Key认证）
  → Handler层（参数校验、统一响应）
  → Repository层（SQL构建）
  → SQLite（含FTS5全文索引）
      ↘ 内存缓存（moka）

部署形态

cargo build --release
# 得到一个二进制文件 + 一个SQLite文件
HOST=0.0.0.0 ./poem_api

前面挂 Nginx 或 Caddy 做 HTTPS 即可。

完整版（含FTS5实现细节、去重策略、限流器踩坑、部署实操）请移步：https://www.jay-r-j.top/rust-chinese-poetry-api/