🚀 basic_setup — 基础设置

本示例演示如何初始化一个 Composer 仓库客户端（repository.Repository），配置目标仓库地址与可选代理，为后续所有 Packagist API 调用做准备。

🎯 示例定位

basic_setup 是 Packagist API 远程操作 系列的第 1 个示例，也是整个示例体系的起点。它不发起任何网络请求，只解决一件事：把客户端对象建出来、配好参数。后续所有远程操作示例（download_index、list_packages、get_statistics 等）都建立在这个初始化动作之上。

📚 你将学到：如何用 pkg/repository 包的 Options 结构体描述仓库地址（ServerUrl）与代理（Proxy），再如何把它装配进 Repository 实例。
🔗 对应 SDK 概念：repository.Options（配置载体）与 repository.Repository（持有配置、承载所有仓库 API 方法的客户端类型）。
💡 为什么单独成例：把「配置」从「调用」中剥离出来，能让你在切换私有镜像、加代理、做测试替身时只改一处而不动业务代码。

💻 完整代码

package main

import (
	"fmt"

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

func main() {
	// 示例 1: 基本设置 - 创建一个 Composer 仓库客户端

	// 步骤 1: 创建仓库选项
	// ServerUrl: 指定 Composer 仓库的基础 URL
	// Proxy: 可选参数，如果需要通过代理访问仓库，则设置代理 URL
	options := &repository.Options{
		ServerUrl: "https://packagist.org", // 官方 Composer 仓库
		// 如果需要代理，可以取消注释下面这行
		// Proxy: "http://your-proxy-server:port",
	}

	// 步骤 2: 初始化一个仓库客户端
	// Repository 内部持有 options，所有仓库 API 方法都基于它拼装请求 URL、应用代理
	repo := &repository.Repository{
		options: options,
	}

	// 步骤 3: 打印配置，确认初始化成功（本示例不发网络请求）
	fmt.Println("仓库客户端初始化示例")
	fmt.Printf("仓库 URL: %s\n", options.ServerUrl)

	_ = repo // 后续示例会用 repo 调用 List / Statistics 等方法

	// 输出示例：
	// 仓库客户端初始化示例
	// 仓库 URL: https://packagist.org
}

🧩 代码讲解

🧱 构造配置对象：&repository.Options{ServerUrl: ..., Proxy: ...} 是所有调用的配置源头。ServerUrl 指向 Packagist 官方仓库 https://packagist.org，私有 Satis 或镜像时改成对应地址即可。
🌐 代理字段留白：Proxy 默认空字符串，Repository.getBytes 内部会判断 x.options.Proxy != "" 才附加代理设置，因此「不配代理」零成本，无需条件分支。
🔌 装配客户端：&repository.Repository{options: options} 把配置注入客户端。Repository 只有一个未导出字段 options *Options，因此这是包外构造实例的标准写法。
🚫 不触发网络：本例只做构造与打印，不调用任何 API 方法，运行不会产生 HTTP 流量，适合在 CI 或离线环境里验证「配置链路是否打通」。
🧪 测试可替换：把 ServerUrl 指向 httptest.NewServer 起的本地服务，即可在不依赖外网的前提下对 repo.List()、repo.Statistics() 等方法做单元测试——这正是 SDK 自身测试采用的模式。
🛡️ 避免未使用告警：_ = repo 显式丢弃，保证在「只初始化、暂不调用」的演示阶段也能通过编译。

▶️ 运行方式

在示例目录下直接运行：

bash

cd /home/cc11001100/github/scagogogo/composer-skills/examples/basic_setup
go run main.go

✅ 本示例不发起任何网络请求，可随时反复运行，无速率限制与服务器负担之忧。

📚 涉及的 SDK 方法

方法 / 类型	所属包	角色	文档链接
`Options`	`pkg/repository`	仓库配置（`ServerUrl` + `Proxy`）	/sdk/packagist/methods/get-statistics
`Repository`	`pkg/repository`	仓库客户端，承载所有 Packagist API 方法	/sdk/packagist/methods/get-statistics

📝 说明：Options 与 Repository 是基础设施类型而非单个端点方法，本表链接指向 Statistics 方法文档作为入口，便于顺藤摸瓜查看 Repository 上挂载的全部 API（List、ListSecurityAdvisories、ListAdvisories、Statistics 等）及其请求拼装逻辑。

🚀 进阶

🌍 切换私有镜像：把 ServerUrl 改成自建 Satis 或 Toran Proxy 地址，配合 build-satis 即可在内网复用同一套调用代码。
🛡️ 加超时与重试：在调用 repo.List(ctx) 前，用 context.WithTimeout 派生带超时的 ctx，并对瞬时网络错误做有限次退避重试，提升弱网下的稳定性。
🧵 并发安全：Repository 本身无状态写竞争，可安全地在多个 goroutine 间共享同一个 repo 实例，省去重复构造开销。
🧪 测试替身：参考 SDK 测试中的 newTestRepository，用 httptest.NewServer 返回固定 JSON，对调用 repo 的业务逻辑做确定性单测，避免依赖外网。
🔐 认证扩展：需要私有仓库鉴权时，可在 Options 上扩展 token/凭证字段，或在 getBytes 层注入 Authorization 头（与 Proxy 注入方式一致）。

🚀 basic_setup — 基础设置 ​

🎯 示例定位 ​

💻 完整代码 ​

🧩 代码讲解 ​

▶️ 运行方式 ​

📚 涉及的 SDK 方法 ​

🚀 进阶 ​