Instruction file imported from mensylisir/environments (.cursor/rules/api_structure.mdc). Copyright stays with the author.

API 结构设计

EnviromentTemplate

// EnviromentTemplate 定义了环境模板
type EnviromentTemplate struct {
    metav1.TypeMeta   `json:",inline"`
    metav1.ObjectMeta `json:"metadata,omitempty"`

    Spec   EnviromentTemplateSpec   `json:"spec,omitempty"`
    Status EnviromentTemplateStatus `json:"status,omitempty"`
}

// EnviromentTemplateSpec 定义了环境模板的规格
type EnviromentTemplateSpec struct {
    // Components 定义了环境中包含的组件列表
    Components []Component `json:"components"`
    
    // OAMComponents 定义了基于OAM模型的组件列表
    OAMComponents []OAMComponent `json:"oamComponents,omitempty"`
}

// Component 定义了一个组件
type Component struct {
    // Name 是组件的名称
    Name string `json:"name"`
    
    // Type 是组件的类型: Helm, Git, Local
    Type string `json:"type"`
    
    // HelmRepo 定义了 Helm 仓库信息，当 Type=Helm 时使用
    HelmRepo *HelmRepo `json:"helmRepo,omitempty"`
    
    // GitRepo 定义了 Git 仓库信息，当 Type=Git 时使用
    GitRepo *GitRepo `json:"gitRepo,omitempty"`
    
    // LocalYAML 定义了本地 YAML 信息，当 Type=Local 时使用
    LocalYAML *LocalYAML `json:"localYAML,omitempty"`
    
    // Dependencies 定义了组件的依赖关系，用于生成拓扑图
    Dependencies []string `json:"dependencies,omitempty"`
}

// OAMComponent 定义了一个基于OAM模型的组件
type OAMComponent struct {
    // Name 是组件的名称
    Name string `json:"name"`
    
    // Type 是组件的类型
    Type string `json:"type"`
    
    // Properties 是组件的属性
    Properties map[string]interface{} `json:"properties,omitempty"`
    
    // Traits 是组件的特性
    Traits []OAMTrait `json:"traits,omitempty"`
    
    // Dependencies 定义了组件的依赖关系，用于生成拓扑图
    Dependencies []string `json:"dependencies,omitempty"`
}

// OAMTrait 定义了OAM组件的特性
type OAMTrait struct {
    // Name 是特性的名称
    Name string `json:"name"`
    
    // Properties 是特性的属性
    Properties map[string]interface{} `json:"properties,omitempty"`
}

// HelmRepo 定义了 Helm 仓库信息
type HelmRepo struct {
    // URL 是 Helm 仓库的 URL
    URL string `json:"url"`
    
    // ChartName 是 chart 的名称
    ChartName string `json:"chartName"`
    
    // Version 是 chart 的版本
    Version string `json:"version"`
    
    // Values 是 Helm values 的覆盖
    Values map[string]interface{} `json:"values,omitempty"`
}

// GitRepo 定义了 Git 仓库信息
type GitRepo struct {
    // URL 是 Git 仓库的 URL
    URL string `json:"url"`
    
    // Path 是仓库中 YAML 文件的路径
    Path string `json:"path"`
    
    // Ref 是 Git 的引用 (分支、标签或提交)
    Ref string `json:"ref"`
    
    // Overrides 是 YAML 文件的覆盖
    Overrides map[string]interface{} `json:"overrides,omitempty"`
}

// LocalYAML 定义了本地 YAML 信息
type LocalYAML struct {
    // Path 是本地 YAML 文件的路径
    Path string `json:"path"`
    
    // Overrides 是 YAML 文件的覆盖
    Overrides map[string]interface{} `json:"overrides,omitempty"`
}

// EnviromentTemplateStatus 定义了环境模板的状态
type EnviromentTemplateStatus struct {
    // 组件验证状态
    ComponentsValid bool `json:"componentsValid"`
    
    // 最后一次更新时间
    LastUpdateTime metav1.Time `json:"lastUpdateTime,omitempty"`
    
    // 任何错误信息
    Errors []string `json:"errors,omitempty"`
}

Enviroment

// Enviroment 定义了一个环境
type Enviroment struct {
    metav1.TypeMeta   `json:",inline"`
    metav1.ObjectMeta `json:"metadata,omitempty"`

    Spec   EnviromentSpec   `json:"spec,omitempty"`
    Status EnviromentStatus `json:"status,omitempty"`
}

// EnviromentSpec 定义了环境的规格
type EnviromentSpec struct {
    // TemplateName 引用的 EnviromentTemplate 名称
    TemplateName string `json:"templateName"`
    
    // Namespaces 是此环境包含的命名空间列表
    Namespaces []NamespaceConfig `json:"namespaces"`
    
    // ResourceQuota 定义了整个环境的资源配额
    ResourceQuota *ResourceQuotaSpec `json:"resourceQuota,omitempty"`
    
    // RBAC 定义了环境级别的角色和角色绑定
    RBAC *RBACConfig `json:"rbac,omitempty"`
    
    // NetworkPolicy 定义了环境的网络策略
    NetworkPolicy *NetworkPolicyConfig `json:"networkPolicy,omitempty"`
    
    // ComponentOverrides 允许覆盖特定组件的配置
    ComponentOverrides map[string]ComponentOverride `json:"componentOverrides,omitempty"`
    
    // OAMComponentOverrides 允许覆盖特定OAM组件的配置
    OAMComponentOverrides map[string]OAMComponentOverride `json:"oamComponentOverrides,omitempty"`
}

// NamespaceConfig 定义了命名空间配置
type NamespaceConfig struct {
    // Name 是命名空间的名称
    Name string `json:"name"`
    
    // ResourceQuota 定义了此命名空间的资源配额
    ResourceQuota *ResourceQuotaSpec `json:"resourceQuota,omitempty"`
    
    // LimitRange 定义了此命名空间的限制范围
    LimitRange *LimitRangeSpec `json:"limitRange,omitempty"`
}

// ResourceQuotaSpec 定义了资源配额
type ResourceQuotaSpec struct {
    // Limits 定义了资源限制
    Limits ResourceList `json:"limits,omitempty"`
}

// ResourceList 是资源列表
type ResourceList map[string]resource.Quantity

// RBACConfig 定义了 RBAC 配置
type RBACConfig struct {
    // Roles 定义了角色列表
    Roles []Role `json:"roles"`
    
    // Bindings 定义了角色绑定列表
    Bindings []RoleBinding `json:"bindings"`
}

// Role 定义了角色
type Role struct {
    // Name 是角色的名称
    Name string `json:"name"`
    
    // Rules 定义了规则列表
    Rules []rbacv1.PolicyRule `json:"rules"`
}

// RoleBinding 定义了角色绑定
type RoleBinding struct {
    // RoleName 是角色的名称
    RoleName string `json:"roleName"`
    
    // Subjects 定义了主体列表
    Subjects []rbacv1.Subject `json:"subjects"`
}

// NetworkPolicyConfig 定义了网络策略配置
type NetworkPolicyConfig struct {
    // Ingress 定义了入站规则
    Ingress []NetworkPolicyRule `json:"ingress,omitempty"`
    
    // Egress 定义了出站规则
    Egress []NetworkPolicyRule `json:"egress,omitempty"`
}

// NetworkPolicyRule 定义了网络策略规则
type NetworkPolicyRule struct {
    // From/To 定义了来源/目标
    From []NetworkPolicyPeer `json:"from,omitempty"`
    To []NetworkPolicyPeer `json:"to,omitempty"`
    
    // Ports 定义了端口列表
    Ports []NetworkPolicyPort `json:"ports,omitempty"`
}

// ComponentOverride 允许覆盖组件配置
type ComponentOverride struct {
    // Values 覆盖 Helm values
    Values map[string]interface{} `json:"values,omitempty"`
    
    // Overrides 覆盖 YAML 设置
    Overrides map[string]interface{} `json:"overrides,omitempty"`
}

// OAMComponentOverride 允许覆盖OAM组件配置
type OAMComponentOverride struct {
    // Properties 覆盖组件属性
    Properties map[string]interface{} `json:"properties,omitempty"`
    
    // Traits 覆盖组件特性
    Traits map[string]map[string]interface{} `json:"traits,omitempty"`
}

// EnviromentStatus 定义了环境的状态
type EnviromentStatus struct {
    // 环境的状态: Pending, Deploying, Ready, Error
    Phase string `json:"phase"`
    
    // 各组件的状态
    Components []ComponentStatus `json:"components,omitempty"`
    
    // 资源使用情况
    ResourceUsage ResourceList `json:"resourceUsage,omitempty"`
    
    // 命名空间状态
    Namespaces []NamespaceStatus `json:"namespaces,omitempty"`
    
    // 应用拓扑图
    Topology TopologyStatus `json:"topology,omitempty"`
    
    // 任何错误信息
    Errors []string `json:"errors,omitempty"`
}

// ComponentStatus 显示组件的状态
type ComponentStatus struct {
    // Name 是组件的名称
    Name string `json:"name"`
    
    // Phase 是组件的阶段: Pending, Deploying, Ready, Error
    Phase string `json:"phase"`
    
    // Message 是与状态相关的消息
    Message string `json:"message,omitempty"`
}

// NamespaceStatus 显示命名空间的状态
type NamespaceStatus struct {
    // Name 是命名空间的名称
    Name string `json:"name"`
    
    // Phase 是命名空间的阶段: Pending, Active, Terminating
    Phase string `json:"phase"`
    
    // ResourceUsage 是资源使用情况
    ResourceUsage ResourceList `json:"resourceUsage,omitempty"`
}

// TopologyStatus 显示应用拓扑状态
type TopologyStatus struct {
    // Nodes 定义了拓扑中的节点
    Nodes []TopologyNode `json:"nodes"`
    
    // Edges 定义了拓扑中的边
    Edges []TopologyEdge `json:"edges"`
    
    // LastUpdated 是拓扑最后更新时间
    LastUpdated metav1.Time `json:"lastUpdated"`
}

// TopologyNode 定义了拓扑中的节点
type TopologyNode struct {
    // ID 是节点的唯一标识
    ID string `json:"id"`
    
    // Name 是节点的名称
    Name string `json:"name"`
    
    // Type 是节点的类型
    Type string `json:"type"`
    
    // Namespace 是节点所在的命名空间
    Namespace string `json:"namespace"`
    
    // Status 是节点的状态
    Status string `json:"status"`
    
    // Properties 是节点的附加属性
    Properties map[string]interface{} `json:"properties,omitempty"`
}

// TopologyEdge 定义了拓扑中的边
type TopologyEdge struct {
    // Source 是边的源节点ID
    Source string `json:"source"`
    
    // Target 是边的目标节点ID
    Target string `json:"target"`
    
    // Type 是边的类型
    Type string `json:"type"`
    
    // Properties 是边的附加属性
    Properties map[string]interface{} `json:"properties,omitempty"`
}