Golang TMDB API v3 封装库使用指南

TMDB (The Movie Database) 是一个流行的电影和电视节目数据库，提供了丰富的API。golang-tmdb 是一个用于访问TMDB API v3的Golang封装库。

安装

首先安装golang-tmdb库：

go get github.com/cyruzin/golang-tmdb

基本使用

初始化客户端

package main

import (
	"fmt"
	"log"

	tmdb "github.com/cyruzin/golang-tmdb"
)

func main() {
	// 使用你的TMDB API密钥初始化客户端
	tmdbClient, err := tmdb.Init("your-api-key-here")
	if err != nil {
		log.Fatal(err)
	}

	// 可选: 设置语言(默认为en-US)
	tmdbClient.SetClientAutoRetry()
	tmdbClient.SetLanguage("zh-CN")
}

获取电影详情

func getMovieDetails(client *tmdb.Client, movieID int64) {
	// 获取电影详情
	movie, err := client.GetMovieDetails(movieID, nil)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Printf("电影标题: %s\n", movie.Title)
	fmt.Printf("上映日期: %s\n", movie.ReleaseDate)
	fmt.Printf("简介: %s\n", movie.Overview)
	fmt.Printf("评分: %.1f\n", movie.VoteAverage)
}

搜索电影

func searchMovies(client *tmdb.Client, query string) {
	options := map[string]string{
		"query": query,
	}

	// 搜索电影
	result, err := client.GetSearchMovies(options)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Printf("找到 %d 部电影\n", result.TotalResults)
	for _, movie := range result.Results {
		fmt.Printf("- %s (%s)\n", movie.Title, movie.ReleaseDate)
	}
}

获取热门电影

func getPopularMovies(client *tmdb.Client) {
	options := map[string]string{
		"page": "1",
	}

	// 获取热门电影
	movies, err := client.GetMoviePopular(options)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println("当前热门电影:")
	for _, movie := range movies.Results {
		fmt.Printf("- %s (评分: %.1f)\n", movie.Title, movie.VoteAverage)
	}
}

获取电影图片

func getMovieImages(client *tmdb.Client, movieID int64) {
	// 获取电影图片
	images, err := client.GetMovieImages(movieID, nil)
	if err != nil {
		log.Fatal(err)
	}

	if len(images.Backdrops) > 0 {
		// 获取第一张背景图
		imageURL := "https://image.tmdb.org/t/p/original" + images.Backdrops[0].FilePath
		fmt.Printf("背景图URL: %s\n", imageURL)
	}

	if len(images.Posters) > 0 {
		// 获取第一张海报
		posterURL := "https://image.tmdb.org/t/p/original" + images.Posters[0].FilePath
		fmt.Printf("海报URL: %s\n", posterURL)
	}
}

高级功能

使用选项参数

许多API方法接受选项参数来过滤结果：

func getMoviesWithOptions(client *tmdb.Client) {
	options := map[string]string{
		"page":            "1",
		"language":        "zh-CN",
		"region":          "CN",
		"include_adult":   "false",
		"primary_release_year": "2023",
	}

	movies, err := client.GetDiscoverMovie(options)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println("2023年发行的电影:")
	for _, movie := range movies.Results {
		fmt.Printf("- %s\n", movie.Title)
	}
}

处理分页

func getAllPopularMovies(client *tmdb.Client) {
	var allMovies []*tmdb.MovieShort

	page := 1
	totalPages := 1

	for page <= totalPages {
		options := map[string]string{
			"page": fmt.Sprintf("%d", page),
		}

		result, err := client.GetMoviePopular(options)
		if err != nil {
			log.Fatal(err)
		}

		allMovies = append(allMovies, result.Results...)
		totalPages = result.TotalPages
		page++
	}

	fmt.Printf("总共获取了 %d 部热门电影\n", len(allMovies))
}

错误处理

func safeGetMovieDetails(client *tmdb.Client, movieID int64) {
	movie, err := client.GetMovieDetails(movieID, nil)
	if err != nil {
		if tmdbErr, ok := err.(*tmdb.Error); ok {
			fmt.Printf("TMDB API错误: %s (状态码: %d)\n", tmdbErr.Message, tmdbErr.StatusCode)
			return
		}
		log.Fatal(err)
	}

	fmt.Printf("成功获取电影: %s\n", movie.Title)
}

完整示例

package main

import (
	"fmt"
	"log"

	tmdb "github.com/cyruzin/golang-tmdb"
)

func main() {
	// 初始化客户端
	tmdbClient, err := tmdb.Init("your-api-key-here")
	if err != nil {
		log.Fatal(err)
	}

	// 设置中文
	tmdbClient.SetLanguage("zh-CN")

	// 搜索电影
	searchMovies(tmdbClient, "复仇者联盟")

	// 获取特定电影详情
	getMovieDetails(tmdbClient, 299536) // 复仇者联盟3:无限战争

	// 获取热门电影
	getPopularMovies(tmdbClient)
}

// 其他函数定义同上...

注意事项

1. 确保遵守TMDB API的使用条款
2. 考虑实现缓存机制以减少API调用
3. 处理API速率限制(默认每秒40次请求)
4. 对于生产环境，考虑使用环境变量存储API密钥

这个封装库提供了对TMDB API的全面访问，包括电影、电视节目、人物、搜索等功能。更多详细用法可以参考库的GitHub页面和TMDB官方API文档。