AgileBuilder logoAgileBuilder
返回文档

模板语法

AgileBuilder 模板的 EJS 渲染语法——插值、条件、循环，默认 % 分隔符，6 个内置辅助函数，文件路径 {{var}} 渲染，以及二进制文件的处理规则。

AgileBuilder 用 EJS 渲染模板文件内容。只要 variables.enabled: true 且文件命中 filePatterns，生成时就会用变量值替换占位符。本文假设配置为：

variables:
  enabled: true
  delimiter: "%"

插值

默认分隔符是 %，标签写作 <% 与 %> 的组合：

写法行为
<%= value %>输出变量值，会做 HTML 转义（" 变成 &#34; 等）。
<%- value %>输出变量值，不做转义。
<% ... %>执行 JavaScript，不输出。

生成代码、JSON、YAML 时，值里常带引号，一般应使用 <%- %> 避免转义污染输出：

// 模板
"name": "<%- appName %>"

// appName = order-service 时生成
"name": "order-service"

修改 variables.delimiter 可以换分隔符，例如 delimiter: "?" 后写作 <?= appName ?>。

引用未定义的变量会以 TEMPLATE_VARS_MISSING 失败，并提示用 --var / --vars / --interactive 补齐——这让模板拼写错误在生成时立刻暴露，而不是静默输出空串。

条件渲染

<% if (useAuth) { %>
import { auth } from './auth';
<% } %>

配合 confirm 类型的交互问题效果最佳：

inquirerQuestions:
  - name: useAuth
    type: confirm
    message: Enable authentication?
    default: true

循环渲染

<% features.forEach(function (feature) { %>
- <%- feature %>
<% }) %>

features 为 ["auth", "logging"] 时生成：

- auth
- logging

多选变量（checkbox 类型问题）得到的正是数组，适合驱动循环。

内置辅助函数

六个命名风格转换函数既可以直接调用，也可以通过 helpers 命名空间调用，两种写法等价：

<%= pascalCase(appName) %>
<%= helpers.kebabCase(appName) %>

以 appName = "order-service" 为例：

函数调用输出
camelCase<%= camelCase(appName) %>orderService
pascalCase<%= pascalCase(appName) %>OrderService
kebabCase<%= kebabCase(camelCase(appName)) %>order-service
snakeCase<%= snakeCase(pascalCase(appName)) %>order_service
uppercase<%= uppercase(appName) %>ORDER-SERVICE
lowercase<%= lowercase("ORDER-Service") %>order-service

典型用途——一个变量派生出各生态的命名规范：

package.json:  "name": "<%= appName %>"
类名:          export class <%= pascalCase(appName) %>Service {}
常量:          const <%= camelCase(appName) %>Version = "1.0.0";

文件路径渲染

variables.enabled: true 时，文件与目录的路径也参与渲染。路径里推荐用 {{变量名}} 写法：

src/{{appName}}/index.ts

appName = order-service 时生成 src/order-service/index.ts。

路径渲染的规则：

  • {{ }} 内支持点路径取值，如 {{user.name}}；变量不存在时渲染为空字符串。
  • 路径中也可以写完整 EJS 表达式（如 <%= pascalCase(appName) %>），路径会先处理 {{ }}，再执行 EJS 渲染。
  • 文件名渲染同样受 filePatterns 影响的说法并不成立——路径渲染只看 variables.enabled；filePatterns 控制的是文件内容是否渲染。

不渲染的文件

以下文件不参与内容渲染：

  • 二进制文件：CLI 检测文件开头是否包含 NUL 字节，是二进制则原样复制。图片、字体、编译产物可以放心放进模板。
  • 配置文件：.agilebuilder.config.yaml / .agilebuilder.config.json 永远不复制到目标目录。
  • .git 目录：默认跳过；传 --keep-git 才会保留。
  • 被 filePatterns 排除的文件：按原样复制（见 文件匹配与 Hooks）。

一个完整片段

模板文件 src/{{appName}}.config.ts：

export const serviceName = "<%- appName %>";
export const serviceClass = "<%- pascalCase(appName) %>Service";
<% if (useAuth) { %>
export const authEnabled = true;
<% } %>

命令与生成结果：

ag create 1 --target ./out --var appName=order-service --var useAuth=true

// out/src/order-service.config.ts
export const serviceName = "order-service";
export const serviceClass = "OrderServiceService";
export const authEnabled = true;

下一步