✅ 验证

验证 composer.json 与 composer.lock 的格式、架构与一致性，并检查安全漏洞、平台禁止项等约束。

Composer 的 validate 命令是依赖治理的入口。Composer Skills 把它拆成一组语义化方法：从最基础的 Validate，到严格模式、跳过特定检查、只验架构、检查 lock 同步，再到结构化的 ValidateStructured。每个方法对应一种「检查粒度」，避免在脚本里手拼命令行参数。

何时使用

• ✅ 提交前本地校验：composer.json 是否符合 schema、字段是否齐全。
• 📦 发布前检查：是否满足 Packagist 发布要求（--no-check-publish 反向场景）。
• 🔄 CI 同步性检查：composer.lock 是否与 composer.json 同步、是否被规范化格式化。
• 🛡️ 安全联动：CheckForSecurityVulnerabilities 在一条调用里返回「输出 + 是否有漏洞」。
• 🧩 平台约束排查：Prohibit 查看哪些包被当前平台需求禁止安装。

结构化返回类型

ValidateResult

ValidateStructured / ParseValidateOutput 返回。

type ValidateResult struct {
    Valid    bool     `json:"valid"`
    Errors   []string `json:"errors,omitempty"`
    Warnings []string `json:"warnings,omitempty"`
}

字段	类型	说明
Valid	bool	整体是否通过验证
Errors	[]string	错误信息列表（出现则 Valid=false）
Warnings	[]string	警告信息列表（不影响 Valid）

解析逻辑

ParseValidateOutput 逐行扫描输出：含 error/Error 的行归入 Errors 并置 Valid=false；含 warning/Warning 的行归入 Warnings。ValidateStructured 还会在命令返回非零退出码时强制 Valid=false。

---

Validate

✅ 验证 composer.json 是否有效（无返回值的便捷形式）。

签名

func (c *Composer) Validate() error

参数

无。

返回值

值	类型	说明
错误	error	验证失败时返回错误；nil 表示通过

定义位置

该方法定义在 config.go，签名与 validate.go 中其它返回 (string, error) 的方法不同——它只关心「是否通过」，不返回输出文本。需要拿到输出请用 ValidateStructured 或下方各 ValidateXxx 方法。

示例

if err := comp.Validate(); err != nil {
    log.Fatalf("composer.json 验证失败: %v", err)
}
fmt.Println("composer.json 验证通过")

---

ValidateStrict

✅ 严格模式验证 composer.json。

签名

func (c *Composer) ValidateStrict() (string, error)

参数

无。

返回值

值	类型	说明
输出	string	composer validate --strict 的输出
错误	error	验证失败时返回

等价命令

composer validate --strict

示例

output, err := comp.ValidateStrict()
if err != nil {
    log.Fatalf("严格验证失败: %v", err)
}
fmt.Println("验证结果:", output)

---

ValidateWithNoCheck

✅ 验证 composer.json 但不检查全部平台需求与其他约束。

签名

func (c *Composer) ValidateWithNoCheck() (string, error)

参数

无。

返回值

值	类型	说明
输出	string	验证输出
错误	error	验证失败时返回

等价命令

composer validate --no-check-all

示例

output, err := comp.ValidateWithNoCheck()
if err != nil {
    log.Fatalf("验证失败: %v", err)
}
fmt.Println("仅格式验证结果:", output)

---

ValidateWithCheckVersion

✅ 验证 composer.json 并检查依赖项版本约束（含间接依赖）。

签名

func (c *Composer) ValidateWithCheckVersion() (string, error)

参数

无。

返回值

值	类型	说明
输出	string	验证输出
错误	error	验证失败时返回

等价命令

composer validate --with-dependencies

示例

output, err := comp.ValidateWithCheckVersion()
if err != nil {
    log.Fatalf("版本约束验证失败: %v", err)
}
fmt.Println("版本约束验证结果:", output)

---

ValidateSchema

✅ 仅验证 composer.json 与 composer.lock 是否符合 JSON 架构，不检查其它约束。

签名

func (c *Composer) ValidateSchema() (string, error)

参数

无。

返回值

值	类型	说明
输出	string	验证输出
错误	error	验证失败时返回

等价命令

composer validate --no-check-all --no-check-publish --no-check-version

示例

output, err := comp.ValidateSchema()
if err != nil {
    log.Fatalf("架构验证失败: %v", err)
}
fmt.Println("架构验证结果:", output)

---

NormalizeComposerJson

✅ 格式化 composer.json，使其符合规范格式。

签名

func (c *Composer) NormalizeComposerJson() (string, error)

参数

无。

返回值

值	类型	说明
输出	string	格式化命令的输出
错误	error	格式化失败时返回

等价命令

composer normalize（需要安装 ergebnis/composer-normalize 插件）

示例

output, err := comp.NormalizeComposerJson()
if err != nil {
    if strings.Contains(err.Error(), "command not found") {
        fmt.Println("请先安装 normalize 插件: composer global require ergebnis/composer-normalize")
    } else {
        log.Fatalf("格式化失败: %v", err)
    }
}
fmt.Println("格式化结果:", output)

依赖外部插件

normalize 不是 Composer 内置命令，未安装插件时会报「command not found」。可配合 CheckNormalization 先检测是否需要格式化。

---

ValidateComposerLock

✅ 验证 composer.lock 是否存在并与 composer.json 同步。

签名

func (c *Composer) ValidateComposerLock() (string, error)

参数

无。

返回值

值	类型	说明
输出	string	验证输出
错误	error	验证失败时返回

等价命令

composer validate --check-lock

示例

output, err := comp.ValidateComposerLock()
if err != nil {
    if strings.Contains(output, "not found") {
        fmt.Println("缺少 composer.lock 文件")
    } else if strings.Contains(output, "not up to date") {
        fmt.Println("composer.lock 需要更新，请运行 composer update")
    } else {
        log.Fatalf("验证 composer.lock 失败: %v", err)
    }
} else {
    fmt.Println("composer.lock 有效:", output)
}

---

Prohibit

✅ 显示被当前平台需求（platform requirements）禁止的包。

签名

func (c *Composer) Prohibit() (string, error)

参数

无。

返回值

值	类型	说明
输出	string	被禁止的包列表
错误	error	查询失败时返回

等价命令

composer prohibit

示例

output, err := comp.Prohibit()
if err != nil {
    log.Fatalf("查询被禁止包失败: %v", err)
}
fmt.Println("被禁止的包:", output)

进阶变体

• ProhibitWithFormat(format string) (string, error)：等价 composer prohibit --format=format，format 可为 text 或 json。
• ProhibitWithOptions(options map[string]string) (string, error)：自定义选项组合，例如同时指定 format=json 与 fixed。

// JSON 格式 + 完整路径
options := map[string]string{
    "format": "json",
    "fixed":  "",
}
output, err := comp.ProhibitWithOptions(options)

---

CheckForSecurityVulnerabilities

✅ 检查项目依赖是否存在已知安全漏洞，返回「输出 + 是否有漏洞」三元组。

签名

func (c *Composer) CheckForSecurityVulnerabilities() (string, bool, error)

参数

无。

返回值

值	类型	说明
输出	string	composer audit 的原始输出
是否有漏洞	bool	true 表示检测到漏洞
错误	error	检查过程发生非预期错误时返回

实现说明

执行 composer audit。Composer 在发现漏洞时会返回非零退出码，本方法会分析输出：若包含 Found + vulnerability/vulnerabilities 或 Security vulnerability 等关键字，则认定「有漏洞」并把 (output, true, nil) 返回，不把退出码当作错误上抛。其它真正的执行错误才作为 error 返回。

示例

output, hasVulnerabilities, err := comp.CheckForSecurityVulnerabilities()
if err != nil {
    log.Fatalf("安全检查失败: %v", err)
}
if hasVulnerabilities {
    fmt.Println("警告：发现安全漏洞!")
    fmt.Println(output)
} else {
    fmt.Println("没有发现安全漏洞")
}

与 HasVulnerabilities 的区别

安全审计 - HasVulnerabilities 返回 (bool, error)，内部走 JSON 解析路径更精确；本方法返回原始文本输出 + 布尔判断，适合需要同时拿到输出文本做日志归档的场景。

---

进阶

ValidateStructured

结构化验证，返回 *ValidateResult，便于程序化判断错误与警告。

func (c *Composer) ValidateStructured() (*ValidateResult, error)

值	类型	说明
结果	*ValidateResult	含 Valid/Errors/Warnings
错误	error	执行错误（注意：验证未通过不一定有 error，需看 Valid 字段）

result, err := comp.ValidateStructured()
if err != nil {
    log.Fatalf("验证失败: %v", err)
}
if !result.Valid {
    for _, e := range result.Errors {
        fmt.Println("错误:", e)
    }
}
for _, w := range result.Warnings {
    fmt.Println("警告:", w)
}

ValidateWithOptions

组合多个验证标志，等价 composer validate <flags>。

func (c *Composer) ValidateWithOptions(options map[string]string) (string, error)

// 严格验证并检查依赖关系
options := map[string]string{
    "strict":            "",
    "with-dependencies": "",
}
output, err := comp.ValidateWithOptions(options)

ParseValidateOutput

纯函数，把任意 composer validate 文本输出解析为 *ValidateResult，便于对缓存或日志中的旧输出做后处理。

func ParseValidateOutput(output string) *ValidateResult

其它验证相关方法

方法	等价命令	说明
ValidateWithNoCheckPublish()	validate --no-check-publish	不检查发布到 Packagist 所需字段
ValidateQuiet()	validate --quiet	静默验证，仅出错时输出
CheckNormalization()	validate --no-check-all --check-normalized	检查 composer.json 是否已规范化格式化
CheckPlatformReqsLock()	check-platform-reqs --lock	检查 composer.lock 中的平台需求
CheckForOutdatedPackages(direct, minor, format)	outdated [--direct] [--minor-only] [--format F]	检查过时包，详见下表

CheckForOutdatedPackages 参数

参数	类型	说明
direct	bool	true 只检查直接依赖
minor	bool	true 只显示次要更新
format	string	输出格式，如 text、json；空字符串表示不指定

// 只检查直接依赖的次要更新，并以 JSON 输出
output, err := comp.CheckForOutdatedPackages(true, true, "json")

🔍 相关方法

• 安全审计：以 audit 为核心的结构化漏洞分析。
• 平台：CheckPlatformReqsStructured 返回平台需求的结构化检查结果。
• 诊断与健康检查：HealthCheck 内部会调用 ValidateStructured 并把结果写入 Valid 字段。