一、写在前面为什么需要随机诗词API很多开发者想在个人网站、博客或管理后台的空白区域增加一点文化气息——随机展示一首古诗词既优雅又能缓解页面空洞感。但真正动手时却容易陷入几个困境找不到稳定又免费的诗词接口试了几个要么挂掉要么返回格式混乱前端跨域报错本地开发好好的部署后却拿不到数据没有做错误处理接口一旦超时或限流页面直接白屏随机逻辑太简陋每次刷新重复率高体验打折。本文以「今日诗词」这款公开免费的随机诗词API为例你同样可以在ApiZero等聚合平台上找到同类接口一步步带你完成从调试、封装到完整Vue组件开发的全流程并总结5个最容易被忽视的坑。代码全部可运行复制到项目里稍作修改就能用。二、API 选择与调试2.1 接口推荐我们选用https://v1.jinrishici.com/all.json这是一个长期维护的免费接口返回随机诗词包含诗句、出处、作者。你也可以在 ApiZero 平台上找到类似的随机诗词API并在线调试。两个平台都支持 HTTPS不需要申请key开箱即用。2.2 接口返回格式用浏览器或Postman请求该地址得到类似以下JSON{ content: 床前明月光疑是地上霜。, origin: 静夜思, author: 李白, category: 唐诗 }注若返回空或异常说明接口暂时不可用建议换用ApiZero上的备用接口。2.3 快速验证打开浏览器DevTools - Console直接执行fetch(https://v1.jinrishici.com/all.json) .then(res res.json()) .then(console.log) .catch(console.error)看到json对象就说明通了。三、Vue 项目集成步骤3.1 初始化项目 安装依赖# 用Vite创建Vue3项目 npm create vitelatest poetry-app -- --template vue cd poetry-app npm install # 安装请求库 npm install axios3.2 封装请求模块src/utils/request.jsimport axios from axios const api axios.create({ baseURL: https://v1.jinrishici.com, timeout: 5000 }) // 响应拦截器 api.interceptors.response.use( response { const data response.data // 统一处理业务码这里接口直接返回正文不需要额外逻辑 return data }, error { console.error(请求失败:, error.message) return Promise.reject(error) } ) export default api3.3 创建诗词API服务src/api/poetry.jsimport request from /utils/request export function getRandomPoetry() { return request.get(/all.json) }3.4 编写组件src/components/PoetryDisplay.vuetemplate div classpoetry-card div v-ifloading classloading正在为您寻诗.../div div v-else-iferror classerror p☹️ 诗意暂时迷路了/p button clickfetchPoetry再试一次/button /div div v-else classpoetry-content p classcontent{{ poetry.content }}/p p classsource—— {{ poetry.author }}《{{ poetry.origin }}》/p /div /div /template script setup import { ref, onMounted } from vue import { getRandomPoetry } from /api/poetry const poetry ref({ content: , origin: , author: }) const loading ref(true) const error ref(false) const fetchPoetry async () { loading.value true error.value false try { const res await getRandomPoetry() poetry.value { content: res.content || 无题, origin: res.origin || 佚名, author: res.author || 无名氏 } } catch (e) { error.value true } finally { loading.value false } } onMounted(fetchPoetry) /script style scoped .poetry-card { padding: 20px; background: #f9f7f1; border-radius: 8px; text-align: center; min-height: 120px; } .content { font-size: 1.2rem; color: #333; line-height: 1.8; } .source { margin-top: 12px; color: #999; font-style: italic; } .error button { padding: 6px 16px; border: 1px solid #ccc; border-radius: 4px; cursor: pointer; } /style3.5 在页面中使用src/App.vuetemplate div classapp h1今日·诗意/h1 PoetryDisplay / /div /template script setup import PoetryDisplay from ./components/PoetryDisplay.vue /script四、5个常见坑与排查方法下表整理了集成随机诗词API时最容易被忽视的问题每个都配有解决方案。坑点典型现象原因解决方案跨域报错Access-Control-Allow-Origin缺失浏览器同源策略开发环境用Vite proxy生产环境后端转发或要求服务商开CORS接口限流突然返回空或503API有每分钟/小时请求限制前端加本地缓存localStorage相同诗词不再重复请求或使用防抖字段名变化渲染为“undefined”接口升级或备用接口字段不同映射时设置默认值如 res.content网络延迟页面长时间空白无加载状态使用loading变量控制骨架屏或转圈同首循环两次刷新显示相同诗词接口伪随机短时间内重复客户端维护已显示列表结合数组去重后展示4.1 跨域终极方案Vite Proxy修改vite.config.jsexport default defineConfig({ server: { proxy: { /jinrishici: { target: https://v1.jinrishici.com, changeOrigin: true, rewrite: path path.replace(/^\/jinrishici/, ) } } } })然后请求改为/jinrishici/all.json。4.2 本地缓存避免重复请求const cache JSON.parse(localStorage.getItem(poetryCache) || []) // 获取新诗词时检查是否已经拉取过 const fetchUniquePoetry async () { let data do { data await getRandomPoetry() } while (cache.some(item item.content data.content)) cache.push(data) localStorage.setItem(poetryCache, JSON.stringify(cache.slice(-50))) // 保留最近50首 return data }五、最佳实践让诗词展示更优雅动画过渡使用Transition包裹内容切换时有淡入效果。随机刷新按钮加一个刷新图标触发fetchPoetry同时闪烁一下。多数据源fallback如果主接口挂了轮询备用接口例如ApiZero上的同类API。服务器端缓存SSR如果使用Nuxt可以在服务端预取一首诗词作为初始状态减少前端白屏时间。button clickrotatePoetry title换一首 随机 /button script setup const rotatePoetry async () { await fetchPoetry() // 触发CSS动画 animation.value true setTimeout(() animation.value false, 500) } /script六、总结本文从真实开发痛点出发带你走完了“选接口 → 调试 → 封装 → 组件化 → 避坑”的完整链路。核心公式是稳定API 合理的请求模块 完备的loading/error状态 兜底策略。如果你现在手头正有一个Vue项目不妨复制上面的PoetryDisplay.vue直接运行。遇到问题不要慌对照表格逐一排查。如果你在项目中遇到了类似接口调用报错比如其他古诗API、一言API等欢迎把错误信息贴在评论区我会按场景补充排查思路。收藏本文下次给网站加“诗意侧边栏”时就能直接用了。觉得有用的话点个赞再走呗
