feat: update auto render
This commit is contained in:
329
docs/template_system.md
Normal file
329
docs/template_system.md
Normal file
@@ -0,0 +1,329 @@
|
||||
# 模板系统开发文档
|
||||
|
||||
## 概述
|
||||
|
||||
本项目实现了一个可扩展的三层模板系统，支持动态模板渲染、热重载、版本管理和YAML配置。
|
||||
|
||||
## 架构设计
|
||||
|
||||
### 三层模板架构
|
||||
|
||||
1. **布局模板 (Layout Template)**
|
||||
- 基础布局结构，固定不变
|
||||
- 提供响应式设计框架
|
||||
- 包含核心CSS和JS引用
|
||||
|
||||
2. **列表模板 (List Template)**
|
||||
- 可扩展的列表/表格/卡片视图模板
|
||||
- 支持多种展示模式：table、card、timeline
|
||||
- 模板继承自布局模板
|
||||
|
||||
3. **字段模板 (Field Template)**
|
||||
- 独立的字段渲染器
|
||||
- 支持多种数据类型：string、time、tag、markdown等
|
||||
- 可插拔式设计
|
||||
|
||||
### 核心组件
|
||||
|
||||
#### 1. TemplateLoader (模板加载器)
|
||||
- 负责模板加载和缓存管理
|
||||
- 支持三层模板架构
|
||||
- 提供模板验证和错误处理
|
||||
|
||||
#### 2. VersionManager (版本管理器)
|
||||
- 模板版本控制
|
||||
- 自动备份和回滚
|
||||
- 版本历史记录
|
||||
|
||||
#### 3. HotReloadWatcher (热重载监听器)
|
||||
- 文件变更自动检测
|
||||
- 实时模板更新
|
||||
- 开发模式优化
|
||||
|
||||
#### 4. ConfigLoader (配置加载器)
|
||||
- YAML配置文件解析
|
||||
- 模板类型定义
|
||||
- 字段渲染器配置
|
||||
|
||||
## 使用指南
|
||||
|
||||
### 快速开始
|
||||
|
||||
1. **启动服务**
|
||||
```bash
|
||||
cd cmd/template_system
|
||||
go run main.go
|
||||
```
|
||||
|
||||
2. **访问示例**
|
||||
- 模板管理界面: http://localhost:8080
|
||||
- API文档: http://localhost:8080/api/templates/health
|
||||
|
||||
### 模板定义
|
||||
|
||||
#### 创建自定义模板
|
||||
|
||||
1. **基础模板结构**
|
||||
```yaml
|
||||
# config/templates.yaml
|
||||
templates:
|
||||
my_table:
|
||||
name: "我的表"
|
||||
type: "list"
|
||||
description: "自定义表视图"
|
||||
fields:
|
||||
id: "number"
|
||||
name: "string"
|
||||
created_at: "time"
|
||||
config:
|
||||
page_size: 10
|
||||
show_search: true
|
||||
```
|
||||
|
||||
2. **模板文件位置**
|
||||
```
|
||||
web/templates/
|
||||
├── builtin/ # 内置模板
|
||||
│ ├── layout.html # 基础布局
|
||||
│ ├── list.html # 列表模板
|
||||
│ └── field/ # 字段模板
|
||||
├── custom/ # 自定义模板
|
||||
│ ├── _default/ # 默认模板
|
||||
│ └── {table_name}/ # 特定表模板
|
||||
└── config/templates.yaml # 模板配置
|
||||
```
|
||||
|
||||
### API接口
|
||||
|
||||
#### 模板管理API
|
||||
|
||||
1. **获取可用模板**
|
||||
```http
|
||||
GET /api/templates/available?table=users
|
||||
```
|
||||
|
||||
2. **获取模板配置**
|
||||
```http
|
||||
GET /api/templates/config
|
||||
```
|
||||
|
||||
3. **版本历史**
|
||||
```http
|
||||
GET /api/templates/versions/{template_name}
|
||||
```
|
||||
|
||||
4. **创建新版本**
|
||||
```http
|
||||
POST /api/templates/versions/{template_name}
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"description": "添加搜索功能",
|
||||
"author": "developer"
|
||||
}
|
||||
```
|
||||
|
||||
5. **回滚版本**
|
||||
```http
|
||||
POST /api/templates/versions/{template_name}/rollback/{version}
|
||||
```
|
||||
|
||||
#### 前端渲染API
|
||||
|
||||
1. **动态渲染**
|
||||
```javascript
|
||||
// 使用前端渲染引擎
|
||||
const templateEngine = new TemplateEngine();
|
||||
const result = await templateEngine.render('list', 'users', data);
|
||||
```
|
||||
|
||||
2. **模板切换**
|
||||
```javascript
|
||||
// 切换模板类型
|
||||
const uiController = new UIController();
|
||||
await uiController.switchTemplate('card', 'users');
|
||||
```
|
||||
|
||||
### 开发特性
|
||||
|
||||
#### 热重载
|
||||
|
||||
在开发模式下，模板文件变更会自动检测并重载：
|
||||
|
||||
1. **启用热重载**
|
||||
```go
|
||||
config := template.TemplateConfig{
|
||||
HotReload: true,
|
||||
// ... 其他配置
|
||||
}
|
||||
```
|
||||
|
||||
2. **手动重载**
|
||||
```http
|
||||
POST /api/templates/hotreload/reload
|
||||
```
|
||||
|
||||
#### 版本管理
|
||||
|
||||
1. **自动版本控制**
|
||||
- 每次模板修改自动创建版本
|
||||
- 支持版本回滚
|
||||
- 版本历史追踪
|
||||
|
||||
2. **版本命令**
|
||||
```bash
|
||||
# 查看版本历史
|
||||
curl http://localhost:8080/api/templates/versions/{template_name}
|
||||
|
||||
# 回滚到指定版本
|
||||
curl -X POST http://localhost:8080/api/templates/versions/{template_name}/rollback/{version}
|
||||
```
|
||||
|
||||
### 性能优化
|
||||
|
||||
#### 缓存策略
|
||||
|
||||
1. **模板缓存**
|
||||
- LRU缓存机制
|
||||
- 可配置缓存大小
|
||||
- 支持缓存清除
|
||||
|
||||
2. **前端缓存**
|
||||
- 模板结果缓存5分钟
|
||||
- 智能缓存失效
|
||||
- 内存优化
|
||||
|
||||
#### 预加载
|
||||
|
||||
1. **模板预加载**
|
||||
- 常用模板预加载
|
||||
- 延迟加载策略
|
||||
- 按需加载
|
||||
|
||||
2. **性能监控**
|
||||
```javascript
|
||||
// 启用性能监控
|
||||
const monitor = new PerformanceMonitor();
|
||||
monitor.enableTracking();
|
||||
```
|
||||
|
||||
### 配置说明
|
||||
|
||||
#### 模板类型配置
|
||||
|
||||
```yaml
|
||||
template_types:
|
||||
list:
|
||||
layout: "table"
|
||||
fields:
|
||||
default: "raw"
|
||||
time: "time"
|
||||
tag: "tag"
|
||||
options:
|
||||
striped: true
|
||||
hover: true
|
||||
```
|
||||
|
||||
#### 字段类型配置
|
||||
|
||||
```yaml
|
||||
field_types:
|
||||
string:
|
||||
type: "text"
|
||||
renderer: "text"
|
||||
validation:
|
||||
max_length: 100
|
||||
|
||||
time:
|
||||
type: "datetime"
|
||||
renderer: "time"
|
||||
formatting:
|
||||
format: "2006-01-02 15:04:05"
|
||||
```
|
||||
|
||||
### 最佳实践
|
||||
|
||||
1. **模板组织**
|
||||
- 保持模板简单，专注单一功能
|
||||
- 使用语义化的模板名称
|
||||
- 合理利用模板继承
|
||||
|
||||
2. **性能优化**
|
||||
- 启用模板缓存
|
||||
- 使用CDN加载静态资源
|
||||
- 压缩模板文件
|
||||
|
||||
3. **版本管理**
|
||||
- 定期清理旧版本
|
||||
- 使用有意义的版本描述
|
||||
- 测试版本回滚功能
|
||||
|
||||
### 故障排除
|
||||
|
||||
#### 常见问题
|
||||
|
||||
1. **模板加载失败**
|
||||
- 检查文件路径权限
|
||||
- 验证模板语法
|
||||
- 查看错误日志
|
||||
|
||||
2. **热重载不工作**
|
||||
- 确认文件权限
|
||||
- 检查文件监听限制
|
||||
- 查看系统日志
|
||||
|
||||
3. **版本回滚失败**
|
||||
- 检查版本文件是否存在
|
||||
- 确认版本标识符正确
|
||||
- 验证文件权限
|
||||
|
||||
### 扩展开发
|
||||
|
||||
#### 添加新的字段渲染器
|
||||
|
||||
1. **创建字段模板**
|
||||
```html
|
||||
<!-- web/templates/builtin/field/new_type.html -->
|
||||
{{define "field_new_type"}}
|
||||
<div class="field-new-type">
|
||||
{{.Value}}
|
||||
</div>
|
||||
{{end}}
|
||||
```
|
||||
|
||||
2. **注册字段类型**
|
||||
```yaml
|
||||
field_types:
|
||||
new_type:
|
||||
type: "custom"
|
||||
renderer: "new_type"
|
||||
```
|
||||
|
||||
#### 添加新的模板类型
|
||||
|
||||
1. **创建模板文件**
|
||||
```html
|
||||
<!-- web/templates/builtin/new_type.html -->
|
||||
{{template "layout" .}}
|
||||
```
|
||||
|
||||
2. **注册模板类型**
|
||||
```yaml
|
||||
template_types:
|
||||
new_type:
|
||||
layout: "new_layout"
|
||||
fields: {}
|
||||
```
|
||||
|
||||
### 贡献指南
|
||||
|
||||
欢迎提交PR和Issue！
|
||||
|
||||
1. Fork项目
|
||||
2. 创建特性分支
|
||||
3. 添加测试
|
||||
4. 提交PR
|
||||
|
||||
## 许可证
|
||||
|
||||
MIT License
|
||||
Reference in New Issue
Block a user