Back to Details

ado-pipeline-best-practices

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

🚨 CRITICAL GUIDELINES

🚨 关键准则

Windows File Path Requirements

Windows 文件路径要求

MANDATORY: Always Use Backslashes on Windows for File Paths
When using Edit or Write tools on Windows, you MUST use backslashes (
\
) in file paths, NOT forward slashes (
/
).
Examples:
  • ❌ WRONG: 
    D:/repos/project/file.tsx
  • ✅ CORRECT: 
    D:\repos\project\file.tsx
This applies to:
  • Edit tool file_path parameter
  • Write tool file_path parameter
  • All file operations on Windows systems
强制要求：在Windows系统中使用文件路径时必须使用反斜杠（
\
）
在Windows系统上使用编辑或写入工具时，文件路径必须使用反斜杠（
\
），而不能使用正斜杠（
/
）。
示例：
  • ❌ 错误：
    D:/repos/project/file.tsx
  • ✅ 正确：
    D:\repos\project\file.tsx
此要求适用于：
  • 编辑工具的file_path参数
  • 写入工具的file_path参数
  • Windows系统上的所有文件操作

Documentation Guidelines

文档准则

NEVER create new documentation files unless explicitly requested by the user.
  • Priority: Update existing README.md files rather than creating new documentation
  • Repository cleanliness: Keep repository root clean - only README.md unless user requests otherwise
  • Style: Documentation should be concise, direct, and professional - avoid AI-generated tone
  • User preference: Only create additional .md files when user specifically asks for documentation
除非用户明确要求，否则绝不要创建新的文档文件。
  • 优先级：优先更新现有README.md文件，而非创建新文档
  • 仓库整洁性：保持仓库根目录整洁——除非用户要求，否则只保留README.md
  • 风格：文档应简洁、直接、专业——避免AI生成式的语气
  • 用户偏好：仅当用户明确要求文档时，才创建额外的.md文件

Azure Pipelines Best Practices

Azure Pipelines 最佳实践

Comprehensive best practices for creating and maintaining Azure DevOps YAML pipelines.
创建和维护Azure DevOps YAML管道的综合最佳实践指南。

Pipeline Structure

管道结构

Multi-Stage Pipelines:
yaml
undefined
多阶段管道：
yaml
undefined

Recommended structure

Recommended structure

stages:
  • stage: Build
  • stage: Test
  • stage: DeployDev
  • stage: DeployStaging
  • stage: DeployProduction

**Benefits:**
- Clear separation of concerns
- Conditional stage execution
- Environment-specific configurations
- Approval gates between stages
stages:
  • stage: Build
  • stage: Test
  • stage: DeployDev
  • stage: DeployStaging
  • stage: DeployProduction

**优势：**
- 清晰的职责分离
- 支持阶段的条件执行
- 环境特定的配置
- 阶段间的审批闸口

Triggers and Scheduling

触发器与调度

Best practices:
  • Use path filters to avoid unnecessary builds
  • Enable batch builds for high-frequency repos
  • Use PR triggers for validation
  • Schedule nightly/weekly builds for comprehensive testing
yaml
trigger:
  batch: true
  branches:
    include: [main, develop]
  paths:
    exclude: ['docs/*', '**.md']

pr:
  autoCancel: true
  branches:
    include: [main]

schedules:
  - cron: '0 0 * * *'
    displayName: 'Nightly build'
    branches:
      include: [main]
    always: false  # Only if code changed
最佳实践：
  • 使用路径过滤器避免不必要的构建
  • 为高频率提交的仓库启用批量构建
  • 使用PR触发器进行验证
  • 调度夜间/每周构建以进行全面测试
yaml
trigger:
  batch: true
  branches:
    include: [main, develop]
  paths:
    exclude: ['docs/*', '**.md']

pr:
  autoCancel: true
  branches:
    include: [main]

schedules:
  - cron: '0 0 * * *'
    displayName: 'Nightly build'
    branches:
      include: [main]
    always: false  # Only if code changed

Variable Management

变量管理

Hierarchy:
  1. Pipeline-level variables (az devops YAML)
  2. Variable groups (shared across pipelines)
  3. Azure Key Vault (secrets)
  4. Runtime parameters (user input)
Security:
  • Never hardcode secrets
  • Use Key Vault for sensitive data
  • Mark secrets in variable groups
  • Secrets are automatically masked in logs
层级结构：
  1. 管道级变量（az devops YAML）
  2. 变量组（跨管道共享）
  3. Azure密钥保管库（机密信息）
  4. 运行时参数（用户输入）
安全注意事项：
  • 绝不要硬编码机密信息
  • 使用密钥保管库存储敏感数据
  • 在变量组中标记机密
  • 机密信息会自动在日志中被屏蔽

Caching

缓存

Implement caching for:
  • Package dependencies (npm, pip, NuGet, Maven)
  • Docker layers
  • Build outputs
Impact:
  • Faster builds (up to 90% reduction)
  • Reduced network usage
  • Lower costs
为以下内容实现缓存：
  • 包依赖（npm、pip、NuGet、Maven）
  • Docker镜像层
  • 构建输出
效果：
  • 构建速度更快（最多可减少90%的时间）
  • 减少网络使用量
  • 降低成本

Templates

模板

Use templates for:
  • Reusable build patterns
  • Standardized deployment steps
  • Consistent security scanning
  • Company-wide best practices
Benefits:
  • DRY (Don't Repeat Yourself)
  • Centralized updates
  • Consistent processes
将模板用于：
  • 可复用的构建模式
  • 标准化的部署步骤
  • 一致的安全扫描
  • 全公司范围内的最佳实践
优势：
  • 遵循DRY（Don't Repeat Yourself，不要重复自己）原则
  • 集中化更新
  • 流程一致性

Security Practices

安全实践

Essential:
  • Code scanning (SAST, dependency)
  • Container image scanning
  • Secret scanning
  • Compliance checks
  • Branch protection policies
  • Required approvals
核心要求：
  • 代码扫描（SAST、依赖项扫描）
  • 容器镜像扫描
  • 机密信息扫描
  • 合规性检查
  • 分支保护策略
  • 必要的审批流程

Performance

性能优化

Optimize:
  • Parallelize independent jobs
  • Use caching extensively
  • Shallow git clones (fetchDepth: 1)
  • Appropriate agent pools
  • Clean up artifacts
优化方向：
  • 并行执行独立作业
  • 广泛使用缓存
  • 浅克隆Git仓库（fetchDepth: 1）
  • 使用合适的代理池
  • 清理构建产物

Monitoring

监控

Track:
  • Build success rates
  • Build durations
  • Test pass rates
  • Deployment frequency
  • Mean time to recovery (MTTR)
Always verify best practices against latest Azure DevOps documentation.
跟踪指标：
  • 构建成功率
  • 构建时长
  • 测试通过率
  • 部署频率
  • 平均恢复时间（MTTR）
请始终对照最新的Azure DevOps文档验证最佳实践。