🏭 Satis

用 Go 编排 Satis 私有包仓库的配置生成与构建流程——创建 satis.json、追加仓库、构建静态仓库、调整稳定性、启用归档、追加依赖。

Satis 是 Composer 官方的私有包仓库生成器，把多个 VCS 仓库打包成一个可供 composer 拉取的静态仓库。Satis 本身是独立可执行文件，本模块假定它已通过 composer global require 安装并可被 composer satis 调用。

何时使用

• 🏢 企业内网要建一个私有 Composer 仓库镜像多个 GitLab 项目。
• 📦 CI 里把 Satis 配置的增改纳入版本控制，每次仓库变动后自动 build。
• 🔒 离线环境预构建归档（--archive），让部署机无需访问源码仓库。
• 🎛️ 动态切换最小稳定性（dev / RC / stable）以满足不同阶段需求。

结构化类型

SatisConfig

CreateSatisConfig 写出、AddSatisRepository 等方法读改的顶层结构。

type SatisConfig struct {
    Name                   string                 `json:"name"`
    Homepage               string                 `json:"homepage"`
    Repositories           []map[string]string    `json:"repositories"`
    OutputDir              string                 `json:"output-dir"`
    RequireAll             bool                   `json:"require-all,omitempty"`
    RequireDependencies    bool                   `json:"require-dependencies,omitempty"`
    RequireDevDependencies bool                   `json:"require-dev-dependencies,omitempty"`
    Require                map[string]string      `json:"require,omitempty"`
    Archive                map[string]interface{} `json:"archive,omitempty"`
    MinimumStability       string                 `json:"minimum-stability,omitempty"`
    Providers              bool                   `json:"providers,omitempty"`
    ProvidersURL           string                 `json:"providers-url,omitempty"`
    Config                 map[string]interface{} `json:"config,omitempty"`
    Notify                 map[string]interface{} `json:"notify,omitempty"`
    TwigTemplate           string                 `json:"twig-template,omitempty"`
}

方法签名

方法	签名	说明
🏗️ CreateSatisConfig	func (c *Composer) CreateSatisConfig(configPath string, name string, homepage string) error	写出初始 satis.json
➕ AddSatisRepository	func (c *Composer) AddSatisRepository(configPath string, type_ string, url string) error	追加一个仓库
🏭 BuildSatis	func (c *Composer) BuildSatis(configPath string, outputDir string) (string, error)	执行 satis build
🚀 InitSatis	func (c *Composer) InitSatis(name string, homepage string, dir string) error	创建目录并写出配置
🎚️ UpdateSatisStability	func (c *Composer) UpdateSatisStability(configPath string, stability string) error	更新最小稳定性
🗜️ EnableSatisArchive	func (c *Composer) EnableSatisArchive(configPath string, format string) error	启用归档功能
📌 AddSatisRequire	func (c *Composer) AddSatisRequire(configPath string, packageName string, version string) error	追加依赖并关闭 require-all

参数说明

CreateSatisConfig / InitSatis

参数	类型	说明
configPath / dir	string	配置文件路径 / 输出目录（InitSatis 在其下创建 satis.json）
name	string	仓库名称，如 acme/private-packages
homepage	string	仓库主页 URL，也是包被引用的根地址

AddSatisRepository

参数	类型	说明
type_	string	仓库类型，如 vcs、git、composer
url	string	仓库地址

UpdateSatisStability

参数	类型	说明
stability	string	必须是 dev / alpha / beta / RC / stable 之一

EnableSatisArchive

参数	类型	说明
format	string	归档格式，空则默认 zip

示例

从零初始化并构建

package main

import (
	"fmt"
	"log"

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

func main() {
	comp, err := composer.New(composer.DefaultOptions())
	if err != nil {
		log.Fatalf("初始化失败: %v", err)
	}

	// 初始化 satis 目录与配置
	if err := comp.InitSatis("acme/private-packages", "https://packages.acme.io", "satis"); err != nil {
		log.Fatal(err)
	}
	configPath := "satis/satis.json"

	// 追加两个 VCS 仓库
	if err := comp.AddSatisRepository(configPath, "vcs", "git@gitlab.acme.io:lib/logger.git"); err != nil {
		log.Fatal(err)
	}
	if err := comp.AddSatisRepository(configPath, "vcs", "git@gitlab.acme.io:lib/auth.git"); err != nil {
		log.Fatal(err)
	}

	// 启用归档 + 锁定稳定性
	if err := comp.EnableSatisArchive(configPath, "tar"); err != nil {
		log.Fatal(err)
	}
	if err := comp.UpdateSatisStability(configPath, "stable"); err != nil {
		log.Fatal(err)
	}

	// 构建
	out, err := comp.BuildSatis(configPath, "satis/public")
	if err != nil {
		log.Fatalf("构建失败: %v", err)
	}
	fmt.Println(out)
}

精确指定依赖（关闭 require-all）

// AddSatisRequire 会自动把 RequireAll 置为 false
if err := comp.AddSatisRequire(configPath, "acme/logger", "^2.0"); err != nil {
	log.Fatal(err)
}
if err := comp.AddSatisRequire(configPath, "acme/auth", "^1.5"); err != nil {
	log.Fatal(err)
}

进阶

UpdateSatisStability 的取值校验

传入非 dev/alpha/beta/RC/stable 的值会返回 invalid stability: <value> 错误，配置文件不会被修改。

AddSatisRequire 的副作用

调用一次 AddSatisRequire 就会把 RequireAll 设为 false，意味着 Satis 只构建 Require 中列出的包而非全部。如果你想要「全部 + 额外几个」，不要用这个方法，直接手工编辑 Require 并保持 RequireAll=true。

BuildSatis 的 outputDir 留空

BuildSatis 当 outputDir 为空字符串时执行 satis build <configPath>（用配置文件里的 output-dir）；非空则追加第二个参数覆盖输出目录。