SpringBoot Generator 生成代码时模板路径错误

Question

在使用SpringBoot Generator（如MyBatis-Plus代码生成器）时，常因模板路径配置错误导致代码生成失败。典型问题为：自定义模板文件未正确放置或FreeMarker模板路径未以`classpath:`开头，致使系统无法加载`controller.java.ftl`、`service.java.ftl`等模板文件，抛出`TemplateNotFoundException`。此外，项目模块结构复杂时，若未显式指定`TemplatePath`或资源未被编译到`target/classes`目录，也会引发路径查找失败。需确保模板位于`resources`目录下，并在代码生成器配置中正确设置`templateEngine.setTemplatePath()`或使用默认路径规则。

Answer 1

1. 问题背景与常见现象

在使用 Spring Boot 集成 MyBatis-Plus 代码生成器时，开发者常通过自定义 FreeMarker 模板（如 controller.java.ftl、service.java.ftl）来控制生成代码的结构和风格。然而，由于模板路径配置不当，频繁出现 TemplateNotFoundException 异常。

典型报错信息如下：

freemarker.template.TemplateNotFoundException: Template not found for name "controller.java.ftl"

该异常表明模板引擎无法从类路径中定位指定模板文件。尤其在多模块 Maven 或 Gradle 项目中，资源未正确编译至 target/classes 目录，或未以 classpath: 前缀声明路径，极易导致此类问题。

2. 路径解析机制深度剖析

MyBatis-Plus 使用 FreemarkerTemplateEngine 作为默认模板引擎，其加载模板依赖于 Configuration#getTemplate(String) 方法。该方法依据传入的路径尝试从 ClassPath 加载资源。

关键点在于：

• FreeMarker 默认搜索路径为 classpath:templates/；
• 若自定义路径未加 classpath: 前缀，则被视为相对文件系统路径；
• Spring Boot 构建过程中，仅 src/main/resources 下的内容会被复制到 target/classes；
• 模块间依赖若未显式声明资源导出，子模块模板可能不可见。

3. 典型错误场景与诊断流程

场景编号	错误描述	根本原因	日志特征
1	模板放于 src/main/java 下	非 resources 目录不参与资源编译	File not found on classpath
2	路径写成 /templates/controller.java.ftl	缺少 classpath: 前缀	Template not found
3	多模块项目中模板位于子模块	主模块未引入子模块资源	ClassLoader cannot locate resource
4	使用绝对路径但环境迁移	路径硬编码，缺乏可移植性	java.io.FileNotFoundException

4. 正确配置方式与最佳实践

为确保模板正确加载，需在代码生成器配置中显式设置模板路径。以下是推荐配置示例：

// 配置模板引擎
TemplateConfig templateConfig = new TemplateConfig();
templateConfig.setController("templates/controller.java.ftl");
templateConfig.setService("templates/service.java.ftl");
templateConfig.setServiceImpl("templates/serviceImpl.java.ftl");
templateConfig.setMapper("templates/mapper.java.ftl");
templateConfig.setXml("templates/mapper.xml.ftl");

// 设置模板引擎并指定模板路径前缀
FreemarkerTemplateEngine templateEngine = new FreemarkerTemplateEngine();
// 确保模板位于 resources/templates/ 下
templateEngine.setTemplatePath("classpath:templates/");

同时，在 pom.xml 中确认资源包含规则：

<resources>
  <resource>
    <directory>src/main/resources</directory>
    <includes>
      <include>**/*.ftl</include>
    </includes>
  </resource>
</resources>

5. 多模块项目中的路径管理策略

在复杂模块结构中，建议将通用模板集中于一个共享模块（如 code-generator-starter），并通过依赖引入：

1. 创建独立模块 generator-template；
2. 在其 src/main/resources/templates/ 放置所有 .ftl 文件；
3. 在父 POM 中声明该模块为依赖；
4. 使用 ClassLoader.getResourceAsStream("templates/controller.java.ftl") 验证可达性；
5. 代码生成器运行前执行资源扫描校验；
6. 结合 Spring Boot 的 @ConditionalOnResource 实现条件加载。

6. 自动化检测与流程图示意

为提升稳定性，可构建模板路径验证流程。以下为 Mermaid 流程图展示：

graph TD
    A[启动代码生成器] --> B{模板路径是否以 classpath: 开头?}
    B -- 否 --> C[抛出 ConfigurationException]
    B -- 是 --> D[尝试 ClassLoader 加载资源]
    D --> E{资源是否存在?}
    E -- 否 --> F[检查 target/classes/templates/ 是否存在文件]
    F --> G{编译后文件存在?}
    G -- 否 --> H[提示: 检查 resources 目录结构]
    G -- 是 --> I[成功加载模板]
    E -- 是 --> I
    I --> J[执行代码生成]