如何根据 Spotube 插件数据模型字段定义构造 Endpoint 的正确返回对象【免费下载链接】spotube Open source music streaming app! Available for both desktop mobile!项目地址: https://gitcode.com/GitHub_Trending/sp/spotubeSpotube 插件用 hetu_script 编写负责为应用提供元数据专辑、歌手、曲目、搜索等。在实现插件时最容易出错的环节是Endpoint 类里的每个方法到底该返回什么结构。写错字段、漏掉必填项或用错对象层级Simple 与 Full 混用Spotube 侧就无法正确解析你的返回值。本文基于仓库内的插件开发文档说明如何从 Endpoint 方法定义 查到每个方法的返回类型再按 数据模型字段表 逐字段构造返回对象并通过模板仓库的 example 应用验证。开发准备按 开发入门文档 的要求需要具备基本编程知识以及 Dart、Flutter 基础一个代码编辑器文档推荐 Visual Studio Code可安装 Hetu Script 扩展获得基础语法高亮但无自动补全插件语言是 hetu_script一种 Dart 系的脚本语言语法接近 TypeScript。插件项目从文档指明的模板仓库初始化$ git clone https://github.com/KRTirtho/spotube-plugin-template.git $ cd spotube-plugin-template仓库根目录的plugins.json决定 Spotube 如何识别插件关键字段包括name、version遵循语义化版本、entryPoint插件入口类名、apis可用webview、localstorage、timezone和abilities可用authentication、scrobbling。修改这些值为你自己的插件信息。第一步确认你要实现的方法及其返回类型所有必须在生命周期中实现的方法都位于src/segments目录下的.ht文件中例如user.ht、track.ht、album.ht、artist.ht、playlist.ht、search.ht、browse.ht、core.ht。每个方法对应一个固定的返回类型节选自文档的方法-返回类型对照方法所在 Endpoint返回类型me()UserEndpointSpotubeUserObjectsavedTracks({ offset, limit })UserEndpointSpotubePaginationResponseObjectofSpotubeFullTrackObjectgetTrack(id)TrackEndpointSpotubeFullTrackObjectradio(id)TrackEndpointListSpotubeFullTrackObject文档建议返回 50 条getAlbum(id)AlbumEndpointSpotubeFullAlbumObjecttracks(id, { offset, limit })AlbumEndpointSpotubePaginationResponseObjectofSpotubeFullTrackObjectgetArtist(id)ArtistEndpointSpotubeFullArtistObjectgetPlaylist(id)PlaylistEndpointSpotubeFullPlaylistObjectall(query)SearchEndpointSpotubeSearchResponseObjecttracks(query, { offset, limit })SearchEndpointSpotubePaginationResponseObjectofSpotubeFullTrackObjectsections({ offset, limit })BrowseEndpointSpotubePaginationResponseObjectofSpotubeBrowseSectionObject注意两点文档明确给出的约束带分页的方法签名统一接收{ offset: int, limit: int }返回值必须包在分页响应对象里而不是裸数组。UserEndpoint的方法应尽可能只是对后端 API 的直接映射文档明确警告不要在这些方法里调用 WebView、Forms 等会产生用户交互的插件 API。第二步按模型字段表构造返回对象确定返回类型后逐字段对照 models.mdx 中的结构表。以getTrack(id)需要返回的SpotubeFullTrackObject为例文档定义的字段如下属性类型idstringnamestringexternalUristringartistsList ofSpotubeSimpleArtistObjectalbumSpotubeSimpleAlbumObjectdurationMs (in milliseconds)numberexplicitbooleanisrcstring几个容易构造错的细节全部来自字段表本身durationMs的单位是毫秒不是秒albumType只允许album、single、compilation三个值releaseDate格式为YYYY-MM-DDSimple 版本允许nullFull 版本必填SpotubeSimpleArtistObject.images与SpotubeSimplePlaylistObject.images允许null构造时可以省略内嵌对象同样要完整SpotubeSimpleArtistObject需要id、name、externalUri、imagesSpotubeImageObject列表后者含width/height可为 null与url。SpotubeSearchResponseObject有一个容易混淆的层级组合albums是 Simple 专辑列表而artists与tracks是 Full 列表playlists是 Simple 列表——构造搜索返回时不能四种对象都用同一层级。分页返回统一使用SpotubePaginationResponseObject字段为limit、nextOffset可为null、total、hasMore、itemsitems是泛型列表装你该方法约定的具体对象。BrowseEndpoint.sectionItems()返回的条目只能是SpotubeFullPlaylistObject、SpotubeFullArtistObject、SpotubeFullAlbumObject三种之一。第三步以 Map 形式返回hetu_script 的结构体在 Dart 侧是以Map消费的文档明确要求把 hetu_script struct 转成 Map惯用写法是调用.toJson()。文档给出的事件发送示例即是这一模式controller.add({ type: login }.toJson())因此你在src/segments各文件里实现方法时应让方法最终返回构造好的对象或 JSON Map而不是 Dart 端无法识别的原始结构。模板中的 endpoint 骨架以 UserEndpoint 为例如下来自 implementing-endpoints.mdxclass UserEndpoint { var client: HttpClient construct (this.client) fun me() { // TODO: Implement method } fun savedTracks({ offset: int, limit: int }) { // TODO: Implement method } // ... 其余方法同理 }入口类src/plugin.ht中的entryPoint类负责持有并注入这些 Endpoint 实例构造函数里创建HttpClient后逐个实例化其类名必须与plugins.json的entryPoint字段一致。编译与验证按 create-your-first-plugin.mdx 的流程验证你的返回值在系统装有make命令、且全局安装hetu_script_dev_tools包的前提下在项目根目录编译插件$ make模板自带一个exampleFlutter 应用会调用 Spotube 会对你的插件调用的所有方法。编译成功后运行它来测试插件功能$ cd example $ flutter run文档同时说明在方法实现之前example 应用里的大部分按钮不会工作——所以点击对应按钮、方法能被正常调用并返回符合上面字段表的数据就是文档给出的验证路径。没有实现的方法点下去没有结果属于预期现象而不是环境故障。限制与已知问题以下限制来自 implmenting-plugin-methods.mdx 的明确说明直接影响你如何写方法体hetu_script 声称支持 async/await但当时尚不可用文档要求使用.then()处理异步hetu_script 不支持错误处理没有 try/catch/finally 或.catch()这是语言的设计决策错误只能在 Dart 侧处理。另外plugins.json的apis字段决定插件能使用哪些 APIwebview、localstorage、timezone如果方法里用到 WebView 等能力需先确认已在其中声明。继续深入方法完整定义与各 Endpoint 说明implementing-endpoints.mdx全部数据模型字段表models.mdx插件可调用库hetu_std、hetu_spotube_plugin等libraries.mdx【免费下载链接】spotube Open source music streaming app! Available for both desktop mobile!项目地址: https://gitcode.com/GitHub_Trending/sp/spotube创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考