bookworm/bookworm-smart-assistant

Fork 0

bookworm-admin 1c14c60d3f Initial: Bookworm Smart Assistant v6.5.1 (byte-preserved, 809 files, fp 26b83e1b38cdf64a)

2026-04-21 17:57:05 +08:00

13 KiB

Raw Permalink Blame History

黄金路径模板示例

基于Backstage Software Templates的黄金路径实现参考。

黄金路径设计原则

核心理念

降低认知负荷：封装复杂性，暴露简单接口
默认安全：安全配置内置，合规自动满足
自助服务：开发者无需等待审批即可启动
透明可学：生成代码可读可改，作为教学工具

模板分层架构

开发者输入 (元数据)
        │
        ▼
┌───────────────────┐
│   软件模板        │  ← Backstage Scaffolder
│   (YAML定义)      │
└─────────┬─────────┘
          │
          ▼
┌───────────────────┐
│   骨架代码        │  ← 标准化项目结构
│   (Skeleton)      │
└─────────┬─────────┘
          │
          ▼
┌───────────────────┐
│   IaC模块         │  ← Terraform/Helm封装
│   (基础设施)      │
└─────────┬─────────┘
          │
          ▼
┌───────────────────┐
│   GitOps配置      │  ← ArgoCD/Flux部署
│   (CD流水线)      │
└───────────────────┘

模板示例一：后端微服务

template.yaml

apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
  name: backend-service-go
  title: Go 后端微服务
  description: |
    创建一个生产就绪的Go微服务，包含:
    - Gin框架 + 标准项目结构
    - OpenTelemetry可观测性
    - Docker + Kubernetes部署
    - GitHub Actions CI/CD
    - SLSA L3合规    
  tags:
    - go
    - backend
    - microservice
    - recommended
spec:
  owner: platform-team
  type: service

  parameters:
    - title: 服务基本信息
      required:
        - name
        - owner
        - description
      properties:
        name:
          title: 服务名称
          type: string
          description: 唯一的服务标识符 (小写字母、数字、连字符)
          pattern: '^[a-z0-9-]+$'
          ui:autofocus: true
        owner:
          title: 负责团队
          type: string
          ui:field: OwnerPicker
          ui:options:
            catalogFilter:
              kind: Group
        description:
          title: 服务描述
          type: string
          description: 简短描述服务用途

    - title: 技术配置
      properties:
        database:
          title: 数据库
          type: string
          enum:
            - none
            - postgresql
            - mysql
          default: none
          description: 选择需要的数据库类型
        cache:
          title: 缓存
          type: boolean
          default: false
          description: 是否需要Redis缓存
        messageQueue:
          title: 消息队列
          type: string
          enum:
            - none
            - kafka
            - sqs
          default: none

    - title: 部署配置
      properties:
        environment:
          title: 初始环境
          type: array
          items:
            type: string
            enum:
              - development
              - staging
              - production
          default:
            - development
            - staging
        region:
          title: 部署区域
          type: string
          enum:
            - ap-northeast-1
            - us-east-1
            - eu-west-1
          default: ap-northeast-1

  steps:
    # Step 1: 生成代码骨架
    - id: fetch-skeleton
      name: 获取代码骨架
      action: fetch:template
      input:
        url: ./skeleton
        values:
          name: ${{ parameters.name }}
          owner: ${{ parameters.owner }}
          description: ${{ parameters.description }}
          database: ${{ parameters.database }}
          cache: ${{ parameters.cache }}
          messageQueue: ${{ parameters.messageQueue }}

    # Step 2: 生成基础设施代码
    - id: generate-infra
      name: 生成基础设施配置
      action: fetch:template
      input:
        url: ./infra-template
        targetPath: ./infra
        values:
          name: ${{ parameters.name }}
          environments: ${{ parameters.environment }}
          region: ${{ parameters.region }}
          database: ${{ parameters.database }}
          cache: ${{ parameters.cache }}

    # Step 3: 创建代码仓库
    - id: publish-github
      name: 创建GitHub仓库
      action: publish:github
      input:
        allowedHosts: ['github.com']
        repoUrl: github.com?owner=our-org&repo=${{ parameters.name }}
        description: ${{ parameters.description }}
        defaultBranch: main
        protectDefaultBranch: true
        requireCodeOwnerReviews: true
        requiredStatusChecks:
          - ci/build
          - ci/test
          - security/scan

    # Step 4: 注册到软件目录
    - id: register-catalog
      name: 注册到软件目录
      action: catalog:register
      input:
        repoContentsUrl: ${{ steps['publish-github'].output.repoContentsUrl }}
        catalogInfoPath: /catalog-info.yaml

    # Step 5: 创建ArgoCD应用
    - id: create-argocd-app
      name: 配置GitOps部署
      action: argocd:create-resources
      input:
        appName: ${{ parameters.name }}
        projectName: default
        repoUrl: ${{ steps['publish-github'].output.remoteUrl }}
        path: ./infra/k8s

  output:
    links:
      - title: 代码仓库
        url: ${{ steps['publish-github'].output.remoteUrl }}
      - title: 软件目录
        icon: catalog
        entityRef: ${{ steps['register-catalog'].output.entityRef }}
      - title: CI流水线
        url: ${{ steps['publish-github'].output.remoteUrl }}/actions

骨架代码结构

skeleton/
├── cmd/
│   └── server/
│       └── main.go
├── internal/
│   ├── handler/
│   │   └── health.go
│   ├── middleware/
│   │   ├── logging.go
│   │   └── tracing.go
│   ├── repository/
│   └── service/
├── pkg/
│   └── config/
│       └── config.go
├── api/
│   └── openapi.yaml
├── .github/
│   └── workflows/
│       ├── ci.yaml
│       └── release.yaml
├── Dockerfile
├── Makefile
├── go.mod
├── catalog-info.yaml
└── README.md

模板示例二：前端应用

template.yaml

apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
  name: frontend-nextjs
  title: Next.js 前端应用
  description: |
    创建一个现代化的Next.js前端应用，包含:
    - Next.js 14 App Router
    - TypeScript + Tailwind CSS
    - shadcn/ui组件库
    - 国际化(i18n)支持
    - Vercel/容器化部署    
  tags:
    - nextjs
    - frontend
    - typescript
    - recommended
spec:
  owner: platform-team
  type: website

  parameters:
    - title: 应用基本信息
      required:
        - name
        - owner
      properties:
        name:
          title: 应用名称
          type: string
          pattern: '^[a-z0-9-]+$'
        owner:
          title: 负责团队
          type: string
          ui:field: OwnerPicker

    - title: 功能配置
      properties:
        authentication:
          title: 认证方案
          type: string
          enum:
            - none
            - nextauth
            - auth0
            - custom
          default: none
        i18n:
          title: 国际化
          type: boolean
          default: false
        analytics:
          title: 分析集成
          type: string
          enum:
            - none
            - google-analytics
            - posthog
            - mixpanel
          default: none

    - title: 部署方式
      properties:
        deployTarget:
          title: 部署目标
          type: string
          enum:
            - vercel
            - kubernetes
            - cloudflare-pages
          default: vercel

  steps:
    - id: fetch-skeleton
      name: 获取代码骨架
      action: fetch:template
      input:
        url: ./skeleton-nextjs
        values:
          name: ${{ parameters.name }}
          authentication: ${{ parameters.authentication }}
          i18n: ${{ parameters.i18n }}
          analytics: ${{ parameters.analytics }}

    - id: install-shadcn
      name: 配置shadcn/ui
      action: run:command
      input:
        command: npx shadcn-ui@latest init -y

    - id: publish-github
      name: 创建GitHub仓库
      action: publish:github
      input:
        repoUrl: github.com?owner=our-org&repo=${{ parameters.name }}

    - id: register-catalog
      name: 注册到软件目录
      action: catalog:register
      input:
        repoContentsUrl: ${{ steps['publish-github'].output.repoContentsUrl }}
        catalogInfoPath: /catalog-info.yaml

模板示例三：数据管道

template.yaml

apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
  name: data-pipeline
  title: 数据处理管道
  description: |
    创建一个数据处理管道，包含:
    - Python + Pandas/PySpark
    - Airflow DAG定义
    - dbt数据转换
    - 数据质量检查(Great Expectations)    
  tags:
    - data
    - python
    - airflow
    - etl
spec:
  owner: data-platform-team
  type: pipeline

  parameters:
    - title: 管道基本信息
      required:
        - name
        - owner
        - schedule
      properties:
        name:
          title: 管道名称
          type: string
        owner:
          title: 负责团队
          type: string
          ui:field: OwnerPicker
        schedule:
          title: 调度频率
          type: string
          enum:
            - '@hourly'
            - '@daily'
            - '@weekly'
            - custom
          default: '@daily'

    - title: 数据源配置
      properties:
        sources:
          title: 数据源
          type: array
          items:
            type: object
            properties:
              type:
                type: string
                enum:
                  - postgresql
                  - mysql
                  - s3
                  - bigquery
                  - api
              connection:
                type: string

IaC模块封装示例

简化的Terraform模块接口

# 开发者只需提供这些参数
module "backend_service" {
  source = "git::https://github.com/our-org/terraform-modules//backend-service"

  # 必填参数
  name        = "order-service"
  environment = "production"
  owner       = "commerce-team"

  # 可选参数 (有合理默认值)
  replicas    = 3
  cpu         = "500m"
  memory      = "1Gi"
  
  # 数据库配置
  database = {
    type     = "postgresql"
    size     = "large"  # small/medium/large，平台团队定义具体规格
  }

  # 缓存配置
  cache = {
    enabled = true
    size    = "medium"
  }
}

模块内部封装的复杂性

# 开发者不需要关心的内部实现
# terraform-modules/backend-service/main.tf

locals {
  # 平台团队定义的规格映射
  db_sizes = {
    small  = { instance_class = "db.t3.micro", storage = 20 }
    medium = { instance_class = "db.t3.small", storage = 50 }
    large  = { instance_class = "db.r5.large", storage = 100 }
  }
}

resource "aws_security_group" "db" {
  # 安全组配置 - 默认最小权限
  ingress {
    from_port   = 5432
    to_port     = 5432
    cidr_blocks = [data.aws_vpc.main.cidr_block]
  }
  # ... 更多安全配置
}

resource "aws_db_instance" "main" {
  # 数据库实例配置
  instance_class        = local.db_sizes[var.database.size].instance_class
  allocated_storage     = local.db_sizes[var.database.size].storage
  
  # 默认启用的安全配置
  storage_encrypted     = true
  deletion_protection   = var.environment == "production"
  backup_retention_period = 7
  
  # 默认启用的监控
  performance_insights_enabled = true
  monitoring_interval          = 60
  
  # ... 更多配置
}

resource "aws_kms_key" "db_encryption" {
  # 自动创建的加密密钥
  description             = "KMS key for ${var.name} database encryption"
  deletion_window_in_days = 30
  enable_key_rotation     = true
}

模板质量检查清单

创建新模板前，确认满足以下要求：

可用性

参数名称清晰易懂
提供合理的默认值
必填项最小化
有完整的描述信息

安全性

默认启用加密
默认最小权限
集成安全扫描
无硬编码密钥

可观测性

集成日志收集
集成指标采集
集成分布式追踪
健康检查端点

可维护性

生成代码可读
包含README文档
遵循团队规范
版本化模板

合规性

满足SLSA要求
自动生成SBOM
符合组织策略
资源标签完整

13 KiB Raw Permalink Blame History Unescape Escape

黄金路径模板示例

黄金路径设计原则

核心理念

模板分层架构

模板示例一：后端微服务

template.yaml

骨架代码结构

模板示例二：前端应用

template.yaml

模板示例三：数据管道

template.yaml

IaC模块封装示例

简化的Terraform模块接口

模块内部封装的复杂性

模板质量检查清单

可用性

安全性

可观测性

可维护性

合规性

13 KiB

Raw Permalink Blame History