把 GoAnime 当库用：pkg/goanime 客户端二次开发完全指南-平芜编程栈

【免费下载链接】GoAnime

Search, stream and download anime, movies and TV shows from the terminal, in English and Brazilian Portuguese.

项目地址：https://gitcode.com/gh_mirrors/go/GoAnime

GoAnime 是一款在终端搜索、流媒体播放和下载动漫、电影与剧集的开源 Go 项目。除了直接运行 CLI，它还提供了一条干净、类型安全的 Go 库入口pkg/goanime，让你在自己的 Go 项目中几行代码就能完成「动漫搜索 → 剧集列表 → 流媒体地址解析」的全流程。本文带你快速上手 GoAnime 库客户端，并覆盖二次开发中常用的进阶技巧。

📦 先认识 pkg/goanime：它能做什么

pkg/goanime是从 CLI 内部实现中抽取出来的公开 API（public API），设计上刻意保持简单：

能力	方法	说明
多源搜索	`SearchAnime`	跨 AllAnime、AnimeFire 等多个源并发搜索
剧集管理	`GetAnimeEpisodes`	获取带元数据的完整剧集列表
流地址解析	`GetEpisodeStreamURL`	返回可直接播放的视频 URL 与请求头
源管理	`GetAvailableSources`	列出当前可用的抓取源

核心客户端定义在 pkg/goanime/client.go，公开类型定义在 pkg/goanime/types/anime.go 与 pkg/goanime/types/source.go。整体文档入口是 pkg/README.md，中文集成思路可参考 docs/LIBRARY_USAGE.md。

🚀 一键接入：在你的项目里引用 GoAnime 库

方式一：直接通过 Go Modules 引入

go get github.com/alvarorichard/Goanime

方式二：先克隆仓库，再用replace指向本地副本（推荐二次开发）

git clone https://gitcode.com/gh_mirrors/go/GoAnime go mod edit -replace github.com/alvarorichard/Goanime=./GoAnime

本地replace的好处是：你可以直接阅读 pkg/goanime/examples/ 下的官方示例，也可以随时打补丁做实验而不污染依赖。

导入包之后，第一个程序只需不到 15 行：

client := goanime.NewClient() results, err := client.SearchAnime("One Piece", nil) // nil = 搜索所有源

🔍 三步调用客户端：搜索 → 剧集 → 播放地址

GoAnime 客户端的调用链路非常线性，记住这三步即可完成 90% 的场景（签名见 pkg/goanime/client.go）：

搜索：client.SearchAnime("Attack on Titan", nil)，返回[]*types.Anime；
取剧集：用搜索结果里的anime.URL与解析出的源，调用client.GetAnimeEpisodes(anime.URL, source)；
取流地址：推荐用client.GetEpisodeStreamURL(anime, episode, options)，返回(streamURL, headers, error)。

最小完整示例：

results, _ := client.SearchAnime("Demon Slayer", nil) anime := results[0] source, _ := types.ParseSource(anime.Source) episodes, _ := client.GetAnimeEpisodes(anime.URL, source) url, headers, _ := client.GetEpisodeStreamURL(anime, episodes[0], nil) fmt.Println(url) // 可直接交给 mpv / ffmpeg 播放

💡 旧方法GetStreamURL已被标记为Deprecated，新代码请直接使用GetEpisodeStreamURL（见 pkg/goanime/client.go）。

🎚️ StreamOptions 进阶：控制清晰度与字幕/配音

GetEpisodeStreamURL接受一个可选的StreamOptions结构体，这是二次开发中最实用的控制点：

goanime.StreamOptions{ Quality: "720p", // best / worst / 1080p / 720p / 480p / 360p Mode: "sub", // sub（字幕版）或 dub（配音版） }

传入nil时使用DefaultStreamOptions()（最高画质 + 字幕版），逻辑见 pkg/goanime/client.go。做播放器 App 时，把这两个字段接到 UI 的画质/版本切换开关上即可。

📊 类型系统：Anime 与 Episode 里有什么

库对元数据的暴露相当丰富，主要类型定义见 pkg/goanime/types/anime.go：

types.Anime：标题、源内 URL、封面图、AniList ID、MAL ID，以及Details扩展字段（类型、评分、状态等 AniList 元数据）；
types.Episode：集数、多语言标题、时长、播出日期、IsFiller/IsRecap标志（方便过滤水/回忆集），还有SkipTimes片头片尾跳过时间点；
types.Source：当前公开SourceAllAnime与SourceAnimeFire两个源，ParseSource支持大小写不敏感的字符串解析，定义在 pkg/goanime/types/source.go。

一个实用技巧：搜索时传&types.SourceAllAnime可以锁定单一源，避免多源结果混排（参考 pkg/goanime/examples/source_specific/main.go）。

⚠️ 错误处理与三个常见坑

1. 源暂时不可用

库导出了哨兵错误ErrSourceUnavailable，上游源被限流或宕机时会返回它，建议用errors.Is判断后做降级或重试：

if errors.Is(err, goanime.ErrSourceUnavailable) { // 切换其他源或稍后重试 }

定义见 pkg/goanime/errors.go。

2. 流地址会过期

GetEpisodeStreamURL返回的 URL 有有效期，播放前再解析，不要把地址长期缓存。

3. 别忘了请求头

部分源要求携带特定 Header（如 Referer）才能播放，第二个返回值headers必须随请求一起发出，交给 mpv 时对应--http-header-fields参数。

🧪 官方示例与测试：现成的学习材料

examples 目录提供 4 个可直接运行的示例程序，建议按顺序跑一遍：

示例	路径	演示内容
基础搜索	pkg/goanime/examples/search/main.go	多源搜索并打印元数据
剧集列表	pkg/goanime/examples/episodes/main.go	遍历一部的所有集
流地址	pkg/goanime/examples/stream/main.go	用`StreamOptions`取可播放 URL
指定源搜索	pkg/goanime/examples/source_specific/main.go	单独搜索 AllAnime / AnimeFire

运行方式：go run ./pkg/goanime/examples/search/main.go。

库自带完整的单元测试与集成测试，本地验证可用：

go test ./pkg/goanime/... # 全量测试 go test -short ./pkg/goanime/... # 仅单元测试

❓ 二次开发常见问题

Q：可以在服务端 Web API 里用这个库吗？可以。所有导出函数都安全于并发使用，NewClient()无全局状态，适合 HTTP handler 中创建或复用客户端。

Q：所有动漫都有完整元数据吗？不是。Details（评分、类型等）依赖 AniList 匹配结果，个别条目可能为空，使用前判空即可。

Q：库会帮我做限流吗？是的，库内部已处理 rate limiting；但仍建议对高频调用做退避，尤其处理ErrSourceUnavailable时。

✅ 小结

pkg/goanime用「NewClient→SearchAnime→GetAnimeEpisodes→GetEpisodeStreamURL」一条极简链路，把 GoAnime CLI 背后的多源抓取能力完整开放给 Go 开发者：类型安全、自带元数据、可控制清晰度与字幕/配音模式。配合 pkg/goanime/client.go 的源码与 docs/LIBRARY_USAGE.md 的集成文档，你可以在一天内做出属于自己的动漫搜索、聚合播放或下载工具。🎬