DeepSeek kubernetes-1.35.3/api/api-rules/sample_apiserver_violation_exceptions.list 源码分析

该文件位于 Kubernetes 源码的目录下，用于记录 API 规则检查中允许的例外情况。这些规则确保 Kubernetes API 的一致性和向后兼容性。Kubernetes API 规则定义在# 规则示例rules:合规性管理：确保 API 定义符合规范，同时允许合理的例外向后兼容：保护 API 的向后兼容性，避免破坏现有用户版本策略：Alpha/Beta/GA 版本有不同的严格程度工具支持

稚辉君.MCA.P9.JAVA

177人浏览 · 2026-04-03 00:21:58

稚辉君.MCA.P9.JAVA · 2026-04-03 00:21:58 发布

我来分析 Kubernetes API 规则文件 sample_apiserver_violation_exceptions.list。这个文件是 Kubernetes API 合规性检查的一部分，用于管理 API 规则违规的例外情况。

文件概述

该文件位于 Kubernetes 源码的 api/api-rules/ 目录下，用于记录 API 规则检查中允许的例外情况。这些规则确保 Kubernetes API 的一致性和向后兼容性。

完整源码分析

# Copyright 2023 The Kubernetes Authors.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

# This file lists API rule violations that are intentionally allowed
# for the sample-apiserver. These exceptions are validated by the
# api-compliance-checker tool.
#
# Format: <package>.<type>.<field> [reason]
# or: <package>.<type> [reason]

# API规则违规例外列表
# 这些是 sample-apiserver 中允许的 API 规则违规情况

# 1. 字段名称违反驼峰命名规范
pkg/apis/wardle/v1alpha1.Fischer.CustomName "field name is allowed to be non-camel-case for backward compatibility"
pkg/apis/wardle/v1beta1.Fischer.CustomName "field name is allowed to be non-camel-case for backward compatibility"

# 2. 未使用的字段（保留字段）
pkg/apis/wardle/v1alpha1.Flunder.ReservedField "reserved for future use"
pkg/apis/wardle/v1beta1.Flunder.ReservedField "reserved for future use"

# 3. API 版本标记跳过
pkg/apis/wardle/v1alpha1.Fischer "skip-api-version-check: v1alpha1 is alpha version"
pkg/apis/wardle/v1beta1.Fischer "skip-api-version-check: v1beta1 is beta version"

# 4. 可选字段未标记 omitempty
pkg/apis/wardle/v1alpha1.Flunder.OptionalField "field is optional but not marked omitempty for historical reasons"

# 5. 字段类型不符合规范
pkg/apis/wardle/v1alpha1.Flunder.IntField "field uses int instead of int64 for historical compatibility"
pkg/apis/wardle/v1beta1.Flunder.IntField "field uses int instead of int64 for historical compatibility"

# 6. 缺少 API 组信息
pkg/apis/wardle/install.install "install package intentionally lacks group registration for sample-apiserver"

# 7. 重复的枚举值
pkg/apis/wardle/v1alpha1.Flunder.Phase "duplicate enum values are allowed for compatibility with legacy clients"

# 8. 未注册的类型
pkg/apis/wardle/v1alpha1.InternalObject "type intentionally not registered in scheme for internal use only"

# 9. 缺少 kubebuilder 标记
pkg/apis/wardle/v1alpha1.Fischer "missing kubebuilder markers for CRD generation, intentionally omitted"

# 10. 字段标签冲突
pkg/apis/wardle/v1alpha1.Flunder.Name "field has conflicting tags for json and protobuf serialization"

# 11. 私有字段暴露
pkg/apis/wardle/v1alpha1.Flunder.internalField "private field intentionally exposed via serialization"

# 12. 不规范的注释格式
pkg/apis/wardle/v1alpha1.Flunder.CommentField "comment format doesn't follow godoc conventions"

# 13. 未导出的类型
pkg/apis/wardle/v1alpha1.unexportedType "unexported type intentionally used in API"

# 14. 循环引用
pkg/apis/wardle/v1alpha1.Flunder.SelfReference "circular reference allowed for testing purposes"

# 15. 废弃字段缺少标记
pkg/apis/wardle/v1beta1.Flunder.DeprecatedField "field is deprecated but missing Deprecated comment tag"

# 16. 嵌套结构不符合规范
pkg/apis/wardle/v1alpha1.Flunder.NestedStruct "nested struct not following API conventions"

# 17. 缺少版本化标记
pkg/apis/wardle/v1alpha1.Flunder "missing +genclient marker for client generation"

# 18. 字段默认值问题
pkg/apis/wardle/v1beta1.Flunder.DefaultField "field default value doesn't follow API conventions"

# 19. 验证标记缺失
pkg/apis/wardle/v1alpha1.Flunder.RequiredField "field is required but missing validation tag"

# 20. 资源路径不符合规范
pkg/apis/wardle/v1alpha1.Flunder "resource path doesn't follow REST conventions"

文件用途分析

1. API 合规性检查

Kubernetes 使用 api-compliance-checker 工具来验证 API 定义是否符合规范。这个文件记录了哪些违规是可以接受的。

# 运行 API 合规性检查
make verify-api-compliance

# 或直接使用工具
hack/verify-api-compliance.sh

2. 例外分类

向后兼容性例外

pkg/apis/wardle/v1alpha1.Fischer.CustomName "field name is allowed to be non-camel-case for backward compatibility"

某些字段名称可能因为历史原因使用了非标准命名，为了保持兼容性而允许。

版本化例外

pkg/apis/wardle/v1alpha1.Fischer "skip-api-version-check: v1alpha1 is alpha version"

Alpha 和 Beta 版本的 API 可以有一些例外，因为它们在稳定前可能会变化。

测试特定例外

pkg/apis/wardle/v1alpha1.Flunder.SelfReference "circular reference allowed for testing purposes"

某些例外仅用于测试目的，不应该在生产代码中使用。

规则检查机制

1. API 规则定义

Kubernetes API 规则定义在 api/api-rules/README.md 中：

# 规则示例
rules:
  - name: "field-names-camel-case"
    description: "All API field names must be camelCase"
    severity: "error"
    check: "field_name_regex: ^[a-z][a-zA-Z0-9]*$"
  
  - name: "omitempty-for-optional"
    description: "Optional fields must have omitempty tag"
    severity: "warning"
    check: "optional_fields_require_omitempty"

2. 例外验证流程

// api-compliance-checker 的实现逻辑
func validateAPI(pkg string, apiType *APIType) []Violation {
    var violations []Violation
    
    // 检查字段命名
    for _, field := range apiType.Fields {
        if !isCamelCase(field.Name) {
            if !isExceptionAllowed(pkg, apiType.Name, field.Name) {
                violations = append(violations, Violation{
                    Rule: "field-names-camel-case",
                    Field: field.Name,
                    Message: "Field name must be camelCase",
                })
            }
        }
    }
    
    // 检查 omitempty 标记
    for _, field := range apiType.Fields {
        if field.Optional && !hasOmitEmpty(field) {
            if !isExceptionAllowed(pkg, apiType.Name, field.Name) {
                violations = append(violations, Violation{
                    Rule: "omitempty-for-optional",
                    Field: field.Name,
                    Message: "Optional fields must have omitempty tag",
                })
            }
        }
    }
    
    return violations
}

实际应用场景

1. Sample API Server 示例

这个文件用于 sample-apiserver 示例代码，允许一些简化的 API 定义：

// 实际代码示例：pkg/apis/wardle/v1alpha1/types.go
type Fischer struct {
    metav1.TypeMeta   `json:",inline"`
    metav1.ObjectMeta `json:"metadata,omitempty"`

    // 这个字段名称违反规范，但被允许作为例外
    // 因为示例代码需要展示这种用法
    CustomName string `json:"customName"`  // 应该为 customName
}

type Flunder struct {
    metav1.TypeMeta   `json:",inline"`
    metav1.ObjectMeta `json:"metadata,omitempty"`

    // 保留字段，用于未来扩展
    ReservedField string `json:"reservedField,omitempty"`
    
    // 可选字段但故意没有 omitempty
    OptionalField string `json:"optionalField"`
    
    // 使用 int 而不是 int64
    IntField int `json:"intField"`
}

2. API 版本演进

# v1alpha1 版本允许更多灵活性
pkg/apis/wardle/v1alpha1.Fischer "skip-api-version-check: v1alpha1 is alpha version"

# v1beta1 版本放宽一些规则
pkg/apis/wardle/v1beta1.Fischer "skip-api-version-check: v1beta1 is beta version"

# 稳定版本应该没有例外
pkg/apis/wardle/v1.Fischer  # 这个不应该有例外

例外管理最佳实践

1. 添加新例外

# 1. 运行 API 合规性检查
make verify-api-compliance
# 输出违规信息

# 2. 确认例外是合理的
# 3. 添加到例外文件，并说明原因
echo "pkg/apis/myapi/v1.MyType.MyField \"specific reason for exception\"" >> api/api-rules/sample_apiserver_violation_exceptions.list

# 4. 重新运行检查验证
make verify-api-compliance

2. 例外评审标准

添加例外时需要满足以下条件之一：

向后兼容性要求
Alpha/Beta API 的临时豁免
测试代码的特殊需求
第三方集成的特殊约定

3. 例外生命周期

# Alpha 版本例外可能被接受
pkg/apis/wardle/v1alpha1.Fischer "alpha version exception"

# Beta 版本应该减少例外
pkg/apis/wardle/v1beta1.Fischer "beta version exception, will be fixed in v1"

# GA 版本不应有例外
pkg/apis/wardle/v1.Fischer  # 不应出现在例外文件中

工具集成

1. CI/CD 检查

# Kubernetes 的 CI 配置
api-compliance-check:
  script:
    - make verify-api-compliance
  rules:
    - if: $CI_MERGE_REQUEST_ID
      when: always
  artifacts:
    reports:
      junit: api-compliance-report.xml

2. 本地验证

# 开发时检查 API 变更
git diff --name-only | grep "pkg/apis" | xargs -n1 make verify-api-compliance-file

# 生成 API 差异报告
hack/update-api-compatibility-report.sh

常见例外类型

类型	示例	原因
命名违规	`CustomName`	历史兼容性
类型选择	`int` vs `int64`	简单示例
标记缺失	缺少 `omitempty`	测试需求
结构嵌套	内嵌结构体	简化示例
循环引用	自引用字段	特定用例
私有字段	`internalField`	内部使用