# 通用模板技能关于模板格式选择、设计模式、生成工作流程以及 Handlebars、Cookiecutter、Copier、Maven 和 Harness 模板的最佳实践的综合指南。 ## 模板格式矩阵 ### 车把 **使用案例：** * 简单的变量替换 * 电子邮件模板 * 文档生成 * 配置文件 * 快速字符串模板 **语法：** 你好{{name}}， {{#if premium}}欢迎使用 Premium！{{/if}} {{#each 项目}}- {{this}}{{/each}} **优点：** * 最小的学习曲线 * 快速执行 * 非常适合配置文件 * 文件大小小 * 无外部依赖 **弱点：** * 逻辑能力有限 * 没有原生循环/条件 * 复杂操作需要助手 **最适合：** 配置文件模板，简单的文档生成 ** ** ### 饼干切割机 **使用案例：** * 交互式项目脚手架 * 多步骤向导模板 * Python包模板 * 后生成钩子 **语法：** { "project_name": "{{ cookiecutter.project_name }}", “作者”：“{{ cookiecutter.author_name }}” } **优点：** * 交互式CLI提示 * Python生态系统集成 * 后生成钩子 * 条件渲染 * 基于 JSON 的配置 **弱点：** * 需要Python依赖 * Jinja2 模板（详细） * 验证不太灵活 * 社区模板质量参差不齐 **最适合：** Python 项目、快速原型、社区模板 ** ** ### 复印机 **使用案例：** * 现代工程脚手架 * 模板版本控制和更新 * 多模板组合 * 复杂的验证规则 **语法：** _templates_后缀：.jinja _copy_without_render： - “*.png” - “*.jpg” 项目名称：类型：str 帮助：你的项目名称是什么？默认值：my_project **优点：** * 强大的 Jinja2 模板 * 模板版本控制 * 更新现有项目 * 复合模板 * 高级验证 * 优秀的文档 **弱点：** * Python依赖 * 更陡峭的学习曲线 * 占地面积更大 * 开发活跃（API 可能发生变化） **最适合：** 企业模板、版本化脚手架、复杂项目 ** ** ### Maven **使用案例：** * Java/JVM 项目原型 * 企业Java脚手架 * 构建系统集成 * 依赖管理 **语法：** <原型> org.apache.maven.archetypes maven-archetype-quickstart **优点：** * 原生 Maven 集成 * 建立工具意识 * 依赖管理 * 企业采用 * IDE 具有内置支持 **弱点：** * 仅限 Java/JVM * XML 重 * 复杂的原型内部结构 * 详细设置 **最适合：** Java/JVM 项目、基于 Maven 的构建 ** ** ### 安全带模板 **使用案例：** * CI/CD 管道步骤 * 可重复使用的阶段定义 * 管道模式 * 部署策略 **语法：** 模板：名称：部署服务类型：StepGroup 规格：步骤： - 步骤：名称：部署K8s 标识符：deploy_k8s 类型：K8s部署规格：服务：<+输入> **优点：** * 原生线束集成 * 表达语言支持 * 运行时输入 * 管道感知 * 内置审批流程 **弱点：** * 仅限特定线束 * YAML 复杂性 * 需要线束设置 * 线束之外的重复使用性有限 **最适合：** 利用管道、部署模板 ** ** ## 格式选择决策树 START：需要生成什么？ │ ├─ 配置文件 │ ├─ 简单替换→车把 │ └─ 复杂验证 → Copier │ ├─ 工程脚手架 │ ├─ Python 项目 → Cookiecutter │ ├─ 企业/版本 → 复印机 │ └─ Java/JVM → Maven │ ├─ CI/CD 管道 │ ├─ 线束平台 → 线束模板 │ └─ 其他CI → 车把+定制 │ ├─ 文件/电子邮件 │ └─ 车把 │ └─ 可重复使用的组件 ├─ 代码片段 → 车把 └─ 全模块→复印机 ** ** ## 生成工作流程步骤 ### 第 1 步：模板规划 **输入：** * 目标受众（用户、开发人员、自动化） * 使用案例和场景 * 复杂程度（简单、中等、高级） * 维护负担承受能力 * 集成要求 **可交付成果：** * 模板规范文件 * 格式选择理由 * 变量命名约定文档 * 实例化示例 **要回答的问题：** 1、会产生什么？ 2. 谁使用它（用户、脚本、工具）？ 3. 多久会改变一次？ 4. 需要版本控制吗？ 5. 需要什么验证？ ** ** ### 步骤 2：变量定义 **基本变量：** project_name - 主要标识符作者姓名 - 创建者/维护者组织 - 公司/组织名称描述 - 简要描述许可证 - 许可证类型（MIT、Apache 等） target_framework - 框架/语言版本 **可选变量（按用例）：** // Python 项目 python_version - 目标Python版本 package_name - PyPI 包名称 django_version - Django 版本（如果适用） // Java 项目 java_version - JDK 版本 groupId - Maven 组 ID artifactId - Maven 工件 ID // 云项目 aws_region - AWS 区域 kubernetes_cluster - K8s 集群名称 docker_registry - 容器注册表 ** ** ### 步骤 3：变量命名约定 **命名规则：** 1. **格式：** `snake_case` （所有格式都支持） 2. **前缀：** * ` generated_*` \- 由模板创建的文件/内容 * `input_*` \- 需要用户输入 * `compated_*` \- 从其他变量派生 * `可选_*` \- 可选的用户输入 3. **示例：** ✓ 项目名称 ✓ 作者_电子邮件 ✓ 生成版本 ✓ 目标框架 ✗ 项目名称（避免 PascalCase） ✗ PROJECT_NAME（避免 SCREAMING_SNAKE_CASE） ** ** ### 第四步：内容结构设计 **标准项目结构：** {项目名称}/ ├── README.md # 模板说明 ├── {project_name}/ # 主包/应用程序 │ ├── __init__.py #（如果适用） │ ├── main.py │ └── 配置.py ├──tests/ # 测试目录 │ ├── __init__.py │ └── test_main.py ├── docs/ # 文档 │ └── API.md ├── .gitignore ├── 许可证 ├── 要求.txt # (Python) ├── setup.py # (Python) ├── package.json # (Node.js) └── {{cookiecutter.var}}/ # 模板变量 ** ** ### 步骤 5：条件渲染 **何时使用：** * 可选功能 * 不同的项目类型 * 特定于目标的配置 * 基于许可证的文件 **车把示例：** {{#if include_docker}} 来自Python：3.11 复制。 /应用程序 {{/如果}} **饼干切割机/复印机示例：** {%- 如果 use_docker %} # Docker 配置 {%-endif%} ** ** ### 第 6 步：验证和约束 **输入验证：** * 邮件格式检查 * 版本号验证 * 项目名称唯一性检查 * 路径验证 **复印机示例：** 项目名称：类型：str help：项目名称（小写、字母数字+下划线）正则表达式：“^[a-z_][a-z0-9_]*$” python_版本：类型：str 默认值：“3.11” 帮助：Python版本（3.9、3.10、3.11、3.12）选择： - “3.9” - “3.10” - “3.11” - “3.12” ** ** ### 第 7 步：后代挂钩 **饼干切割机/复印机挂钩：** # 钩子/post_gen_project.py 导入操作系统从 pathlib 导入路径 # 初始化git仓库 os.system("git init") # 创建虚拟环境 os.system("python -m venv venv") # 安装依赖项 os.system(“pip install -r 要求.txt”) # 生成API文档 os.system(“pythongenerate_docs.py”) ** ** ### 步骤 8：文档 **所需文件：** 1. **README.md** \- 如何使用模板 2. **VARIABLES.md** \- 所有可用变量 3. **EXAMPLES.md** \- 实例化示例 4. **TROUBLESHOOTING.md** \- 常见问题 ** ** ## 模板设计的最佳实践 ### 1\.变量默认值 **良好的默认值：** # 清晰、合理的默认值作者姓名：“你的名字” 许可证：“麻省理工学院” python_version: "3.11" # 最新稳定版 include_docker: false # 选择加入以提高复杂性 include_tests: true # 从测试开始总是好的 **错误的默认值：** # 不清楚或为空作者姓名：“” 未知变量：“？？？” version: "1.0.0" # 应该是上下文感知的 ** ** ### 2\. DRY原则（不要重复自己） **模板变量一次：** 定义：project_name = "my_project" 用于： - 目录名称 - 自述文件标题 -Setup.py名称 - Docker 镜像名称 ** ** ### 3\.文件组织 **组相关文件：** 模板/ ├── [project_name]/ # 项目源（保持原样） ├── [project_name]_docs/ # 文档结构 ├── [project_name]_config/ # 配置模板 └──测试/#测试模板 ** ** ### 4\.模板可读性 **使用清晰的评论：** {# 该文件是从 {{template_name}} #} 生成的 {# 最后更新时间：{{ generated_date}} #} {# 如有问题，请参阅：{{docs_url}} #} ** ** ### 5\.版本管理 **模板版本控制：** # 在模板元数据中版本：“1.0.0” 线束兼容性：“1.4+” 最小_python：“3.9” ** ** ### 6\.错误处理 **清除错误消息：** # 而不是：ValueError # 使用：如果不是 re.match(r"^[a-z_][a-z0-9_]*$", project_name): 引发值错误（ f“项目名称 '{project_name}' 无效。\n” f“必须以小写字母或下划线开头，\n” f“后跟小写字母、数字或下划线。” ） ** ** ## 模板生成工作流程 ### 端到端生成过程 1. 用户选择 ├─ 选择模板 ├─ 选择格式（如果灵活） └─ 提供变量 2. 验证 ├─ 验证所有输入 ├─ 检查约束条件 └─ 生成变量报告 3. 预处理 ├─ 计算导出变量 ├─ 展开条件句 └─ 构建文件树 4. 一代 ├─ 渲染模板 ├─ 复制静态文件 ├─ 创建目录结构 └─ 处理特殊文件 5. 后处理 ├─ 运行钩子 ├─ 初始化git/vcs ├─ 安装依赖 └─ 生成文档 6. 验证 ├─ 检查生成的文件 ├─ 验证结构 ├─ 测试基本功能 └─ 生成报告 7. 输出 ├─ 显示概要 ├─ 提供后续步骤 └─ 保存清单 ** ** ## 在模板中利用表达语言 ### 可用的上下文变量驾驭表达： ├─ <+input.VARIABLE_NAME> # 输入 ├─ <+pipeline.PROPERTY> # 管道级别 ├─ <+stage.PROPERTY> # 舞台级别 ├─ <+steps.STEP_ID.PROPERTY> # 步骤输出 ├─ <+env.PROPERTY> # 环境变量 ├─ <+secrets.getValue("NAME")> # 秘密引用 └─ <+execution.PROPERTY> # 执行上下文 ### 带有表达式的模板示例模板：名称：部署服务类型：步骤规格：服务：名称：<+输入.服务名称> 环境：名称：<+输入.环境> 变量：版本：<+input.artifact_version> 部署超时：<+input.timeout_分钟> 需要批准：<+input.requires_approval> ** ** ## 相关文档 * [Handlebars.js]() * [Cookiecutter]() * [复印机]() * [Maven 原型]() * [线束模板]()

通用模板

包含技能