古诗词·一言 API:一句诗的接口
gushici 在 GitHub 上已经拿到 1,383 Star 了。
xenv 开源了这个项目,专门干一件事——随机返回一句古诗词名句。Vert.x 异步框架加 Redis,毫秒级响应,支持 svg、txt、json、png 四种返回格式。

1、 这玩意儿是干嘛的
给你一个接口,调用一次返回一句古诗词。
应用场景蛮多的。博客侧边栏挂一句诗、小程序首页做点缀、论坛签名当随机展示、个人网站顶上一行装饰文字,都能直接接进去。SVG 方式可以在博客和论坛里无损直接调用,PNG 方式兼容性最好几乎所有地方都能插,JSON 方式拿到来源、作者、分类等结构化字段供你自己拼接显示。
2、 为什么用这个
要自己搭一个不算难,写个随机接口谁都会。难的是数据和稳定性。
诗词名句数据由古诗文网收录整理,分门别类放进 Redis 里。整套服务跑过数百万次调用,单元测试齐全,单机压测能跑到 2 万 QPS。E5 2660 八核十六线程机器上跑一百万次请求平均响应 4 毫秒,错误率 0。
如果你只是想要一句诗挂页面上,没必要自己采数据自己维护服务,调一下就行。
3、 怎么调用
接口地址格式:
https://v1.jinrishici.com/{一级分类}/{二级分类(可选)}.{返回格式(可选)}
支持的分类全部列在这里:https://v1.jinrishici.com/,可以用抒情、人生、离别、思乡、爱情、季节这些一级分类去取。

最简单的用法,HTML 里直接一行:
<img src="https://v1.jinrishici.com/all.svg">
想要自定义字体大小和字间距,加参数:
<img src="https://v1.jinrishici.com/all.svg?font-size=18&spacing=4">
字体大小 8 到 50 像素可选,字间距 0 到 30 像素可选,默认 20 像素和 1.5 像素。
要 JSON 格式自己拼接显示,一个 XMLHttpRequest 就拿到结果:
<script>
var xhr = new XMLHttpRequest();
xhr.open('get', 'https://v1.jinrishici.com/all.json');
xhr.onreadystatechange = function () {
if (xhr.readyState === 4) {
var data = JSON.parse(xhr.responseText);
document.getElementById('gushici').innerText = data.content;
}
};
xhr.send();
</script>
JSON 返回里带作者、来源、分类,可以自己拼成任何排版。TXT 调用和 JSON 几乎一致的写法,省掉解析那步,流量的消耗更小一些。PNG 调用则是最兜底的方式,所有浏览器所有平台都支持,缺点是没法改样式,图片传输体积也被流量策略压得比较小。
4、 想自己部署也行
项目本身开源,本仓库提供测试数据。Maven 装依赖,maven package 打成 fat jar,配置好 Redis 把 dump.rdb 导进去,启动命令跑起来:
java -server -jar yiyan-1.0-fat.jar -conf conf.json
要 IDE 调试,启动类 io.vertx.core.Launcher,参数 run ma.luan.yiyan.MainVerticle -conf src/main/resources/conf.json。
想自己采数据也可以,照着原有 Redis 里的 key 格式来。每个分类一个 set,set 里存 json 字符串或者 base64 加密的图片。日志会自动添加,help 字段可选,其余字段自己填 json 和 img 两个 key 集。
5、 一点版本历史
2018 年 8 月初版本上线,1.0 支持四种格式返回和分类搜索。
1.1 引入前缀树,分类检索从 O(n) 优化到 O(L),n 为分类总数,L 为分类级数。代价是空间复杂度从 O(n) 涨到 O(nL),代码多了六十行。同一次更新里规范了地址参数的正则匹配,补全了全局错误处理覆盖 Router 和 EventBus 两条路径。
1.3 让 SVG 支持自定义字体大小和字间距。1.4 补全单元测试、优化启动流程、升级依赖版本。
6、 已经有新版了
作者另外做了一个今日诗词 API,地址 https://www.jinrishici.com,不开源但免费调用。
新版可以根据地点、时间、节日、季节、天气、景观、城市做智能推荐。Gushici 这个仓库继续开源维护,给想要自建或者跑测试数据的人用。
名句数据由古诗文网整理,特此致谢。
新版可以根据地点、时间、节日、季节、天气、景观、城市做智能推荐。Gushici 这个仓库继续开源维护,给想要自建或者跑测试数据的人用。
名句数据由古诗文网整理,特此致谢。
1444



被折叠的 条评论
为什么被折叠?



