从0到1开发Petdex插件：开发者必看的API参考手册

从0到1开发Petdex插件开发者必看的API参考手册【免费下载链接】petdexThe public gallery of animated pet for Codex, Claude Code, OpenCode y Gemini CLI项目地址: https://gitcode.com/gh_mirrors/pe/petdexPetdex是一个为Codex、Claude Code、OpenCode和Gemini CLI提供动画宠物的公共图库项目开发者可以通过其开放API轻松构建各种宠物交互插件。本手册将详细介绍如何利用Petdex API快速开发自己的插件从环境搭建到核心功能实现帮助你顺利完成插件开发之旅。快速入门Petdex API基础Petdex提供了简洁易用的RESTful API让开发者能够轻松获取宠物数据、实现交互功能。所有API端点均遵循标准HTTP协议返回JSON格式数据无需复杂的认证流程即可访问公共资源。核心API端点概览Petdex的API系统主要包含以下核心端点覆盖了从宠物数据获取到用户交互的完整功能宠物清单API/api/manifest- 获取所有已批准宠物的元数据包括slug、精灵图URL和动画状态随机宠物API/api/pets/random- 获取随机宠物信息支持排除指定宠物宠物点赞API/api/pets/[slug]/like- 实现对特定宠物的点赞/取消点赞功能这些API端点构成了插件开发的基础无论是构建宠物展示界面还是实现互动功能都离不开对这些接口的调用。API调用示例使用curl命令即可快速测试Petdex API# 获取宠物清单 curl https://petdex.dev/api/manifest # 获取随机宠物 curl https://petdex.dev/api/pets/random # 为指定宠物点赞 curl -X POST https://petdex.dev/api/pets/nukey/like -d {liked: true}环境搭建开发前的准备工作在开始开发Petdex插件之前需要准备好基础开发环境。以下是推荐的开发配置确保你能够顺利调用Petdex API并处理返回数据。推荐开发环境Node.jsv18.0.0或更高版本包管理器npm、yarn或bun代码编辑器VS Code推荐安装REST Client插件项目初始化通过以下命令快速创建一个Petdex插件项目# 克隆仓库 git clone https://gitcode.com/gh_mirrors/pe/petdex # 进入项目目录 cd petdex # 安装依赖 bun installAPI访问配置Petdex API默认不需要认证即可访问公共资源。对于需要用户身份的操作如点赞API会通过Clerk处理用户认证。在开发环境中可以通过设置环境变量来配置API访问# .env文件示例 PETDEX_API_BASEhttps://petdex.dev核心API详解构建插件的关键宠物清单API获取宠物数据/api/manifest是Petdex最核心的API端点它返回所有已批准宠物的元数据。这个API是构建宠物展示功能的基础几乎所有插件都需要调用它来获取宠物信息。请求示例async function fetchPets() { const response await fetch(https://petdex.dev/api/manifest); if (!response.ok) { throw new Error(API请求失败: ${response.status}); } return response.json(); }响应结构API返回的JSON数据包含一个宠物对象数组每个对象包含以下关键字段slug宠物的唯一标识符displayName宠物的显示名称description宠物的描述信息spritesheetUrl精灵图的URL地址animationStates动画状态信息包括各种动作的帧数据缓存策略为了提高性能并减少API请求次数Petdex API采用了合理的缓存策略浏览器缓存public, max-age3005分钟CDN缓存public, s-maxage300, stale-while-revalidate36005分钟CDN缓存1小时后台更新这意味着你的插件应该处理可能的缓存数据并在必要时强制刷新。随机宠物API实现宠物随机展示/api/pets/random端点用于获取随机宠物非常适合实现随机宠物功能或宠物推荐系统。请求参数exclude可选需要排除的宠物slug用于避免重复展示请求示例async function getRandomPet(excludeSlug ) { const url new URL(https://petdex.dev/api/pets/random); if (excludeSlug) { url.searchParams.set(exclude, excludeSlug); } const response await fetch(url, { headers: { Accept: application/json } }); if (!response.ok) { throw new Error(随机宠物请求失败: ${response.status}); } return response.json(); }响应结构API返回单个宠物的详细信息包括slug宠物唯一标识符displayName宠物显示名称description宠物描述spritesheetPath精灵图路径href宠物详情页URLinstallHref宠物安装URL图使用随机宠物API构建的平台游戏示例展示了如何将API返回的宠物数据集成到游戏中宠物点赞API实现用户互动功能/api/pets/[slug]/like端点允许用户为喜欢的宠物点赞或取消点赞是构建用户互动功能的关键API。请求方法POST切换点赞状态或设置特定状态GET获取当前点赞数和用户点赞状态请求示例点赞async function likePet(slug, liked true) { const response await fetch(https://petdex.dev/api/pets/${slug}/like, { method: POST, headers: { Content-Type: application/json }, body: JSON.stringify({ liked }) }); if (!response.ok) { throw new Error(点赞请求失败: ${response.status}); } return response.json(); }请求示例获取点赞状态async function getLikeStatus(slug) { const response await fetch(https://petdex.dev/api/pets/${slug}/like); if (!response.ok) { throw new Error(获取点赞状态失败: ${response.status}); } return response.json(); }响应结构count总点赞数liked当前用户是否已点赞需要认证实战案例构建你的第一个Petdex插件桌面宠物插件下面我们将创建一个简单的桌面宠物插件展示如何使用Petdex API实现基本功能。这个插件将从Petdex获取随机宠物并在桌面上显示宠物动画。图桌面宠物插件的设置界面可配置API密钥和宠物行为实现步骤获取宠物数据使用/api/manifest获取宠物列表选择随机宠物使用/api/pets/random获取随机宠物显示宠物动画解析精灵图和动画状态实现动画效果添加互动功能使用点赞API实现用户互动核心代码示例// 插件主类 class PetdexDesktopPlugin { constructor() { this.pet null; this.manifest null; this.init(); } async init() { try { // 初始化时获取宠物清单 await this.fetchManifest(); // 获取随机宠物 await this.getRandomPet(); // 显示宠物 this.renderPet(); } catch (error) { console.error(插件初始化失败:, error); } } async fetchManifest() { const response await fetch(https://petdex.dev/api/manifest); this.manifest await response.json(); console.log(获取宠物清单成功共, this.manifest.length, 个宠物); } async getRandomPet() { const response await fetch(https://petdex.dev/api/pets/random, { headers: { Accept: application/json } }); this.pet await response.json(); console.log(随机宠物:, this.pet.displayName); } renderPet() { // 创建宠物元素 const petElement document.createElement(div); petElement.className petdex-pet; petElement.style.position fixed; petElement.style.bottom 20px; petElement.style.right 20px; // 设置宠物精灵图 const sprite document.createElement(img); sprite.src this.pet.spritesheetUrl; sprite.alt this.pet.displayName; petElement.appendChild(sprite); document.body.appendChild(petElement); // 添加点赞按钮 const likeButton document.createElement(button); likeButton.textContent 点赞; likeButton.addEventListener(click, () this.likeCurrentPet()); petElement.appendChild(likeButton); } async likeCurrentPet() { try { const result await fetch(https://petdex.dev/api/pets/${this.pet.slug}/like, { method: POST, headers: { Content-Type: application/json }, body: JSON.stringify({ liked: true }) }); const data await result.json(); alert(点赞成功当前点赞数: ${data.count}); } catch (error) { console.error(点赞失败:, error); } } } // 初始化插件 window.addEventListener(load, () new PetdexDesktopPlugin());宠物展示网站另一个常见的插件类型是宠物展示网站它可以展示Petdex中的各种宠物并允许用户浏览、搜索和互动。图Petdex Dock项目仓库示例展示了如何组织宠物插件项目结构关键功能实现宠物列表展示使用/api/manifest获取所有宠物并分页展示宠物搜索功能根据名称、描述等字段筛选宠物宠物详情页展示单个宠物的详细信息和动画用户互动实现点赞、收藏等功能项目结构建议petdex-plugin/ ├── src/ │ ├── api/ # API调用函数 │ ├── components/ # UI组件 │ ├── pages/ # 页面组件 │ └── utils/ # 工具函数 ├── public/ # 静态资源 ├── package.json # 项目配置 └── README.md # 项目文档高级技巧优化你的Petdex插件缓存策略优化为了提高插件性能并减少API请求可以实现多级缓存策略内存缓存将频繁访问的宠物数据缓存在内存中本地存储使用localStorage或IndexedDB缓存宠物清单服务端缓存利用Petdex API的缓存头实现智能缓存错误处理最佳实践API调用可能会遇到各种错误良好的错误处理可以提高插件的稳定性async function safeApiCall(url, options {}) { try { const response await fetch(url, options); if (!response.ok) { // 处理HTTP错误 const errorData await response.json().catch(() null); throw new Error(API错误: ${response.status} ${errorData?.error || }); } return response.json(); } catch (error) { // 处理网络错误 console.error(API调用失败:, error.message); // 尝试使用缓存数据 const cachedData getFromCache(url); if (cachedData) { console.warn(使用缓存数据); return cachedData; } // 抛出错误或返回默认数据 throw error; } }性能优化建议精灵图优化使用WebP格式并适当压缩精灵图懒加载只加载当前可见的宠物数据和图片请求合并减少API调用次数合并相关请求Web Worker在后台处理复杂数据解析避免阻塞主线程常见问题解答API请求限制Petdex API对未认证请求有一定的速率限制通常为每分钟60次请求。如果需要更高的请求配额可以通过以下方式解决实现缓存减少重复请求批量请求尽可能合并多个请求认证请求通过Clerk认证可以获得更高的配额宠物数据更新Petdex定期更新宠物数据包括新增宠物和更新现有宠物信息。为了确保插件展示最新数据可以监听API返回的Last-Modified头定期如每天刷新宠物清单缓存使用s stale-while-revalidate模式实现后台更新跨域请求处理Petdex API已配置CORS允许来自任何域的请求。如果遇到跨域问题请检查请求头是否包含正确的Origin是否使用了正确的HTTP方法是否包含必要的请求头总结与下一步通过本手册你已经了解了Petdex API的核心功能和使用方法以及如何构建基本的Petdex插件。现在你可以开始开发自己的插件并探索更多高级功能。推荐学习资源项目文档CONTRIBUTING.mdAPI源码src/app/api/示例项目packages/社区支持如果你在开发过程中遇到问题可以通过以下方式获取帮助查看项目的issues页面参与项目讨论提交PR贡献代码现在是时候开始你的Petdex插件开发之旅了无论是桌面应用、网页插件还是移动应用Petdex API都能为你提供丰富的宠物数据和互动功能帮助你构建令人惊叹的宠物应用。【免费下载链接】petdexThe public gallery of animated pet for Codex, Claude Code, OpenCode y Gemini CLI项目地址: https://gitcode.com/gh_mirrors/pe/petdex创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考