🚀 GetPackageChanges

获取 Packagist 包元数据的增量变更记录，用于自建镜像的增量同步。

何时使用

🛠️ 自建 Packagist 镜像，避免每次全量拉取；🔍 监控哪些包被新增 / 更新 / 删除；⏱️ 需要可断点续传、按时间游标推进的同步任务。

签名

func (c *ComposerClient) GetPackageChanges(ctx context.Context, since int64) (*domain.ChangeTrackingResponse, error)

参数

参数	类型	说明
ctx	context.Context	上下文，用于超时与取消
since	int64	增量游标（Unix 时间戳）；传 0 返回当前时间戳但 Actions 为空，用于首次获取游标

返回值

值	类型	说明
结果	*domain.ChangeTrackingResponse	含 Timestamp（下次游标）与 Actions 变更列表，Type 为 update/delete
错误	error	HTTP 失败、非 200、JSON 解析失败时返回

对应端点：GET https://packagist.org/metadata/changes.json?since={timestamp}。

示例

package main

import (
	"context"
	"fmt"
	"log"
	"time"

	"github.com/scagogogo/composer-skills/pkg/client"
)

func main() {
	c := client.NewComposerClient(30 * time.Second)
	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
	defer cancel()

	// 首次同步：拿一个起始游标
	resp, err := c.GetPackageChanges(ctx, 0)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("起始游标: %d\n", resp.Timestamp)

	// 下次用这个游标做增量
	resp, err = c.GetPackageChanges(ctx, resp.Timestamp)
	if err != nil {
		log.Fatal(err)
	}
	for _, a := range resp.Actions {
		fmt.Printf("[%s] %s @ %d\n", a.Type, a.Package, a.Time)
	}
	fmt.Printf("下次游标: %d\n", resp.Timestamp)
}

进阶

增量同步模式

since=0 时只返回当前 Timestamp 而不返回历史变更。正确做法是：① 先用 since=0 拿到起始 Timestamp 并持久化；② 此后每次用上次的 Timestamp 作为 since，处理返回的 Actions，再保存新的 Timestamp。若 since 无效，响应 Error 字段会有错误说明。

• 📦 对 Type=update 的包调 GetPackage 刷新本地缓存，对 Type=delete 的包从本地删除。
• 🧩 V2 镜像用 GetPackageWithV2Metadata。