Apache Velocity作为Java生态中广泛使用的模板引擎，在处理变量和字面量时，点号的使用规则有明确要求，混淆两者的处理逻辑很容易导致模板渲染异常。很多开发者在编写模板时，会因为不清楚点号对不同类型内容的解析差异，写出不符合预期的代码。
Velocity中点号的基础解析逻辑
Velocity对点号的处理会根据点号前后的内容类型自动切换解析模式，核心区分依据是点号左侧是变量引用还是字面量字符串。如果是变量引用，点号会触发属性访问或者方法调用；如果是字面量，点号会被当作普通字符处理。
变量场景下的点号处理
当点号左侧是已经定义的Velocity变量时，点号用于访问变量的属性或者调用变量的方法，Velocity会自动解析对应的Java对象属性或者方法返回值。
## 定义用户对象变量 #set($user = $userService.getUserById(1)) ## 访问用户对象的name属性，点号触发属性解析 用户名称：$user.name ## 调用用户对象的getAge方法，点号触发方法调用 用户年龄：$user.getAge()
如果变量是Map类型，点号还可以用于获取Map中对应key的值，等价于使用方括号的写法。
#set($config = {"site_name":"测试站点","version":"1.0"})
## 两种写法等价，都获取key为site_name的值
站点名称：$config.site_name
站点名称：$config["site_name"]
字面量场景下的点号处理
当点号左侧是字符串字面量时，点号不会被特殊解析，会直接作为字符串的一部分存在。Velocity中字符串字面量需要用单引号或者双引号包裹，未包裹的内容会被当作变量名解析。
## 字面量中的点号是普通字符 #set($literal_str = "com.example.service.UserService") 完整类名：$literal_str ## 未加引号的内容会被当作变量，如果变量不存在会输出空值 #set($domain = "example") #set($full_path = "$domain.com") ## 这里$domain是变量，.com是字面量部分 完整路径：$full_path
常见错误用法与正确修正
很多开发者容易犯的错误是混淆变量和字面量的点号处理，比如想要拼接字符串时错误使用点号，或者访问变量属性时忘记变量已经定义。
错误1：用点号拼接字面量字符串
错误写法：想要拼接"test"和".txt"得到"test.txt"，直接写$test.txt，如果$test是未定义的变量，会输出".txt"，如果$test有值会尝试访问其txt属性。
正确写法：使用字符串拼接或者双引号包裹整体字面量。
## 正确拼接方式1：使用双引号包裹完整字面量 #set($file_name = "test.txt") 文件名：$file_name ## 正确拼接方式2：变量和字面量用双引号拼接 #set($prefix = "test") #set($suffix = ".txt") #set($file_name2 = "$prefix$suffix") 文件名：$file_name2
错误2：访问不存在的属性时点号无输出
如果变量对应的对象没有对应的属性或者方法，点号访问会输出空值，不会报错，需要提前确认对象结构。
#set($user = $userService.getUserById(1)) ## 如果User对象没有email属性，这里会输出空值 用户邮箱：$user.email
点号处理的注意事项
- 变量名中不能包含点号，点号只能用于变量之后的属性访问或者方法调用，不能出现在变量定义名称中。
- 如果需要在字面量中输出$符号，需要对$进行转义，写成$ ，避免被Velocity当作变量引用解析。
- 当点号左侧是数字字面量时，点号会被当作小数点处理，比如
$num = 1.5是合法的数字定义，不会触发属性解析。
掌握Velocity中变量和字面量点号的处理规则，能够有效减少模板编写中的低级错误，提升模板渲染的稳定性和正确性。实际使用时可以先明确当前内容的类型，再选择对应的点号使用方式。
Apache_Velocity模板变量字面量点号处理Velocity语法修改时间：2026-07-23 14:39:31