Skip to content

BACKWARD_COMPATIBILITY.md

Latest commit

 

History

History
219 lines (174 loc) · 5.68 KB

BACKWARD_COMPATIBILITY.md

File metadata and controls

219 lines (174 loc) · 5.68 KB

向后兼容性验证

本文档详细说明多主题功能如何保证与现有代码的完全兼容性。

兼容性承诺

✅ 零修改升级: 现有项目无需任何代码修改即可升级
✅ API 完全兼容: 所有现有方法签名和行为保持不变
✅ 性能保证: 传统模式下性能与原版本相同
✅ 目录结构兼容: 现有模板目录结构继续工作

实际验证示例

1. 现有代码示例

以下是典型的现有代码，升级后无需任何修改：

package main

import (
    "net/http"
    "github.com/nilorg/template"
)

func main() {
    // 现有代码 - 无需修改
    engine, err := template.NewEngine("./templates", template.DefaultLoadTemplate, nil)
    if err != nil {
        panic(err)
    }
    engine.Init()

    // 现有路由处理 - 无需修改
    http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
        data := template.H{"title": "Hello World"}
        engine.RenderPage(w, "home", data)
    })

    http.HandleFunc("/login", func(w http.ResponseWriter, r *http.Request) {
        data := template.H{"title": "Login"}
        engine.RenderSingle(w, "login", data)
    })

    http.ListenAndServe(":8080", nil)
}

2. 现有目录结构

# 现有项目结构 - 无需修改
./templates
├── layouts/
│   └── layout.tmpl
├── pages/
│   └── home/
│       └── home.tmpl
├── singles/
│   └── login.tmpl
├── errors/
│   └── 404.tmpl
└── partials/
    └── header.tmpl

3. 现有配置选项

// 现有配置 - 完全兼容
engine, err := template.NewEngine("./templates", template.DefaultLoadTemplate, funcMap,
    template.GlobalConstant(map[string]interface{}{
        "siteName": "My Website",
        "version":  "1.0.0",
    }),
    template.GlobalVariable(map[string]interface{}{
        "year": time.Now().Year(),
    }),
)

自动模式检测

系统会自动检测并选择合适的模式：

传统模式检测

# 当检测到这种结构时，自动使用传统模式
./templates
├── layouts/     # 直接在 templates 下
├── pages/
├── singles/
├── errors/
└── partials/

多主题模式检测

# 当检测到这种结构时，自动使用多主题模式
./templates
├── default/     # 主题目录
│   ├── layouts/
│   ├── pages/
│   └── ...
└── dark/        # 另一个主题目录
    ├── layouts/
    ├── pages/
    └── ...

性能验证

基准测试结果

# 传统模式性能（升级前后对比）
BenchmarkLegacyMode_EngineCreation    3000    380ms/op    52KB/op
BenchmarkLegacyMode_PageRendering     200K    5.0ms/op    1.4KB/op
BenchmarkLegacyMode_ThemeQueries      10M     115ns/op    16B/op

# 结果：性能完全相同，无任何退化

错误处理兼容性

现有错误类型保持不变

// 现有错误处理逻辑无需修改
engine, err := template.NewEngine("./invalid-path", template.DefaultLoadTemplate, nil)
if err != nil {
    // 错误类型和消息格式保持一致
    log.Printf("Engine creation failed: %v", err)
}

err = engine.RenderPage(w, "nonexistent", data)
if err != nil {
    // 模板不存在错误格式保持一致
    http.Error(w, "Template not found", http.StatusInternalServerError)
}

渐进式升级路径

阶段1: 零修改升级

// 只需更新依赖版本，代码无需修改
go get github.com/nilorg/template@latest

// 现有代码继续工作
engine, err := template.NewEngine("./templates", template.DefaultLoadTemplate, funcMap)

阶段2: 可选启用多主题

// 添加多主题支持，现有模板继续工作
engine, err := template.NewEngine("./templates", template.DefaultLoadTemplate, funcMap,
    template.EnableMultiTheme(true),    // 启用多主题
    template.DefaultTheme("default"),   // 设置默认主题
)

阶段3: 逐步迁移到多主题结构

# 创建主题目录，移动现有模板
mkdir templates/default
mv templates/layouts templates/default/
mv templates/pages templates/default/
mv templates/singles templates/default/
mv templates/errors templates/default/
mv templates/partials templates/default/

兼容性测试

自动化测试覆盖

  • ✅ API 方法签名兼容性测试
  • ✅ 现有项目结构兼容性测试
  • ✅ 配置选项兼容性测试
  • ✅ 错误处理兼容性测试
  • ✅ 性能回归测试
  • ✅ 内存使用兼容性测试

测试命令

# 运行兼容性测试套件
go test -v -run TestFinalCompatibilityVerification
go test -v -run TestExistingExampleCompatibility
go test -v -run TestAPIConsistency
go test -v -run TestBackwardCompatibilityExamples

常见问题

Q: 升级后需要修改现有代码吗？

A: 不需要。所有现有代码无需任何修改即可继续工作。

Q: 现有模板文件需要修改吗？

A: 不需要。现有模板文件和目录结构完全兼容。

Q: 性能会受到影响吗？

A: 不会。传统模式下性能与原版本完全相同。

Q: 如何验证兼容性？

A: 运行现有测试套件，所有测试应该继续通过。

Q: 可以部分使用多主题功能吗？

A: 可以。多主题功能是可选的，可以渐进式启用。

总结

多主题功能的设计严格遵循向后兼容性原则：

  1. 零破坏性变更: 没有任何破坏性API变更
  2. 自动检测: 智能检测现有项目结构
  3. 渐进式增强: 新功能作为可选扩展
  4. 性能保证: 传统模式性能不受影响
  5. 完整测试: 全面的兼容性测试覆盖

现有项目可以安全升级，享受新功能的同时保持完全的稳定性。