# JVue Template Engine

**Repository Path**: iteachyou/jvue-template-engine

## Basic Information

- **Project Name**: JVue Template Engine
- **Description**: JVue Template Engine 是一款纯 Java 开发的高性能模板引擎，将前端开发者熟悉的 Vue 模板语法引入到 Java 服务端渲染场景中。无需学习新语法，开箱即用，让 Java 开发者也能享受 Vue 风格的模板体验。
- **Primary Language**: Java
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 15
- **Forks**: 0
- **Created**: 2026-04-24
- **Last Updated**: 2026-06-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: jvue, 模板引擎

## README

## JVue Template Engine

[![JDK](https://img.shields.io/badge/JDK-17%2B-blue)](https://openjdk.org/)
[![License](https://img.shields.io/badge/License-MIT-green)](LICENSE)
[![Version](https://img.shields.io/badge/version-1.0.2-orange)](https://gitee.com/iteachyou/jvue-template-engine)

## 简介

**JVue Template Engine** 是一款纯 Java 开发的高性能模板引擎，将前端开发者熟悉的 [Vue](https://vuejs.org/) 模板语法引入到 Java 服务端渲染（SSR）场景中。无需学习新语法，开箱即用，让 Java 开发者也能享受 Vue 风格的模板体验。

> **核心理念：用 Vue 写模板，用 Java 跑引擎。**

```html
<!-- 这就是一个完整的 JVue 模板 -->
<div>
  <h1>{{ title }}</h1>
  <ul>
    <li v-for="item in items" :key="item.id">
      <span v-if="item.active">✅ {{ item.name }}</span>
      <span v-else>❌ {{ item.name }}</span>
    </li>
  </ul>
  <p>共 {{ items.length }} 条记录</p>
</div>
```

---

## 功能特性

| 类别 | 特性 | 状态 |
|------|------|------|
| 🎯 **Vue 指令** | `v-if` / `v-else-if` / `v-else` 条件渲染 | ✅ |
| 🔄 **列表渲染** | `v-for` 支持 List / Map / 带索引遍历 | ✅ |
| 🔗 **属性绑定** | `:href`、`:class`（对象/数组）、`:style` 动态绑定 | ✅ |
| 👁️ **显示控制** | `v-show`（渲染为 `display:none`） | ✅ |
| 📝 **内容指令** | `v-text` / `v-html` / `v-pre` | ✅ |
| 🔌 **自定义指令** | 通过 `JVueDirectiveHandler` 注册任意自定义指令 | ✅ |
| 🧮 **插值表达式** | `{{ }}` 支持算术运算、三元表达式、属性访问、链式调用 | ✅ |
| 🛠️ **自定义方法** | 注册 Java 方法，在模板表达式中直接调用 | ✅ |
| 📦 **模板包含** | `<include src="name"/>` + `v-include` 动态包含 | ✅ |
| 🚀 **多源加载** | Classpath / 文件系统 / 组合加载器（按优先级链 fallback） | ✅ |
| 💾 **编译缓存** | AST 级缓存 + ConcurrentHashMap 线程安全 | ✅ |
| 🔒 **XSS 防护** | 插值默认 HTML 转义，`v-html` 可控输出 | ✅ |
| 🛡️ **路径穿越防护** | FileLoader / ClasspathLoader 均拒绝 `../` 越界访问 | ✅ |
| 🧩 **零运行时依赖** | 纯 Java 实现，无第三方库依赖 | ✅ |
| ☕ **JDK 兼容** | 要求 Java 17 及以上版本 | ✅ |

---

## 快速开始

### 添加依赖

**Maven**

```xml
<dependency>
  <groupId>cc.iteachyou.jvue</groupId>
  <artifactId>jvue-template-engine</artifactId>
  <version>1.0.2</version>
</dependency>
```

**Gradle**

```groovy
implementation 'cc.iteachyou.jvue:jvue-template-engine:1.0.2'
```

### 5 分钟上手

```java
import cc.iteachyou.jvue.JVueTemplateEngine;
import java.util.*;

// 1. 准备模板
String template = "<div>"
    + "<p v-if=\"vip\">VIP 用户</p>"
    + "<ul><li v-for=\"item in items\">{{ item }}</li></ul>"
    + "<a :href=\"link\">跳转</a>"
    + "<script src=\"/resources/js/jquery.min.js\"></script>"
    + "</div>";

// 2. 创建引擎实例（传入模板加载器）
JVueTemplateEngine engine = new JVueTemplateEngine(
    name -> {
        if ("index".equals(name)) return template;
        throw new IllegalArgumentException("未找到模板: " + name);
    }
);

// 3. 渲染输出
String html = engine.render("index", Map.of(
    "vip", true,
    "items", List.of("Apple", "Banana"),
    "link", "/home"
));
```

---

## 语法参考

### 插值表达式 `{{ }}`

```html
<!-- 基本变量 -->
<p>{{ username }}</p>

<!-- 算术运算 -->
<p>合计：{{ price * quantity }}</p>

<!-- 三元表达式 -->
<p>{{ isVip ? '尊享会员' : '普通用户' }}</p>

<!-- 对象属性链 -->
<p>{{ user.address.city }}</p>
```

### 条件渲染 `v-if / v-else-if / v-else`

```html
<div v-if="score >= 90">优秀</div>
<div v-else-if="score >= 60">及格</div>
<div v-else>不及格</div>
```

### 列表渲染 `v-for`

```html
<!-- 遍历列表 -->
<li v-for="item in list" :key="item.id">{{ item.name }}</li>

<!-- 带索引 -->
<li v-for="(item, index) in list">{{ index + 1 }}. {{ item.name }}</li>

<!-- 遍历 Map -->
<li v-for="(value, key) in map">{{ key }}: {{ value }}</li>
```

### 属性绑定

```html
<img :src="imageUrl" />
<div :class="{ active: isActive }">动态类名</div>
<div :class="[baseClass, extraClass]">数组类名</div>
<p :style="{ color: themeColor }">动态样式</p>
```

### 其他内置指令

| 指令 | 说明 |
|------|------|
| `v-show="expr"` | 控制可见性（渲染为 `display:none`） |
| `v-text="expr"` | 设置文本内容 |
| `v-html="raw"` | 输出原始 HTML（注意 XSS） |
| `v-pre` | 跳过该节点编译 |
| `v-cloak` | 标记未编译节点 |

### 模板包含

```html
<!-- 静态包含 -->
<include src="footer"/>

<!-- 动态包含 -->
<div include="templateName"></div>
```

### 自定义指令

```java
engine.registerDirective(new JVueDirectiveHandler() {
    @Override public String name() { return "v-upper"; }

    @Override
    public String apply(JVueDirectiveAttribute attr,
                        JVueElementNode node,
                        JVueRenderContext ctx,
                        JVueTemplateEngine e) {
        Object val = e.getExpressionEvaluator().evaluate(attr.value(), ctx);
        return "<" + node.getTagName() + ">" +
               String.valueOf(val).toUpperCase() +
               "</" + node.getTagName() + ">";
    }
});
// 模板：<span v-upper="name"/> → <SPAN>CURSOR</SPAN>
```

### 自定义方法

```java
engine.registerMethod("upper", args ->
    String.valueOf(args.get(0)).toUpperCase()
);
// 模板：<p>{{ upper(name) }}</p> → <p>CURSOR</p>
```

### 多源模板加载

```java
// 组合加载器：优先磁盘 → fallback 到 classpath
JVueCompositeTemplateLoader loader = new JVueCompositeTemplateLoader(
    new JVueFileTemplateLoader(Path.of("/var/templates")),
    new JVueClasspathTemplateLoader("templates/")
);
JVueTemplateEngine engine = new JVueTemplateEngine(loader);
```

---

## 安全机制

### XSS 防护（插值默认转义）

```java
engine.render("x", Map.of("input", "<script>alert('xss')</script>"));
// 输出: &lt;script&gt;alert(&#39;xss&#39;)&lt;/script&gt;  ← 已自动转义
```

### 路径穿越防护

```java
FileLoader loader = new JVueFileTemplateLoader(baseDir);
loader.load("../../etc/passwd");  // ❌ 抛出 IllegalStateException
loader.load("../secret.txt");     // ❌ 抛出 IllegalStateException
loader.load("normal.html");       // ✅ 正常返回
```

---

## 与 Spring Boot 集成

推荐使用配套的 [jvue-template-engine-spring-boot-starter](https://gitee.com/iteachyou/jvue-template-engine-spring-boot-starter) 实现零配置接入：

```xml
<dependency>
  <groupId>cc.iteachyou.jvue</groupId>
  <artifactId>jvue-template-engine-spring-boot-starter</artifactId>
  <version>1.0.1</version>
</dependency>
```

```yaml
# application.yml
jvue:
  template:
    prefix: classpath:/templates/
    suffix: .html
    cache: true
    encoding: UTF-8
```

详细用法请查看 [Starter 文档](https://gitee.com/iteachyou/jvue-template-engine-spring-boot-starter) 和 [在线 Demo](https://gitee.com/iteachyou/jvue-template-engine-spring-boot-starter-demo)。

---

## 性能基准

测试环境：JDK 17 · 4 核 CPU

| 场景 | 模板大小 | QPS（约） | 平均耗时 |
|------|---------|----------|---------|
| 简单插值（10 变量） | ~500B | ~850K | < 0.2ms |
| 中等复杂度（v-for × 50） | ~2KB | ~120K | < 1ms |
| 复杂嵌套（多层 v-for + v-if） | ~10KB | ~28K | ~4ms |

> 模板编译结果会被 AST 缓存，重复渲染无编译开销。

---

## 版本历史

| 版本 | 更新内容 |
|------|---------|
| **1.0.2** | 🔧 修复 `<script>` 标签属性（src/type 等）丢失问题；增强安全性 |
| **1.0.1** | 🛡️ 路径遍历防护、XSS 默认转义、线程安全缓存、除零保护 |
| **1.0.0** | 🎉 首个正式发布：核心 Vue 指令、插值引擎、自定义扩展 |

---

## 参与贡献

欢迎提交 Issue 和 Pull Request！

1. Fork 本仓库
2. 创建功能分支：`git checkout -b feat/amazing-feature`
3. 提交修改：`git commit -m 'feat: add amazing feature'`
4. 推送分支：`git push origin feat/amazing-feature`
5. 提交 Pull Request

请确保代码通过全部单元测试（当前 **33 个测试全部通过**）。

---

## 开源协议

本项目基于 [MIT](LICENSE) 协议开源，可免费用于商业和非商业项目。

---

<div align="center">

**Made with ❤️ by [I Teach You](https://gitee.com/iteachyou)**

If this project helps you, please give it a ⭐

</div>