Giter8项目模板制作完全指南-CSDN博客

Giter8项目模板制作完全指南

模板授权建议

在创建Giter8模板时，授权方式是一个需要认真考虑的问题。我们强烈推荐使用CC0 1.0授权协议，这是一种类似于"公共领域"的国际通用授权方式，能够完全放弃所有版权及相关权利。

特别需要注意的是，在《伯尔尼公约》覆盖的国家（如美国），版权会自动产生而无需注册。这意味着如果你不为模板声明授权条款，其他人将没有合法权利使用你的模板。即使是宽松的MIT或Apache授权，也会要求使用者在他们的软件中注明模板来源。采用CC0授权可以彻底解决这个问题，让模板代码片段真正成为公共资源。

建议在模板中包含如下授权声明：

模板授权声明
----------------
由<作者姓名> <作者邮箱>于<年份>编写
[其他作者/贡献者信息]

作者已尽可能放弃对此模板的所有版权及相关权利，
将其贡献至全球公共领域。
本模板不提供任何担保。详见CC0 1.0授权协议。

模板目录结构详解

Giter8运行时会在项目中查找两种目录结构来定位模板：

推荐结构：优先查找src/main/g8目录（src布局）
备选结构：如果不存在上述目录，则使用项目根目录（root布局）

root布局（实验性）

root布局是一种实验性结构，直接使用GitHub项目的根目录作为模板根目录。由于这种布局下无法在project目录下的文件中使用模板字段，其应用场景非常有限，仅适用于不需要字段替换的非sbt项目模板。

模板属性文件详解

default.properties文件可以放置在project/目录或模板根目录下。这个文件定义了模板中的可替换字段及其默认值。

Giter8使用StringTemplate引擎处理模板，模板字段在源文件中用$字符包围。例如：

class $classname$ {

属性值的动态引用

模板字段可以相互引用，构建更复杂的默认值。例如：

name = URL Builder
github_id=githubber
developer_url=https://github.com/$github_id$
project_url=https://github.com/$github_id$/$name;format="norm"$

在交互模式下会显示为：

name [URL Builder]: my-proj
github_id [githubber]: n8han
project_url [https://github.com/n8han/my-proj]:
developer_url [https://github.com/n8han]:

特殊字符转义

需要显示$符号时，可以使用反斜杠转义：

val foo = "foo"
val bar = "bar"
println(s"\\$foo\\$bar")

输出结果为：

val foo = "foo"
val bar = "bar"
println(s"$foo$bar")

保留字段名限制

某些变量名是StringTemplate语法保留字，不能用作字段名，常见的有：

"i", "i0", "if", "else", "elseif", "endif", "first", "length"
"strlen", "last", "rest", "reverse", "trunc", "strip", "trim"

高级模板功能

模板注释

可以使用特殊语法添加仅对模板维护者可见的注释，这些注释不会出现在生成的输出中：

$! 这个注释不会出现在输出中 !$
// 这个注释会出现在输出中
$!
这个多行注释
同样不会出现
在输出中
!$

条件语句

所有字段都有一个名为truthy的属性，可用于条件表达式。"y"、"yes"和"true"会被视为true，其他值则为false。

示例：

scala212 = yes
scala211 = no

在模板中使用：

$if(scala212.truthy)$
scalaVersion := "2.12.3"
$elseif(scala211.truthy)$
scalaVersion := "2.11.11"
$else$
scalaVersion := "2.10.6"
$endif$

条件语句也可用于控制文件/目录的包含：

src/main/g8
├── $name__normalize$
│   ├── $if(jvm.truthy)$jvm$endif$
│   │   └── src
│   │       └── main
│   │           └── scala
│   │               └── $organization__packaged$
│   │                   └── $name;format="Camel"$.scala

若要跳过目录但保留其内容，可以使用.作为目录名：

src/main/g8
├── parent_folder
│   ├── $if(cond.truthy)$skip_folder$else$.$endif$
|   |   └── child_file

特殊字段处理

name字段：被视为项目名称，g8运行时会基于此名称创建输出目录（空格和大写字母会被替换）。如果未指定，输出将直接放在当前工作目录。
package字段：被视为源代码包名， $package$ 会扩展为目录结构（如net.databinder变为net/databinder）。
verbatim字段：定义空格分隔的文件模式（如*.html *.js），匹配的文件将跳过模板处理。

Maven中央仓库集成

Giter8可以直接查询Maven中央仓库获取最新版本号，避免手动更新模板：

unfiltered_version = maven(ws.unfiltered, unfiltered_2.11)

若只需要稳定版（排除里程碑版和候选版）：

scalatest_version = maven(org.scalatest, scalatest_2.11, stable)

通过掌握这些功能，你可以创建出功能强大且易于维护的Giter8模板，大大提高项目初始化的效率和一致性。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

Giter8项目模板制作完全指南