IntelliJ IDEA给Controller、Service、Mapper不同文件设置不同的文件头注释模板、Velocity模板引擎

通过在 IntelliJ IDEA 中的 “Includes” 部分添加多个文件头模板，并在 “Files” 模板中利用这些包含来实现不同类型文件的注释。以下是为 Controller、Service、Mapper 文件设置不同文件头的完整示例：

1. 设置 Includes 文件头模板

File > Settings （在 macOS 上是 Preferences）> Editor > File and Code Templates > includes

在 “Includes” 选项卡中，创建以下三个文件头模板：

ControllerHeader

/**
 * 控制层：
 * Controller Class: ${NAME}
 * @Author: ${USER}
 * @Date: ${DATE} ${TIME}
 * @Version: ${VERSION}
 * @Description: ${DESCRIPTION}
 */

ServiceHeader

/**
 * 服务层：
 * Service Class: ${NAME}
 * @Author: ${USER}
 * @Date: ${DATE} ${TIME}
 * @Version: ${VERSION}
 * @Description: ${DESCRIPTION}
 */

MapperHeader

 /**
 * 数据层：
 * Mapper Class: ${NAME}
 * @Author: ${USER}
 * @Date: ${DATE} ${TIME}
 * @Version: ${VERSION}
 * @Description: ${DESCRIPTION}
 */

2. 设置 Files 模板

2.1 设置路径

File > Settings （在 macOS 上是 Preferences）> Editor > File and Code Templates > includes

2.2 在 “Files” 选项卡中，找到或创建 Java 类模板，并使用条件判断来选择合适的文件头：

2.2.1 根据文件名区分

${NAME.endsWith("Controller")}这种写法专业名词叫Velocity 模板引擎，关于该引擎在后续有详细介绍

#if (${NAME.endsWith("Controller")})
    #parse("ControllerHeader.java")
#elseif (${NAME.endsWith("Service")})
    #parse("ServiceHeader.java")
#elseif (${NAME.endsWith("Mapper")})
    #parse("MapperHeader.java")
#else
/**
 * Class: ${NAME}
 * Author: ${USER}
 * Date: ${DATE}
 * Description: ${DESCRIPTION}
 */
#end

使用更严谨的File template

#if (${NAME.matches(".*Controller$")})
    #parse("ControllerHeader.java")
#elseif ($NAME.matches(".*Service$") || $NAME.matches(".*ServiceImpl$"))
    #parse("ServiceHeader.java")
#elseif (${NAME.matches(".*(Mapper|Dao|Repo)$")})
    #parse("DataLayerHeader.java")
#else
/**
 * Class: ${NAME}
 * Author: ${USER}
 * Date: ${DATE}
 * Description: ${DESCRIPTION}
 */
#end

2.2.2根据包名区分

#if (${PACKAGE_NAME}.contains("controller"))
/**
 * Controller层 - ${NAME}
 * 包路径：${PACKAGE_NAME}
 */
#elseif (${PACKAGE_NAME}.contains("service"))
/**
 * Service层 - ${NAME}
 */
#elseif (${PACKAGE_NAME}.contains("mapper"))
/**
 * Mapper接口 - ${NAME}
 */
#end

• 更严谨的判断

#set($isMapperPackage = ${PACKAGE_NAME.contains(".mapper")} || ${PACKAGE_NAME.contains(".dao")})
#set($isServiceImplPackage = ${PACKAGE_NAME.contains(".service.impl")})

#if ($isMapperPackage && ($isMapper || ${NAME.endsWith("Repository")}))
  #parse("mapperHeader.java")
#elseif ($isServiceImplPackage)
  #parse("serviceImplHeader.java")
#end

3. 应用模板

• 当你创建一个新文件时，例如 UserController.java、UserService.java 或 UserMapper.java，IDEA 将根据文件名后缀自动应用相应的文件头注释。
• 确保新文件的命名遵循 *Controller、*Service、*Mapper 的模式，以便条件判断能够正确匹配。

---

4. 为不同文件类型创建完全独立模板

4.1 实图讲解

• 新增Controller模板—效果图：
  
• New -> Java Class-> Controller 就会出现新添加的模板
  

4.2 自定义Files模板详细设置

在 IntelliJ IDEA 中创建需要的文件模板，比如 Controller、Service、Mapper，可以通过以下步骤来实现：

1. 打开文件模板设置：

   • 在 IntelliJ IDEA 的菜单栏中，点击 File -> Settings（在 macOS 上是 IntelliJ IDEA -> Preferences）。
   • 在左侧栏中，选择 Editor -> File and Code Templates。

2. 创建新的文件模板：

   • 在 Files 标签页中，点击右上角的 + 按钮，创建一个新的文件模板（如Controller）。
   • 为你的模板命名，比如 Controller、Service、Mapper，
   • 设置文件名：如Controller等，扩展名：java。

3. 定义文件模板内容：

   • 在模板的编辑器中输入你希望的文件内容。你可以使用变量来动态生成代码，如 ${NAME}、${PACKAGE_NAME} 等。

   • 例如，对于一个 Controller 模板，你可以这样定义：

     package ${PACKAGE_NAME};
     
     import org.springframework.web.bind.annotation.*;
     
     #parse("ControllerHeader.java")
     @RestController
     @RequestMapping("/${NAME}")
     public class ${NAME}Controller {
         
         // Add your endpoints here
     }
     

   • 对于 Service 模板，可以这样定义：

     package ${PACKAGE_NAME};
     
     import org.springframework.stereotype.Service;
     
     #parse("ServiceHeader.java")
     @Service
     public class ${NAME}Service {
         
         // Add your service methods here
     }
     

   • 对于 Mapper 模板，可以这样定义：

     package ${PACKAGE_NAME};
     
     import org.apache.ibatis.annotations.Mapper;
     
     #parse("MapperHeader.java")
     @Mapper
     public interface ${NAME}Mapper {
         
         // Add your mapper methods here
     }
     

4. 使用模板：

   • 当你创建新文件时，右键点击项目结构树中的目标包或目录，选择 New -> Java Class。
   • 在弹出的对话框中，选择你创建的模板（如 Controller、Service、Mapper）。
   • 输入文件名，IDEA 会根据模板自动生成文件内容，包括你预定义的文件头注释。

通过这些步骤，你可以为常用的文件类型创建模板，提升开发效率和代码的一致性。

5. Velocity 模板引擎

如**#set** 是 Velocity 模板引擎的核心指令之一。以下为您完整解析 Velocity 的语法体系和学习路径：

---

5.0 相关指令

以下是 Velocity 模板引擎核心指令的详细解析：

---

一、变量操作指令

1. #set - 变量赋值

#set($var = "value")              ## 字符串
#set($num = 10 + 5)               ## 数值计算
#set($list = [1, 2, 3])           ## 列表
#set($map = {"key":"value"})      ## 键值对

特性：

• 右值可以是表达式、方法调用或嵌套指令
• 变量类型动态推断（无需声明类型）
• 变量作用域为整个模板（类似全局变量）

特殊场景：

## 多变量赋值
#set($a = $b = 10)

## 空值处理
#set($result = $optionalValue ?: "default")

---

二、流程控制指令

2. #if / #elseif / #else - 条件分支

#if($user.role == "admin")
  ADMIN MODE
#elseif($user.age >= 18)
  ADULT USER
#else
  GUEST MODE
#end

判断规则：

条件表达式	判定为 false 的情况
$var	null、空字符串、空集合、false
$var == 5	值不相等或类型不同
$list && $list.size() > 0	组合逻辑判断

3. #foreach - 循环迭代

#foreach($item in $items)
  Item $foreach.index: $item.name
  #if($foreach.count == 5)
    #break  ## 退出循环
  #end
#end

循环变量：

属性	说明
$foreach.index	当前索引（从 0 开始）
$foreach.count	当前计数（从 1 开始）
$foreach.first	是否是第一次迭代（布尔值）
$foreach.last	是否是最后一次迭代（布尔值）

---

三、模板组织指令

4. #include - 静态引入

#include("header.html") 

特点：

• 引入的文件内容不解析 Velocity 语法
• 适合引入静态 HTML/CSS/JS 片段
• 可一次引入多个文件：

  #include("head.html", "footer.html")
  

5. #parse - 动态解析

#parse("user_card.vm")

与 #include 对比：

特性	#parse	#include
语法解析	✅ 会解析 VTL 指令	❌ 原样输出
变量共享	✅ 共享当前上下文变量	❌ 无变量传递
性能	较低（需解析）	较高（直接读取）

6. #stop - 引擎停止

#if($error)
  #stop  ## 立即终止模板渲染
#end

使用场景：

• 遇到致命错误时中断渲染
• 调试时快速定位问题

---

四、逻辑控制指令

7. #break - 退出当前指令

#foreach($item in $list)
  #if($item == "stop") 
    #break  ## 退出当前 #foreach 循环
  #end
#end

作用范围：

• 仅对当前所在指令有效（如 #foreach、#macro）

8. #evaluate - 动态执行

#set($template = "Hello $name")
#evaluate($template)  ## 输出：Hello John

危险操作：

## 可能引发代码注入（慎用！）
#evaluate($userInput)

---

五、代码复用指令

9. #define - 定义代码块

#define($block)
  

    This is a reusable block
  
#end

## 调用
$block

特点：

• 类似变量赋值，但可包含复杂 HTML/VTL
• 每次调用输出相同内容

10. #macro - 定义可传参宏

#macro(renderUser $user $isAdmin)
  

    $user.name
  
#end

## 调用
#renderUser($currentUser true)

高级特性：

功能	示例
默认参数	#macro(show $msg="Hello")
可变参数	#macro(sum $nums...)
嵌套调用	宏内可调用其他宏

---

六、指令对比矩阵

指令	是否解析内容	是否共享变量	典型应用场景
#include	❌	❌	引入静态资源文件
#parse	✅	✅	模块化动态模板
#define	✅	✅	定义重复使用的静态内容块
#macro	✅	✅	创建带参数的复用组件

---

七、安全实践建议

1. 避免 #evaluate 用户输入

   ## 危险！
   #evaluate($request.getParameter("tpl"))
   

2. 防御性模板设计

   ## 安全变量引用
   $!{userInput}  ## 自动处理 null
   
   ## 集合判空
   #if($!{list} && $list.size() > 0)
   

3. 性能优化

   ## 复杂计算预编译
   #set($regex = "^\\d{4}-\\d{2}-\\d{2}$")
   #if($dateStr.matches($regex))
   

---

八、完整示例模板

## 用户列表模板 (user_list.vm)
#define($header)
  
  
  
    
    #include("styles.css")
  
#end

#macro(userCard $user)
  

    #parse("user_avatar.vm")
    
$!{user.name}
    #if($user.isAdmin)
      ADMIN
    #end
  
#end

$header

  #foreach($user in $users)
    #if($user.name == "root")
      #stop  ## 禁止显示 root 用户
    #end

    #userCard($user)

    #if($foreach.count >= 100)
      #break  ## 最多显示 100 条
    #end
  #end

  #parse("footer.vm")

---

以上内容可作为 Velocity 开发的权威参考，建议结合官方文档实践验证。每个指令的详细行为可能因 Velocity 版本略有差异（本文基于 2.x 版本）。

5.1、#set 指令详解

5.1.1. 基础作用

#set($variable = "value") 

• 变量定义：创建或修改变量（类似编程中的赋值）
• 动态计算：可赋值为字符串、数字、布尔值，或通过表达式计算的结果
• 作用域：在整个模板中有效（类似全局变量）

5.1.2. 典型用法

## 字符串赋值
#set($className = "UserController")

## 数值计算
#set($total = 10 + 5 * 3)  ## $total = 25

## 布尔逻辑
#set($isValid = $name && $name.length() > 5)

## 对象方法调用
#set($firstChar = $className.substring(0,1)) 

---

5.2、Velocity 的语法规则

Velocity 的语法规则来源于以下渠道：
5.2.1. 官方文档
Apache Velocity 官网 (velocity.apache.org) 提供完整的 VTL (Velocity Template Language) 规范。

5.2.2. IDE 集成

• IntelliJ IDEA 等 IDE 的 Velocity 模板编辑界面会提供语法提示
• 输入 # 时会自动弹出指令列表（如 #if, #foreach, #macro）

5.2.3. 开源项目实践

• 许多 Java 项目（如 Spring Boot 的代码生成器）使用 Velocity 模板
• 通过阅读开源代码学习实际应用技巧

---

5.3、系统学习 Velocity 语法的路径

5.3.1. 基础语法

指令/语法	用途	示例
变量引用	输出变量值	$variable 或 ${variable}
注释	添加模板注释	## 单行注释 或 #* 多行注释 *#
#set	变量赋值	#set($price = 99.9)
#if/#else/#elseif	条件分支	见下方示例
#foreach	循环遍历集合	见下方示例

条件判断示例：

#if($user.role == "admin")
  
管理员权限
#elseif($user.age > 18)
  
成年用户
#else
  
未成年用户
#end

循环示例：

#foreach($item in $items)
  
${foreach.index} - ${item.name}
#end

5.3.2. 高级功能

功能	说明	示例
宏 (Macro)	定义可复用的代码片段	#macro(showError $msg) $msg #end
引入其他模板	模块化模板设计	#parse("header.vm")
内置工具对象	提供字符串/数学等工具方法	$math.add(1,2) 或 $date.format('yyyy-MM-dd')
转义输出	防止 XSS 攻击	$!{userInput} 或 #escape($htmlContent)

宏定义与调用：

## 定义宏
#macro(renderButton $text $color)
  $text
#end

## 调用宏
#renderButton("提交", "blue")

5.3.3. 调试技巧

• 输出原始文本：使用 #[[ 不解析的内容 ]]#

  #[[
   这里的 $variable 不会被解析 → 直接输出 $variable
  ]]#
  

• 查看变量类型：

  $variable.class.name  ## 输出变量类型（如 java.lang.String）
  

---

5.4、快速查询手册

在模板开发中常用以下语法：

需求场景	对应语法
避免变量为 null 时报错	$!{variable}
字符串拼接	#set($fullName = "$firstName $lastName")
集合是否为空判断	#if($list.isEmpty()) 或 `#if(!$list
数值格式化	$number.format("#,###", $price)
日期格式化	$date.format('yyyy-MM-dd', $today)

---

5.5、学习资源推荐

5.5.1. 官方文档（必读）

• VTL 语法参考
• 用户指南

5.5.2. 实战教程

• Baeldung 的 Velocity 指南
• TutorialsPoint 的 Velocity 教程

5.5.3. IDE 辅助

• 在 IntelliJ IDEA 中创建 .vm 文件，IDE 会提供：
  • 语法高亮
  • 指令自动补全（输入 # 触发）
  • 错误检查

---

5.6、示例：完整模板文件

## 模板：user_profile.vm
#set($user = $data.getUser())
#set($birthday = $date.format('yyyy-MM-dd', $user.birthDate))



  


  #if($user.isAdmin())
    
管理员用户
  #end

  
用户信息
  

    
姓名：$!{user.name}
    
年龄：$math.sub($date.getYear(), $user.birthYear)
    
生日：$birthday
  

  #macro(renderSection $title $content)
    

      
$title
      
$content
    
  #end

  #renderSection("联系方式", $user.contactInfo)

---

通过系统学习上述内容，您将能：

1. 熟练使用 Velocity 生成动态内容
2. 理解模板引擎的运行机制
3. 快速定位和解决模板渲染问题

建议边学边实践，在 IntelliJ 中创建 .vm 文件体验实时语法反馈。

5.7 Velocity引擎与Freemarker等热门引擎对比以及应用场景

Velocity 确实不如 Freemarker、Thymeleaf 这类模板引擎知名度高，但它是一个历史悠久且特定场景下非常高效的模板引擎。以下是它的核心应用场景和特点解析，帮助您理解为什么某些场景（比如 IDEA 的注释模板）会选择它：

---

一、Velocity 的典型应用场景

1. 代码生成（核心优势场景）

• Java 注释模板（如 IDEA 内置）
• MyBatis 逆向工程（生成 DAO/Mapper 文件）
• Spring Boot 项目脚手架（如 JHipster 早期版本）
• API 文档生成（结合 Swagger 模板）

优势：
✅ 语法简单，适合非前端开发者使用
✅ 无复杂依赖，可嵌入任何 Java 环境
✅ 生成纯文本（代码/配置文件）时性能极高

2. 传统 Web 页面渲染（逐渐被替代）

• 早期的 Java Web 项目（如 Struts 1.x 时代）
• 企业级 CMS 内容模板（如 Alfresco）

现状：
⚠️ 新项目更推荐 Thymeleaf/FreeMarker（对现代前端更友好）
⚠️ 不支持响应式设计等现代特性

3. 邮件模板

• 企业级邮件内容动态生成（如订单通知）
• 相比 HTML 页面，邮件模板更简单，Velocity 足够轻量

4. 配置文件动态化

#set($dbHost = "192.168.1.100")
jdbc.url=jdbc:mysql://${dbHost}:3306/db

---

二、为什么 IDEA 选择 Velocity 做注释模板？

1. 轻量级
   无需引入额外依赖，IDEA 内置的模板引擎需要极低的开销。

2. 逻辑简单
   注释模板通常只需要变量替换和简单条件判断，例如：

   /**
    * @author ${USER}
    * @date ${DATE}
    #if(${DESCRIPTION})
    * @description ${DESCRIPTION}
    #end
    */
   

3. 无副作用
   不会像 FreeMarker 那样产生意外换行或空格（对代码格式敏感）。

---

三、与现代模板引擎对比

特性	Velocity	FreeMarker	Thymeleaf
学习曲线	⭐（最简单）	⭐⭐	⭐⭐⭐（需懂 HTML）
性能	⭐⭐⭐（最快）	⭐⭐	⭐
前端友好度	❌（纯后端）	✅	✅⭐⭐⭐（原生 HTML）
动态代码生成	✅⭐⭐⭐	✅⭐	❌
社区活跃度	⭐（维护模式）	⭐⭐⭐	⭐⭐⭐⭐

---

四、经典代码生成示例

MyBatis 生成器模板（mapper.xml.vm）

  #foreach($field in ${table.fields})
    #if(${field.keyFlag})
      
    #else
      
    #end
  #end
  
  
    SELECT * FROM ${table.name} WHERE id = #{id}
  

Spring Controller 模板（Controller.java.vm）

#set($entity = ${table.entityName.toLowerCase()})
@RestController
@RequestMapping("/api/${entity}")
public class ${table.controllerName} {
    @Autowired
    private ${table.serviceName} ${entity}Service;

    @GetMapping("/{id}")
    public Result<${table.entityName}> getById(@PathVariable ${table.primaryKeyType} id) {
        return Result.success(${entity}Service.getById(id));
    }
}

---

五、什么时候应该选择 Velocity？

1. 需要生成代码/配置文件
   （如自动生成 CRUD 代码、批量创建相似文件）

2. 嵌入式模板需求
   （如插件系统需要允许用户自定义模板）

3. 历史项目维护
   （老系统升级时保留原有模板）

---

六、为什么不推荐新项目用 Velocity 做页面渲染？

1. 功能局限
   缺少模板继承、片段复用等现代特性，复杂页面难以维护。

2. 前后端协作困难
   设计师无法直接修改 HTML（模板语法混合在标签中）。

3. 安全风险
   默认不开启 HTML 转义，容易导致 XSS 攻击（需手动处理）。

---

七、快速识别 Velocity 模板

1. 文件扩展名：.vm
2. 语法特征：

   
   <h1>$titleh1>
   
   
   #foreach($item in $list)
     <li>$itemli>
   #end
   

---

如果您只需要一个轻量级文本生成工具（如代码注释、配置文件生成），Velocity 仍然是优秀选择。但对于 Web 页面开发，建议转向 FreeMarker/Thymeleaf 等现代引擎。