database_render/docs/template_system.md

模板系统开发文档

概述

本项目实现了一个可扩展的三层模板系统，支持动态模板渲染、热重载、版本管理和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. 启动服务

cd cmd/template_system
go run main.go

2. 访问示例

• 模板管理界面: http://localhost:8080
• API文档: http://localhost:8080/api/templates/health

模板定义

创建自定义模板

1. 基础模板结构

# 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. 获取可用模板

GET /api/templates/available?table=users

2. 获取模板配置

GET /api/templates/config

3. 版本历史

GET /api/templates/versions/{template_name}

4. 创建新版本

POST /api/templates/versions/{template_name}
Content-Type: application/json

{
  "description": "添加搜索功能",
  "author": "developer"
}

5. 回滚版本

POST /api/templates/versions/{template_name}/rollback/{version}

前端渲染API

1. 动态渲染

// 使用前端渲染引擎
const templateEngine = new TemplateEngine();
const result = await templateEngine.render('list', 'users', data);

2. 模板切换

// 切换模板类型
const uiController = new UIController();
await uiController.switchTemplate('card', 'users');

开发特性

热重载

在开发模式下，模板文件变更会自动检测并重载：

1. 启用热重载

config := template.TemplateConfig{
    HotReload: true,
    // ... 其他配置
}

2. 手动重载

POST /api/templates/hotreload/reload

版本管理

1. 自动版本控制

• 每次模板修改自动创建版本
• 支持版本回滚
• 版本历史追踪

2. 版本命令

# 查看版本历史
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. 性能监控

// 启用性能监控
const monitor = new PerformanceMonitor();
monitor.enableTracking();

配置说明

模板类型配置

template_types:
  list:
    layout: "table"
    fields:
      default: "raw"
      time: "time"
      tag: "tag"
    options:
      striped: true
      hover: true

字段类型配置

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. 创建字段模板

<!-- web/templates/builtin/field/new_type.html -->
{{define "field_new_type"}}
<div class="field-new-type">
  {{.Value}}
</div>
{{end}}

2. 注册字段类型

field_types:
  new_type:
    type: "custom"
    renderer: "new_type"

添加新的模板类型

1. 创建模板文件

<!-- web/templates/builtin/new_type.html -->
{{template "layout" .}}

2. 注册模板类型

template_types:
  new_type:
    layout: "new_layout"
    fields: {}

贡献指南

欢迎提交PR和Issue！

1. Fork项目
2. 创建特性分支
3. 添加测试
4. 提交PR

许可证

MIT License