# JVue Template Engine SpringBoot Starter
**Repository Path**: iteachyou/jvue-template-engine-spring-boot-starter
## Basic Information
- **Project Name**: JVue Template Engine SpringBoot Starter
- **Description**: JVue Template Engine SpringBoot Starter 是 JVue Template Engine 的 Spring Boot 自动配置模块
- **Primary Language**: Java
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 10
- **Forks**: 0
- **Created**: 2026-04-24
- **Last Updated**: 2026-05-07
## Categories & Tags
**Categories**: Uncategorized
**Tags**: 模板引擎, jvue
## README
## 📖 简介
`jvue-template-engine-spring-boot-starter` 是 [JVue Template Engine](https://gitee.com/iteachyou/jvue-template-engine) 的 Spring Boot 自动配置模块，提供：
- ✅ **零配置接入**：引入依赖即自动装配，无需手动初始化 `JVueTemplateEngine`
- ✅ **视图解析器集成**：无缝融入 Spring MVC 视图层，兼容 `Model`、`ModelAndView`
- ✅ **自动注入扩展**：自定义指令、方法、过滤器通过 Spring Bean 自动注册
- ✅ **完美兼容Spring Boot 3.x 版本**
- ✅ **模板热重载**（开发模式）
---
## 🚀 快速开始
### 第一步：添加依赖
> `jvue-template-engine-spring-boot-starter` 已传递依赖核心引擎，无需单独引入。
**Maven**
```xml
cc.iteachyou.jvue
jvue-template-engine-spring-boot-starter
1.0.0
```
**Gradle**
```groovy
implementation 'cc.iteachyou.jvue:jvue-template-engine-spring-boot-starter:1.0.0'
```
### 第二步：创建模板文件
在 `src/main/resources/templates/` 目录下新建 `hello.html`：
```html
{{ title }}
{{ greeting }}，{{ user.name }}！
暂无待办事项
```
### 第三步：编写 Controller
```java
@Controller
public class HelloController {
@GetMapping("/hello")
public String hello(Model model) {
model.addAttribute("title", "我的待办");
model.addAttribute("greeting", "你好");
model.addAttribute("user", currentUser());
model.addAttribute("todoList", todoService.list());
return "hello"; // 对应 templates/hello.html
}
}
```
### 第四步：启动项目
```
. ____ _ __ _ _
/\\ / ___'_ __ _ _(_)_ __ __ _ \ \ \ \
( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
\\/ ___)| |_)| | | | | || (_| | ) ) ) )
' |____| .__|_| |_|_| |_\__, | / / / /
=========|_|==============|___/=/_/_/_/
:: Spring Boot :: (v3.2.0)
[JVue] Template engine initialized. prefix=classpath:/templates/ suffix=.html cache=true
```
访问 `http://localhost:8080/hello`，模板即可正确渲染。
---
## ⚙️ 配置项参考
在 `application.yml` 或 `application.properties` 中配置：
```yaml
# ──────────────────────────────────────────────────────
# jvue-template-engine 配置
# ──────────────────────────────────────────────────────
jvue:
template:
prefix: classpath:/templates/vue/ #路径前缀
suffix: .vue.html #模板文件后缀名
cache: true #是否缓存
encoding: UTF-8 #编码
static-methods:
- cc.iteachyou.jvue.demo.JVueStaticTemplateMethods#wrapTag #静态方法注册
- cc.iteachyou.jvue.demo.JVueStaticTemplateMethods#sumTag #静态方法注册
```
**`application.properties` 示例**
```properties
jvue.template.prefix=classpath:/templates/ #路径前缀
jvue.template.suffix=.html #模板文件后缀名
jvue.template.cache=true #是否缓存
jvue.template.encoding=UTF-8 #编码
```
---
## 🎮 在 Controller 中使用
### 标准 MVC 方式（返回视图名）
```java
@Controller
@RequestMapping("/report")
public class ReportController {
@Autowired
private ReportService reportService;
@GetMapping("/{id}")
public String detail(@PathVariable Long id, Model model) {
model.addAttribute("report", reportService.getById(id));
model.addAttribute("charts", reportService.getCharts(id));
return "report/detail"; // → templates/report/detail.html
}
}
```
### 使用 ModelAndView
```java
@GetMapping("/dashboard")
public ModelAndView dashboard() {
ModelAndView mav = new ModelAndView("dashboard/index");
mav.addObject("stats", statsService.summary());
mav.addObject("topUsers", userService.top(10));
return mav;
}
```
### 直接渲染为字符串（程序化调用）
```java
@Autowired
private JVueTemplateEngine jVueTemplateEngine;
public String buildEmailBody(Order order) {
Map model = Map.of(
"name", name,
"vip", vip
);
return jVueTemplateEngine.render("email/order", dataMap);
}
```
### REST 接口中返回渲染结果
```java
@RestController
@RequestMapping("/api/preview")
public class PreviewController {
@Autowired
private JVueEngine jvueEngine;
@PostMapping
public ResponseEntity preview(@RequestBody PreviewRequest req) {
RenderContext ctx = RenderContext.of(req.getData());
String html = jvueEngine.render(req.getTemplate(), ctx);
return ResponseEntity.ok()
.contentType(MediaType.TEXT_HTML)
.body(html);
}
}
```
---
## 🔌 扩展自定义
### 注册自定义指令
```java
@PostConstruct
public void initCustomDirective() {
engine.registerDirective(new JVueDirectiveHandler() {
@Override
public String name() {
return "v-upper";
}
@Override
public String apply(JVueDirectiveAttribute attribute, JVueElementNode node, JVueRenderContext context, JVueTemplateEngine engine) {
Object value = engine.getExpressionEvaluator().evaluate(attribute.value(), context);
String result = value == null ? "" : value.toString().toUpperCase();
return "<" + node.getTagName() + ">" + result + "";
}
});
engine.registerDirective(new JVueDirectiveHandler() {
@Override
public String name() {
return "v-badge";
}
@Override
public String apply(JVueDirectiveAttribute attribute, JVueElementNode node, JVueRenderContext context, JVueTemplateEngine engine) {
Object value = engine.getExpressionEvaluator().evaluate(attribute.value(), context);
String text = value == null ? "" : String.valueOf(value);
return ""
+ text + "";
}
});
}
```
**模板中使用**
```html
```
---
### 注册自定义方法
实现 `JVueFunctionRegistrar` 接口：
```java
package cc.iteachyou.jvue.demo;
import cc.iteachyou.jvue.eval.JVueMethod;
import org.springframework.stereotype.Component;
@Component
public class JVueDemoTemplateMethods {
@JVueMethod(namespace = "str")
public String maskName(String value) {
if (value == null || value.isEmpty()) {
return "";
}
if (value.length() == 1) {
return value + "*";
}
return value.charAt(0) + "***" + value.charAt(value.length() - 1);
}
@JVueMethod(value = "join", namespace = "str")
public String joinTwo(String a, String b) {
return a + " | " + b;
}
@JVueMethod(value = "join", namespace = "str")
public String joinThree(String a, String b, double c) {
return a + " | " + b + " | " + c;
}
@JVueMethod(namespace = "str")
public String words(String... parts) {
if (parts == null || parts.length == 0) {
return "";
}
return String.join(" -> ", parts);
}
}
```
**模板中使用**
```html
```
## 🧩 自动装配原理
```
Spring Boot 启动
│
├─ 扫描 META-INF/spring/AutoConfiguration.imports
│ └─ JVueTemplateAutoConfiguration
│
├─ 读取 JVueTemplateProperties (jvue.template.*)
│
├─ 创建 JVueTemplateEngine Bean
│
├─ 扫描 自定义指令 / 自定义静态方法
│ / 非静态方法 / 表达式引擎
│ └─ 自动注册到 JVueTemplateEngine
│
└─ 注册 JVueTemplateViewResolver（集成 Spring MVC 视图层）
```
---
## 🔄 版本兼容性
| Starter 版本 | JVue Engine | Spring Boot | JDK |
|-------------|-------------|-------------|-----|
| 1.0.x | 1.0.x | 3.x.x | 17+ |
> Spring Boot 3.x 需要 JDK 17+。
---
## ❓ 常见问题
**Q：模板修改后不生效？**
开发环境请设置 `jvue.template.cache=false`。
**Q：如何在非 Web 场景（如定时任务、消息队列）中使用？**
直接创建 `JVueTemplateEngine` Bean 调用 `render()` 即可，不依赖 HTTP 上下文。
**Q：表达式中能调用 Spring Bean 的方法吗？**
不能直接调用，需通过静态方法注册或使用 `@JVueMethod` 注解，然后在模板中使用。
---
## 🤝 参与贡献
欢迎提交 Issue 和 Pull Request！
1. Fork 本仓库
2. 创建功能分支：`git checkout -b feat/my-feature`
3. 提交修改：`git commit -m 'feat: add my feature'`
4. 推送分支：`git push origin feat/my-feature`
5. 提交 Pull Request
---
## 🔗 相关项目
| 项目 | 说明 |
|------|------|
| [jvue-template-engine](https://gitee.com/iteachyou/jvue-template-engine) | 核心模板引擎 |
| [jvue-template-engine-spring-boot-starter](https://gitee.com/iteachyou/jvue-template-engine-spring-boot-starter) | 本项目 · Spring Boot 自动配置 |
---
## 📄 开源协议
本项目基于 [MIT](LICENSE) 开源。
---